【最强AI Agent】 π 使用教程

问题描述：

这篇贴子用于快速上手pi，要深入了解详细内容请看我贴出的原文链接

前言

按照的作者话来说,Pi Coding Agent是一个有主见且极简的Coding Agent，这段时间爆火的OpenClaw就是基于此工具包构建的。上手了一段时间后，我敢说这就是目前最好用的AI Agent CLI。

很多项目爆火后都会迎来各种低质量的issues和ai生成的pr，而pi这个名字非常有意思，会与数学信息产生关联，是作者有意取的，就是为了降低知名度。

设计理念

翻译自README

Pi 奉行近乎激进的可扩展性，因此无需、也不愿替你规定工作流。许多在别的工具中“内建”的能力，在这里都可通过 extensions、skills，或安装第三方 pi packages 来实现。这样既能让核心保持精简，又能让你按自己的工作方式塑造 Pi。

不做 MCP。 你可以构建带有 README 的 CLI 工具（见 Skills），也可以编写 extension，为 Pi 增加 MCP 支持。为何如此？

不设 sub-agents。 实现路径有很多：可借助 tmux 启动多个 Pi 实例，或用 extensions 自行搭建，亦可安装按你思路实现的软件包。

不弹 permission popups。 你可以在容器中运行，或通过 extensions 构建与自身环境及安全要求相匹配的确认流程。

不设 plan mode。 计划可直接写入文件，或借助 extensions 自行实现，或安装相应软件包。

不内置 to-dos。 它们容易让模型困惑。请使用 TODO.md，或用 extensions 自定义。

不提供后台 bash。 请使用 tmux：全程可观测，交互更直接。

详情见作者博文,这位大佬的文章写的非常棒！

快速上手

使用过程中有困难可以 。

安装

npm install -g @mariozechner/pi-coding-agent

接着可通过pi命令来启动,或为你的终端配置快捷键。

Windows

注意： 使用Windows的佬友还需要一个bash shell。检查顺序：

1. ~/.pi/agent/settings.json中的自定义路径
2. Git Bash (C:\Program Files\Git\bin\bash.exe)
3. PATH 中的bash.exe (如Cygwin, MSYS2, WSL)

对于大多数佬友，Git for Windows 足够了。

自定义 Shell 路径 ( settings.json )

{ "shellPath": "C:\\cygwin64\\bin\\bash.exe" }

Termux（Android）

见原文，因为要控制篇幅的需要便不再赘述。

模型配置

配置好后可以通过 /model （或 Ctrl+L）选择模型。

（pi有着优质的模型配置方式，但OpenClaw选择在此之上再造一层史这让我非常不理解。）

订阅

对于具有一下订阅之一的佬友

• Claude Pro/Max
• ChatGPT Plus/Pro (Codex)
• GitHub Copilot
• Google Gemini CLI
• Google Antigravity

可通过/login进行登入，使用/logout登出。认证Token会被储存在~/.pi/agent/auth.json。

API 密钥

祥见原文

可通过环境变量设置：

export ANTHROPIC_API_KEY=sk-ant-... pi

或写入~/.pi/agent/auth.json。

{ "anthropic": { "type": "api_key", "key": "sk-ant-..." }, "openai": { "type": "api_key", "key": "sk-..." }, "google": { "type": "api_key", "key": "..." }, "opencode": { "type": "api_key", "key": "..." } }

如下表

供应商	环境变量	auth.json 键
Anthropic	ANTHROPIC_API_KEY	anthropic
Azure OpenAI Responses	AZURE_OPENAI_API_KEY	azure-openai-responses
OpenAI	OPENAI_API_KEY	openai
Google Gemini	GEMINI_API_KEY	google
Mistral	MISTRAL_API_KEY	mistral
Groq	GROQ_API_KEY	groq
Cerebras	CEREBRAS_API_KEY	cerebras
xAI	XAI_API_KEY	xai
OpenRouter	OPENROUTER_API_KEY	openrouter
Vercel AI Gateway	AI_GATEWAY_API_KEY	vercel-ai-gateway
ZAI	ZAI_API_KEY	zai
OpenCode Zen	OPENCODE_API_KEY	opencode
Hugging Face	HF_TOKEN	huggingface
Kimi For Coding	KIMI_API_KEY	kimi-coding
MiniMax	MINIMAX_API_KEY	minimax
MiniMax (中国)	MINIMAX_CN_API_KEY	minimax-cn

默认情况下auth.json是携带0600权限创建的（仅用户可读/写），Auth文件凭证优先于环境变量。

第三方提供商

祥见原文

创建~/.pi/agent/models.json

完整示例

