Pi Coding Agent 快速入门指南

Pi 是一款强调极简、快速和可扩展的终端编程 Agent。它默认只提供文件读写、编辑和命令执行四类核心工具，将 MCP、子代理、权限确认等能力交给扩展系统处理。对于希望控制上下文成本、复用现有 CLI 工具并深度定制工作流的开发者，Pi 值得尝试；如果更看重开箱即用、图形界面或企业权限管理，Claude Code、Codex 等成熟工具可能更合适。

0、Pi 是什么来头

Pi 的作者 Mario Zechner 是奥地利开发者，也是跨平台游戏开发框架 libGDX 的作者。Pi 最初源于他对重型编程 Agent 的反思：当工具不断增加功能、系统提示词和工具定义频繁变化时，模型行为与既有工作流也容易受到影响。

Pi 因此选择了一条不同的路线：保持核心精简，把个性化能力交给用户和扩展。其定位可以概括为“极简终端编程 Agent”，也就是负责承载和运行 Coding Agent 的 harness。

Pi 还被用于 OpenClaw 的底层 Agent 集成。在 OpenClaw 的依赖中可以看到 @earendil-works/pi-tui，这也让更多开发者开始关注 Pi 本身。

1、安装与登录

使用 npm 全局安装 Pi：

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

Linux 和 macOS 也可以使用官方安装脚本：

curl -fsSL https://pi.dev/install.sh | sh

其中，--ignore-scripts 用于禁止依赖包执行生命周期脚本。按照项目文档的建议添加该参数，可以减少不必要的供应链风险。

安装完成后，在终端运行：

pi

进入交互界面后，通过 /login 配置模型。主要有以下两种方式。

订阅账号登录

Pi 支持通过 OAuth 接入 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot 和 Grok 等服务。

需要注意，不同厂商对第三方 Agent 工具的计费政策可能不同。例如，Claude 订阅账号在第三方 harness 中的调用可能进入额外用量计费，而不是直接占用订阅套餐额度。实际使用前应查看对应服务商最新的计费说明。

API Key 接入

也可以直接配置模型服务商提供的 API Key。Pi 内置支持多家模型提供商，包括 DeepSeek、智谱 Coding Plan、Kimi For Coding、Qwen Token Plan、MiniMax 和小米 MiMo，部分服务还提供中国区节点配置。

Pi 同样可以接入本地模型：

• llama.cpp：使用专门的 /llama 命令管理。
• Ollama、LM Studio、vLLM：通过 models.json 添加模型配置。

2、第一次上手

进入项目目录后执行：

pi

随后直接用自然语言描述开发任务即可。Pi 默认只向模型提供四个工具：

• read：读取文件。
• write：写入文件。
• edit：修改文件。
• bash：执行终端命令。

查找文件、搜索代码等操作不会使用额外的专用工具，而是由模型通过 grep、find 等命令完成。这四项能力构成了 Pi 的极简工具基础。

项目约定文件

项目级指令可以写入 AGENTS.md，全局指令则放在：

~/.pi/agent/AGENTS.md

Pi 会沿目录树向上查找 AGENTS.md 或 CLAUDE.md。因此，从 Claude Code 迁移时，已有的 CLAUDE.md 通常可以继续使用，不必改名或移动。

常用交互操作

• @：模糊搜索项目文件。
• !命令：执行 Shell 命令，并将输出加入模型上下文。
• !!命令：执行 Shell 命令，但不把输出加入上下文。
• Ctrl+V：粘贴图片。
• pi -c：继续上一个会话。
• pi -r：浏览历史会话。
• pi -p：以非交互模式运行，适合脚本调用。
• --mode json：使用 JSON 输出。
• --mode rpc：使用 RPC 模式。

Pi 还提供可嵌入 Node.js 应用的 SDK，OpenClaw 就是其程序化接口的实际集成案例之一。

在会话中切换模型

输入 /model 或按 Ctrl+L 可以切换模型，并且支持在会话中跨服务商切换。Pi 会处理不同 provider 之间的上下文转换，使新的模型能够继续已有任务。

其他相关操作包括：

• Shift+Tab：调整 thinking 等级。
• Ctrl+P：在预先选择的常用模型之间循环切换。

3、树状会话管理

与采用线性历史记录的多数 CLI Agent 不同，Pi 将会话组织成树状结构。

每个会话保存为一个 JSONL 文件，每行是一条 JSON 记录，各节点会记录自己的父节点。通过 /tree 打开树视图后，可以回到任意历史节点，修改问题或指令并生成新的分支，原有分支仍会保留。

这种结构特别适合方案试错。例如，方案 A 失败后，可以回到分叉点尝试方案 B，同时保留方案 A 的执行记录，方便比较和复盘。

配套命令包括：

• /fork：从某条历史消息创建新的会话文件。
• /clone：复制当前分支。

