Pi Coding Agent 1.0 使用教程：安装、接入模型（含 Ollama 本地模型）并跑通第一个任务

Name

Soren Atelier

更新于 2026/10/4

简短回答：安装 Pi，进入项目目录，登录，然后把任务交给它。

curl -fsSL https://pi.dev/install.sh | sh
cd /path/to/project
pi

进入 Pi 后输入 /login，选择一种接入方式：Claude、ChatGPT 或 GitHub Copilot 订阅，API Key，或者本地模型。然后用自然语言描述任务即可。Windows 上把第一行换成 powershell -c "irm https://pi.dev/install.ps1 | iex"。

Pi 是 Earendil Works 开发的一款极简、开源（MIT 协议）的终端编程智能体。1.0 版于 2026 年 10 月 1 日发布，到 10 月 4 日已更新到 1.0.2。仓库在 GitHub 上有超过 112,000 个 star，1.0 发布帖在 Hacker News 上拿到 1,678 分。官方称每周用户有数十万。

开始之前先记住一点：Pi 在运行命令或修改文件前不会征求你的同意。它以你当前用户账号的全部权限运行。这是它和 Claude Code、Codex 最大的区别，也决定了你应该怎么配置它。具体做法见下文「第一天就该改的安全默认设置」一节。

实测范围：2026 年 10 月 4 日，我们在 macOS（Apple M4 Max，Node.js 22.20）上通过 npm 安装了 Pi 1.0.2，并通过 Ollama 接入本地 qwen3-vl:8b 模型。我们实际跑了一个写文件任务、一次只读运行、一次 AGENTS.md 加载检查和一次会话导出。我们没有测试 /login 订阅登录流程、交互式全屏 TUI、MCP 服务器、codemode 和第三方包。这些部分的内容来自 1.0.2 自带的官方文档和 Pi 1.0 发布公告 (opens in a new tab)。

Pi 是什么，适合谁

Pi 的自我定位是「一个极简、可扩展、可以按你自己的方式改造的智能体框架（agent harness）」。实际上它分两层：

• 一个编程智能体 CLI（pi），内置七个工具：read、bash、edit、write，以及默认关闭的 grep、find、ls。
• 底层的一套工具包：多模型供应商的 LLM 库（pi-ai）、智能体运行时、终端 UI 库和 TypeScript SDK。其他项目基于它们构建，最有名的是 OpenClaw。

Pi 有意砍掉了很多功能。它没有内置子智能体，也没有 plan 模式。官方的态度是：「让 Pi 自己把你想要的东西做出来，或者装一个按你习惯实现的包。」如果你想要开箱即用、打磨完整的产品，Claude Code、Codex 或 OpenCode 更合适。Pi 适合这样的人：想要一个小而可读的智能体循环，几乎能接任何模型，并且愿意自己动手扩展。

第 1 步：安装 Pi

有四种安装方式：

我们用的是带 --ignore-scripts 的 npm 安装，共装了 121 个包，耗时 26 秒：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

pi --version 输出 1.0.2。

安装时的坑：

• Node.js 版本太旧。Pi 需要 Node 22.19 或更高版本。如果你还在 Node 20，要么用自带 Node 的安装脚本，要么先升级 Node。
• 过时的教程。很多 1.0 之前的教程指向 badlogic/pi-mono 和 @mariozechner/... 这个 npm scope。现在的仓库是 earendil-works/pi (opens in a new tab)，包名是 @earendil-works/pi-coding-agent。
• Windows 的 shell。原生 Windows 版 Pi 通过 Git Bash 执行 bash 工具。如果在 Pi 里运行 !printf 'Bash is working\n' 失败，请安装 Git for Windows，或者在 ~/.pi/agent/settings.json 里设置 shellPath。

第 2 步：配置模型

Pi 必须能连上一个模型才能工作。有三种方式。

方式 A：通过 /login 使用订阅或 API Key

在项目目录里启动 pi，然后输入：