{ "providers": { "CloseAI": { "baseUrl": "https://api.closeai.ai/v1", "api": "openai-responses", "apiKey": "sk-a1b1c4d5e14f5", "models": [ { "id": "gpt-5.4", "name": "GPT-5.4", "reasoning": true, "input": [ "text", "image" ], "contextWindow": 1000000, "maxTokens": 128000, "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 } } ] } } }

API	描述
openai-completions	OpenAI Chat Completions (最兼容)
openai-responses	OpenAI Responses API
anthropic-messages	Anthropic Messages API
google-generative-ai	Google Generative AI

• 在 providers 层级设置的 api，作为该 provider 下所有 models 的默认值。

• 在 models 层级中，单个模型可以通过自己的 api 字段覆盖这个默认值。

• 如遇报错Error: 403 Your request was blocked.说明请求被cf阻断。自定义请求头加上UA即可：

"headers": { "User-Agent": "MyCustomClient/1.0" },

以下是御三家模型配置（要套到上面的完整配置中）。

{ "models": [ { "id": "gpt-5.4", "name": "GPT 5.4", "reasoning": true, "input": ["text", "image"], "contextWindow": 1000000, "maxTokens": 128000 }, { "id": "claude-opus-4-6", "name": "Claude Opus 4.6", "reasoning": true, "input": ["text", "image"], "contextWindow": 200000, "maxTokens": 128000 }, { "id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro Preview", "reasoning": true, "input": ["text", "image"], "contextWindow": 1048576, "maxTokens": 65536 } ] }

每家站点的花费各不相同根据情况修改。

每次在Pi中键入/model 时，文件都会重新加载，因此在会话期间编辑models.json无需重启。

指南

详见README

image1726×2162 326 KB

感受一下TUI，OpenClaw用的也是这个。可以编写主题和扩展进行爆改，甚至让Pi像Claude Code。

编辑器

（指的是输入框）

功能	用法
文件引用	输入 @ 可模糊搜索项目文件
路径补全	按 Tab 自动补全路径
多行输入	Shift+Enter（Windows Terminal 下也可用 Ctrl+Enter）
图片	Ctrl+V 粘贴（Windows 下可用 Alt+V），或直接拖到终端
Bash 命令	!command 执行并把输出发给模型，!!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：在当前会话文件内浏览会话树。你可以选中任意历史节点，从那继续，并在不同分支间切换。所有历史都保留会话文件中。

• 输入关键词可搜索，←/→ 翻页

• 过滤模式（Ctrl+O）：default → no-tools → user-only → labeled-only → all

• 按 l 可给条目标记书签

/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 package。

这里整理了公开的 Pi 包

Packages - pi.dev

提示词模板

将提示词封装为Markdown文件，输入/文件名展开。

<!-- ~/.pi/agent/prompts/review.md --> Review this code for bugs, security issues, and performance problems. Focus on: {{focus}}

放置在 ~/.pi/agent/prompts/（全局）, .pi/prompts/（项目）或封装为 pi package 分享给别人.

技能

按需加载的技能包，遵循 Agent Skills 标准。可通过输入/skill:name 调用，也可让 Agent 自动加载。

<!-- ~/.pi/agent/skills/my-skill/SKILL.md --> # My Skill Use this skill when the user asks about X. ## Steps 1. Do this 2. Then that

安装路径：

全局

• ~/.pi/agent/skills/
• ~/.agents/skills/

项目

• .pi/skills/
• .agents/skills/（从当前工作目录向上逐级查找父目录）

或封装为 pi package。

详见此处.

pi作者维护的技能包，包含浏览器控制，brave搜索等技能，pi和其它支持skill的项目都能直接使用。

扩展

放入 ~/.pi/agent/extensions/（全局）、.pi/extensions/（项目）或封装为 pi package 分享给别人。

参见文档和例子。

主题

内置暗色与明亮，修改主题配置后可热重载。

放入~/.pi/agent/themes/（全局），.pi/themes/（项目）或封装为 pi package 分享给别人。

详见此处。

通过扩展与主题系统可以极大增强我们的使用体验！！！ 直接对模型说出需求即可，因为pi的系统提示词中包含了pi的文档路径。

Pi Telegram Bot

这是我用pi编写出来的项目，可以在TG上与 Pi Agent 沟通。

且值得一提的是，我没有蠢到像OpenClaw一样手写MD到HTML的转换（难绷），而是直接使用已有包进行转换和标签清洗。

但目前暂时没有记忆系统，因为找不到合适的项目，希望佬友们能出谋划策。不过你可以把重要信息写入工作目录（cwd）下的的AGENTS.md会载入上下文。

具体信息README写的很清晰就不再重复发一遍。使用过程中有困难可以 。

github.com

GitHub - Ziphyrien/Pi-Telegram

通过在 GitHub 上创建帐户来为 Ziphyrien/Pi-Telegram 开发做出贡献。

网友解答：

---

--【壹】--：

前排支持～

---

--【贰】--：

支持一下

---

--【叁】--：

好厉害，支持一下

---

--【肆】--：

强，非常好的教程

---

--【伍】--：

强，先赞再看

---

--【陆】--：

看起来是一个非常完善的脚手架，感觉搭建起来需要相当长的时间还有足够多的精力。。。

---

--【柒】--：

前排支持

---

--【捌】--：

刚刷到 有空试试
感谢分享好人一生平安。

---

--【玖】--：

多谢分享，学习了！

---

--【拾】--：

不支持哦，可以看看设计理念

---

--【拾壹】--：

这个agent支持类似kilo的orchestrator模式么?

---

--【拾贰】--：

太强大了，值得深入研究一下

---

--【拾叁】--：

等大佬测试一下

---

--【拾肆】--：

image311×347 96.8 KB
很好用，前段时间在L站被佬推荐后用了，据说比opencode好，适合习惯用cli的佬，我平时是比较喜欢有webui界面的Agent

---

--【拾伍】--：

支持一下

---

--【拾陆】--：

有什么优势

---

--【拾柒】--：

好文,学习学习

---

--【拾捌】--：

学习了学习了

---

--【拾玖】--：

可以看作者博文，写的非常棒！pi 优雅简洁，可扩展性极强，用过的都说好。