Pi Coding Agent 使用教程
速览
Pi 是一个有主见且极简的 Coding Agent，基于它构建的 OpenClaw 爆火。Pi 奉行激进可扩展性，不内置 MCP、sub-agents、permission popups 等，通过 extensions、skills 或第三方包定制工作流。本文详细介绍了 Pi 的安装、模型配置（支持多家 API 和订阅）、以及第三方提供商设置。适用于希望在终端中高效使用 AI 辅助编码的开发者。
AI 深度解读
背景
Pi 是一个面向开发者的极简 Coding Agent CLI，由作者有意取名“π”以降低知名度（避免与数学符号混淆带来的低质量 issues 和 AI 生成的 PR）。它基于激进可扩展性的设计理念，核心保持精简，一切工作流通过 extensions、skills 或第三方 pi packages 实现。近期爆火的 OpenClaw 正是基于此工具包构建。Pi 提供 TUI（终端用户界面），支持多模型、多提供商、会话树管理、消息队列等高级功能，被认为是目前最好用的 AI Agent CLI。
核心内容
Pi 的安装通过 npm 全局安装：
npm install -g @mariozechner/pi-coding-agent
安装后运行 pi 命令启动，或为终端配置快捷键。Windows 用户需要 bash shell（如 Git Bash、Cygwin、MSYS2、WSL），可通过 ~/.pi/agent/settings.json 自定义 shell 路径。Termux（Android）用户见原文。
模型配置
通过 /model 或 Ctrl+L 选择模型。支持多种订阅登录：Claude Pro/Max、ChatGPT Plus/Pro (Codex)、GitHub Copilot、Google Gemini CLI、Google Antigravity，使用 /login 登入，认证 Token 存储在 ~/.pi/agent/auth.json。API 密钥可通过环境变量或 auth.json 设置。auth.json 默认权限 0600（仅用户可读/写），凭证优先于环境变量。
第三方提供商通过 ~/.pi/agent/models.json 配置，示例包含 CloseAI 等自定义 provider。API 类型包括 openai-completions、openai-responses、anthropic-messages、google-generative-ai。在 providers 层级设置的 api 作为该 provider 下所有 models 的默认值，单个模型可通过自己的 api 字段覆盖。若遇 403 错误（CF 阻断），需在 headers 中添加 User-Agent。
每次在 Pi 中键入 /model 时文件重新加载，无需重启会话。
编辑器功能
编辑器输入框支持：
@模糊搜索文件引用Tab路径补全Shift+Enter多行输入（Windows Terminal 可用Ctrl+Enter）Ctrl+V粘贴图片（Windows 可用Alt+V），或直接拖到终端!command执行 bash 命令并把输出发给模型，!!command执行但不发送输出- 标准编辑快捷键（删除单词、撤销等）
命令
在编辑器输入 / 可触发命令。扩展可注册自定义命令，技能通过 /skill:name 调用，提示词模板通过 /templatename 展开。主要命令列表：
/login、/logout：OAuth 登录/退出/model：切换模型/scoped-models：启用/禁用 Ctrl+P 轮换可选模型/settings：设置思考等级、主题、消息投递、传输方式/resume：从历史会话恢复/new：新建会话/name <name>：设置会话显示名称/session：显示会话信息（路径、Token、费用）/tree：跳转到会话任意节点并从那继续/fork：从当前分支创建新会话/compact [prompt]：手动压缩上下文，可自定义压缩提示/copy：复制助手上一条回复到剪贴板/export [file]：导出会话为 HTML 文件/share：上传为私有 GitHub Gist，生成可分享 HTML 链接/reload：重载扩展、技能、提示词、上下文文件（主题自动热更新）/hotkeys：显示全部快捷键/changelog：显示版本更新记录/quit、/exit：退出 pi
消息队列
智能体工作时可继续发消息：
Enter：排入引导消息，在当前工具执行完后立即送达（并中断后续未执行工具）Alt+Enter：排入跟进消息，只在代理完成全部工作后送达Escape：中止当前过程，把已排队消息恢复到编辑器Alt+Up：把队列中的消息取回到编辑器
settings 可配置投递方式：steeringMode 和 followUpMode 可设为 "one-at-a-time"（默认）或 "all"。transport 用于选择支持多传输的提供方通道偏好（"sse"、"websocket" 或 "auto"）。
会话管理
会话以 JSONL 树结构保存，每条记录有 id 和 parentId，可在同一文件内分支。自动保存到 ~/.pi/agent/sessions/，按工作目录（cwd）分组。
pi -c：继续最近一次会话pi -r：浏览并选择历史会话pi --no-session：临时模式（不保存会话）pi --session <path>：使用指定会话文件或会话 ID
分支功能：/tree 在会话文件内浏览树，可选中任意历史节点继续；/fork 从当前分支创建新会话文件。
设置
使用 /settings 修改常用选项，或直接编辑 JSON 文件：
~/.pi/agent/settings.json：全局.pi/settings.json：项目
项目上下文
Pi 启动时从以下位置加载 AGENTS.md（或 CLAUDE.md）：
~/.pi/agent/AGENTS.md（全局）- 父目录（从当前工作目录向上查找）
- 当前目录
所有匹配的 md 文件拼接在一起，用于项目说明、约束和常用命令封装。
系统提示
用 .pi/SYSTEM.md（项目）或 ~/.pi/agent/SYSTEM.md（全局）替换系统提示词，或者通过 APPEND_SYSTEM.md 追加在末尾。
自定义
上述所有内容均可封装为 pi 命令或扩展，体现激进可扩展性。
关键要点
- Pi 是一个有主见且极简的 Coding Agent CLI，通过 extensions、skills 和第三方 packages 实现扩展，核心不内置任何预设工作流。
- 不提供 MCP、sub-agents、permission popups、plan mode、内置 to-dos、后台 bash，这些能力通过其他方式（如 tmux、extensions、文件）实现。
- 安装只需 npm 全局安装，Windows 需 bash shell，Termux 见原文。
- 模型配置支持多种订阅登录和 API 密钥，可通过
auth.json或环境变量设置，auth.json 权限 0600。 - 第三方提供商通过
models.json配置，支持多种 API 类型（如 openai-completions、openai-responses 等），可自定义 headers 解决 CF 阻断。 - 编辑器支持文件引用、路径补全、多行输入、图片粘贴、bash 命令执行等功能。
- 命令系统丰富，