切换分支时，Pi 还可以询问是否总结被放弃的分支，并把总结带入新分支，从而降低关键信息丢失的概率。

会话也支持导出和分享：

• /export：导出为 HTML。
• /share：上传为 GitHub 私有 Gist，并生成可访问链接。

这些能力适合记录调试过程、制作教程，或在提交开源项目 Issue 时提供可复现的操作记录。

4、Pi 故意不做的六件事

Pi 的设计原则明确列出了六项默认不内置的能力：

1. MCP。
2. 子代理。
3. 权限确认弹窗。
4. Plan Mode。
5. 内置 Todo。
6. 后台 Bash。

这并不意味着 Pi 无法实现这些功能，而是项目默认不把它们加入核心上下文和执行流程。

控制 Token 开销

按照项目介绍，Pi 的系统提示词与工具定义合计不到 1000 Token。相比之下，复杂 harness 的系统提示词和大量工具描述可能占用数千乃至上万 Token。

MCP Server 也可能带来明显的上下文开销。例如，包含大量工具的浏览器自动化 MCP，会在每次会话开始时注入完整工具描述，而其中多数工具未必会被实际使用。

Pi 推荐的替代方式是“CLI 工具加 README”：需要某项能力时，Agent 再读取对应文档，并通过 bash 调用 CLI。这样只有在真正使用时才产生相关上下文成本。

权限与隔离

Pi 默认不会为每个命令弹出权限确认框，执行方式更接近常说的 YOLO 模式。其设计观点是：当 Agent 同时具备写代码和执行代码的能力时，仅依靠确认弹窗无法形成完整的安全边界。

因此，如果任务涉及不可信代码、敏感数据或高风险命令，应优先在容器、虚拟机或隔离环境中运行 Pi，而不是把弹窗当作唯一安全措施。

默认无确认执行并不等于没有风险。首次使用时应避免直接授予生产环境、私钥目录和重要数据目录的访问权限。

用文件代替 Plan 和 Todo

Pi 建议把计划和任务分别写入普通文件，例如：

PLAN.md
TODO.md

这样做有几个好处：

• 可以进入 Git 版本管理。
• 能够跨会话保留。
• 人与 Agent 都能修改。
• 变更过程清晰可追踪。

后台命令可以交给 tmux 管理。需要子代理时，也可以让 Pi 通过 bash 启动另一个 pi -p 进程，使子任务的调用参数和输出保持可见。

5、缺少的功能可以通过扩展补齐

Pi 扩展本质上是 TypeScript 模块，放入以下目录后即可加载：

~/.pi/agent/extensions/

修改扩展后，可以执行 /reload 热加载，不需要单独编译。扩展能够：

• 注册自定义工具。
• 注册自定义命令。
• 监听和拦截运行事件。
• 改变特定工具的执行逻辑。

例如，可以监听 tool_call 事件，在 Bash 命令包含 rm -rf 等高风险操作时弹出确认框。换句话说，Pi 不是无法提供权限系统，而是允许用户自行决定是否启用、拦截哪些操作。

复用 Agent Skills

Pi 支持 Agent Skills 标准，可复用 Claude Code、Codex 等工具已有的 Skills。示例配置如下：

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

除 Skills 外，Pi 还提供两类扩展方式：

• Prompt Templates：使用 Markdown 文件定义 Slash 命令，并支持参数。
• Pi Packages：将扩展、Skills、模板和主题统一打包分发。

安装包时可以使用 npm 包或 Git 仓库，例如：

pi install npm:package-name

社区已经提供子代理、MCP 桥接和 Web 搜索等扩展，例如 pi-subagents、pi-mcp-adapter 和 pi-web-access。具体兼容性与安装方式应以各扩展的最新文档为准。

6、Pi 适合谁使用

Pi 与 Claude Code、Codex 的产品思路不同。Claude Code 更接近功能完整的开发套件，预置子代理、Plan Mode、Hooks 和 MCP 等能力；Codex 与 OpenAI 模型和账号体系结合更紧密；Pi 则提供一个精简基础和开放的改装接口。

Pi 更适合以下开发者：

• 希望严格控制上下文与 Token 消耗。
• 已有大量 CLI 工具，希望直接交给 Agent 调用。
• 需要跨模型、跨服务商切换。
• 愿意通过扩展定制权限、工具和工作流。
• 不希望核心行为随大量内置功能频繁变化。

Pi 可能不适合以下需求：

• 必须使用图形界面。
• 需要完善的企业权限、审计和集中管控。
• 希望所有功能开箱即用，不愿配置扩展。
• 无法提供容器或其他隔离执行环境。

总体而言，Pi 的价值不在于内置功能最多，而在于核心足够小、交互速度快，并允许开发者决定上下文中应该出现什么。如果你对重型 Coding Harness 的复杂度和 Token 开销感到困扰，Pi 提供了一种更可控的选择。