/login

在 Pi 1.0.2 中，/login 的供应商列表包括 Anthropic（Claude Pro/Max）、OpenAI（ChatGPT Plus/Pro）、GitHub Copilot、xAI、Kimi Code 和 Meta，另外还有大量供应商支持 API Key 登录。凭据保存在 ~/.pi/agent/auth.json。这个文件不要外泄，也不要提交到仓库。之后可以用 /model 切换模型，或者按 Ctrl+P 在 --models 指定的模型之间轮换。

订阅登录我们没有实测。在第三方工具里使用个人订阅之前，请先确认供应商的服务条款。

方式 B：环境变量

这是适合 CI 的方式。Pi 读取常见的变量名：

export ANTHROPIC_API_KEY=sk-ant-...
pi --model sonnet "Explain how this repo is structured"

其他变量名同理：OPENAI_API_KEY、GEMINI_API_KEY、DEEPSEEK_API_KEY、OPENROUTER_API_KEY、GROQ_API_KEY 等。完整列表用 pi --help 查看。用 pi auth check --provider <name> 可以在不启动会话的情况下确认某个供应商是否配置好。

方式 C：通过 Ollama 接入本地模型（已实测）

Pi 内置支持 llama.cpp router（/llama 命令）。如果用 Ollama、LM Studio、vLLM 或任何兼容 OpenAI 接口的服务，需要自己把服务加到 ~/.pi/agent/models.json。下面是我们实际使用的文件：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "qwen3-vl:8b" }
      ]
    }
  }
}

apiKey 是个占位值，Ollama 会忽略它，但 Pi 需要这里有值才会把模型视为可用。检查 Pi 能否看到这个模型：

pi --list-models qwen

输出为 ollama qwen3-vl:8b 128K ...。Pi 显示的上下文窗口是 128K，而 Ollama 报告这个模型是 262K。除非你在 models.json 里设置上限，否则 Pi 会使用自己的默认值。

第 3 步：跑通第一个任务

在交互模式下，直接输入任务，用 @ 选择文件。如果要写脚本调用 Pi 或测试模型，用 print 模式（-p）：Pi 执行完任务就退出。

我们的测试项目里只有一个六行的 sales.csv。提示词如下：

pi --model ollama/qwen3-vl:8b -p "Read sales.csv. Write a Python script growth.py that uses only the standard library csv module to print each region's month-over-month sales change in percent. Then run it with python3 and show the output."

会话日志记录了整个过程：

1. 第 1 轮：Pi 调用 read 读取 sales.csv。
2. 第 2 轮：调用 write 创建 growth.py，再调用 bash 运行。8B 模型在文件里写入了字面量的 \n 转义序列，Python 报了 SyntaxError。
3. 第 3 轮：Pi 读取报错，正确重写文件后再次运行。
4. 第 4 轮：输出结果：

north: 2026-07 to 2026-08 → 12.50%
south: 2026-07 to 2026-08 → -11.11%
east: 2026-07 to 2026-08 → 58.33%

三个数字都正确。在笔记本 GPU 上整个运行耗时 6 分 54 秒，大部分时间花在一个很长的「思考」轮次上（约 12,000 个输出 token）。换成云端前沿模型，同样的任务几秒就能完成。这次本地运行证明了这套配置可以离线、零 API 成本地跑通，但不能说明本地 8B 模型足以胜任日常编程。

Pi 在写文件和运行 python3 之前都没有询问。这是默认行为，不是 bug。

第一天就该改的安全默认设置

Pi 的安全文档 (opens in a new tab)写得很直白：Pi「不会在每次工具调用前请求批准」。文档还指出，盯着对话记录看并不构成安全边界。下面三个习惯可以弥补这一点。

1. 审查类工作使用只读工具集。--tools 是白名单，下面这次运行只能读，不能写也不能执行：

pi --tools read,grep,find,ls -p "Review the code in src/ and list risky functions"

我们实测过。让 Pi 创建文件时，它回复说自己没有任何能写文件的工具。整个运行耗时 11.5 秒，目录没有任何变化。

2. 无人值守或不受信任的任务放进沙箱。文档给了三种做法：Gondolin 扩展（Pi 的工具在本地 Linux 微型虚拟机里运行）、普通 Docker，以及 NVIDIA OpenShell。在让 Pi 处理不是你自己写的仓库，或者让它长时间独自运行之前，先选一种用上。

3. 把包和项目目录当作代码对待。Pi 包可以包含会执行代码的扩展。项目里的 .pi/settings.json 只有在你授予项目信任（project trust）后才会加载。执行 pi install 安装第三方包之前先读一遍源码；刚 clone 下来的目录，拒绝信任。

指令文件、会话与成本

• AGENTS.md 和 CLAUDE.md。Pi 会从 agent 目录、当前工作目录及其上级目录加载这两个文件，不需要项目信任。我们用一条单行的 AGENTS.md 规则做了测试，模型遵守了。AGENTS.override.md 会替换同一目录下的该文件。如果你已经在给其他智能体维护 AGENTS.md，Pi 可以直接复用。怎么写一份所有工具通用的文件，可以参考我们的 Claude Code AGENTS.md 配置指南。
• 会话自动保存。运行 pi --continue 恢复当前目录最近的会话，或用 /resume 选择一个。会话以 JSONL 文件保存在 ~/.pi/agent/sessions/ 下。
• 导出会话。在我们的测试中，pi --export <session.jsonl> out.html 生成了一个 390 KB 的独立 HTML 对话记录，适合用于代码评审或提交 bug 报告。
• 关注成本。底部状态栏实时显示 token 用量和费用，/session 显示当前会话的统计。Pi 1.0 还为 Anthropic 模型加入了缓存预热，长会话中重复提示词的成本会更低。

进阶：MCP、codemode 与包

以下功能来自官方文档，我们没有实测。

MCP 服务器。在 shell 里添加并检查服务器，然后启动 Pi：

pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list

如果要从 Claude Code、Claude Desktop 或 Cursor 迁移服务器，可以把它们的 mcpServers 条目几乎原样粘贴到 Pi 的 mcp.json。来自 Codex TOML 或 OpenCode local/remote 块的条目需要先转换格式。

Codemode。1.0 新增功能。模型编写一段 JavaScript 脚本，在 QuickJS 沙箱里调用 Pi 的工具、MCP 工具以及非 LLM 模型（比如 Jev 风格的决策模型这类分类器，或图像模型）。只有脚本的输出会返回给模型。在 ~/.pi/agent/settings.json 中开启：

{
  "defaultTools": ["+codemode"]
}

包。扩展、skills、提示词模板和主题都以 npm 或 git 包的形式分发：

pi install npm:@example/pi-tools@1.0.0
pi -e npm:@example/pi-tools

第一行是永久安装。第二行只在本次运行中加载，不改动你的设置，试用新包时更安全。子智能体和 plan 模式目前只有社区包提供。

常见问题排查

Pi 在数据工作流中的位置

Pi 很适合处理脚本和代码仓库。Notebook 就难一些：.ipynb 本质是 JSON，仓库型智能体只能把单元格源码当文本编辑，看不到实时的内核状态，比如加载了哪些 DataFrame、上一个单元格输出了什么。如果你的大部分工作在 Jupyter 里，像 RunCell (opens in a new tab) 这样的 Notebook 原生智能体可以直接运行单元格并读取输出，更适合这类工作流。常见的分工是：仓库交给 Pi，探索性分析交给 Notebook 智能体。

常见问题

相关指南

• OpenCode 使用指南
• Codex 使用指南
• Claude Code AGENTS.md 配置指南
• DeepSeek Harness 安装教程
• NemoClaw vs OpenClaw vs ZeroClaw vs Pi Agent vs Nanobot
• 2026 年最佳 AI 编程工具