--- url: /blog/4ideu4s8/index.md description: >- 这篇贴子用于快速上手pi，要深入了解详细内容请看我贴出的原文链接 前言按照的作者话来说,Pi Coding Agent是一个有主见且极简的Coding Agent，这段时间爆火的OpenClaw就是基于此工具包构建的。上手了一段时间后… --- > \[!info] Info > **真诚** 、 **友善** 、 **团结** 、 **专业** ，共建你我引以为荣之社区。 [《社区准则》](https://linux.do/guidelines) ## 【最强AI Agent】 π 使用教程 [开发调优](https://linux.do/c/develop/4) [View as nested](https://linux.do/n/topic/1680124) * [前言](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-1) * [设计理念](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-2) * [快速上手](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-3) * [安装](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-4) * [Windows](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-windows-5) - [Termux（Android）](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-termuxandroid-6) * [模型配置](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-7) * [订阅](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-8) - [API 密钥](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-api-9) - [第三方提供商](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-10) * [指南](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-11) * [编辑器](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-12) * [命令](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-13) * [消息队列](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-14) * [会话](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-15) * [管理](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-16) * [分支](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-17) * [设置](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-18) * [项目上下文](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-19) * [系统提示](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-20) * [自定义](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-21) * [提示词模板](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-22) - [技能](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-23) - [扩展](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-24) - [主题](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-h-25) * [Pi Telegram Bot](【最强AI%20Agent】%20π%20使用教程%20-%20开发调优.md#p-14390496-pi-telegram-bot-26) [3月 2 日](https://linux.do/t/topic/1680124/1 "跳到第一个帖子") 1 / 168 3月 2 日 [5 天 前](https://linux.do/t/topic/1680124/172) [方生无归](https://linux.do/u/ziphyrien) [Ziphyrien](https://linux.do/u/ziphyrien) 骐骥驰骋 这篇贴子用于快速上手pi，要深入了解详细内容请看我贴出的原文链接 ## 前言 按照的作者话来说,[**Pi Coding Agent**](https://github.com/badlogic/pi-mono/tree/main/packages/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：全程可观测，交互更直接。 详情见作者 [博文](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/),这位大佬的文章写的非常棒！ ## 快速上手 使用过程中有困难可以 。 ### 安装 `npm install -g @mariozechner/pi-coding-agent` 接着可通过 `pi` 命令来启动,或 [为你的终端配置快捷键](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/terminal-setup.md) 。 #### 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](https://git-scm.com/download/win) 足够了。 自定义 Shell 路径 ( `settings.json` ) ```json { "shellPath": "C:\\cygwin64\\bin\\bash.exe" } ``` #### Termux（Android） 见 [原文](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/termux.md) ，因为要控制篇幅的需要便不再赘述。 ### 模型配置 配置好后可以通过 `/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 密钥 祥见 [原文](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/providers.md) 可通过环境变量设置： ```bash export ANTHROPIC_API_KEY=sk-ant-... pi ``` 或写入 `~/.pi/agent/auth.json` 。 ```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文件凭证优先于环境变量。 #### 第三方提供商 祥见 [原文](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/models.md) 创建 `~/.pi/agent/models.json` 完整示例 ```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即可： ```json "headers": { "User-Agent": "MyCustomClient/1.0" }, ``` 以下是御三家模型配置（要套到上面的完整配置中）。 ```json { "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](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#readme) [![image](./assets/【最强AI%20Agent】%20π%20使用教程%20-%20开发调优/d6e575c84cf15f39129bac5f9dbb4d46ed75d085_2_399x500.png)](https://cdn3.linux.do/original/4X/d/6/e/d6e575c84cf15f39129bac5f9dbb4d46ed75d085.png "image") 感受一下TUI，OpenClaw用的也是这个。可以编写主题和扩展进行爆改，甚至让Pi像Claude Code。 ### 编辑器 （指的是输入框） | 功能 | 用法 | | --------- | ------------------------------------------------------------- | | 文件引用 | 输入 `@` 可模糊搜索项目文件 | | 路径补全 | 按 `Tab` 自动补全路径 | | 多行输入 | `Shift+Enter` （Windows Terminal 下也可用 `Ctrl+Enter` ） | | 图片 | `Ctrl+V` 粘贴（Windows 下可用 `Alt+V` ），或直接拖到终端 | | Bash 命令 | `!command` 执行并把输出发给模型，`!!command` 执行但不发送输出 | 删除单词、撤销等使用标准编辑快捷键。详见 [此处](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/keybindings.md) 。 ### 命令 在编辑器里输入 `/` 可触发命令。 [扩展](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#extensions) 可注册自定义命令， [技能](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#skills) 可用 `/skill:name` 调用， [提示词模板](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#prompt-templates) 可通过 `/templatename` 展开。 | 命令 | 说明 | | ------------------- | ------------------------------------------------------ | | `/login`,`/logout` | OAuth 登录/退出 | | `/model` | 切换模型 | | `/scoped-models` | 启用/禁用 `Ctrl+P` 轮换可选模型 | | `/settings` | 设置思考等级、主题、消息投递、传输方式 | | `/resume` | 从历史会话中恢复 | | `/new` | 新建会话 | | `/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](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/settings.md) 配置投递方式： `steeringMode` 和 `followUpMode` 可设为 `"one-at-a-time"` （默认，收到回复后再发下一条）或 `"all"` （一次性发送队列全部消息）。 `transport` 用于选择支持多传输的提供方通道偏好（ `"sse"` 、 `"websocket"` 或 `"auto"` ）。 ### 会话 会话以 JSONL 树结构保存。每条记录都有 `id` 和 `parentId` ，所以可以在同一个文件里直接分支，不必新建文件。文件格式见 [此处](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/session.md) 。 ### 管理 会话会自动保存到 `~/.pi/agent/sessions/` ，并按工作目录（cwd）分组。 * `pi -c` ：继续最近一次会话 * `pi -r` ：浏览并选择历史会话 * `pi --no-session` ：临时模式（不保存会话） * `pi --session ` ：使用指定会话文件或会话 ID ### 分支 **`/tree`** ：在当前会话文件内浏览会话树。你可以选中任意历史节点，从那继续，并在不同分支间切换。所有历史都保留会话文件中。 [![Tree View|600x389.296875](./assets/【最强AI%20Agent】%20π%20使用教程%20-%20开发调优/fef44c9acaf8a1487a3d89bfc8e4ee9db9483049.png)](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/images/tree-view.png) * 输入关键词可搜索， `←/→` 翻页 * 过滤模式（Ctrl+O）：default → no-tools → user-only → labeled-only → all * 按 `l` 可给条目标记书签 **`/fork`** ：从当前分支创建一个新的会话文件。系统会打开选择器，复制到所选节点为止的历史，并把该节点消息放入编辑器，方便你继续修改。 ### 设置 使用 `/settings` 修改常用选项，或直接编辑 JSON 文件： | 位置 | 范围 | | --------------------------- | ---- | | `~/.pi/agent/settings.json` | 全局 | | `.pi/settings.json` | 项目 | 详见 [此处](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/settings.md) 。 ### 项目上下文 Pi 在启动时会从以下位置加载 `AGENTS.md` （或 `CLAUDE.md` ）： * `~/.pi/agent/AGENTS.md` (全局) * 父目录（从当前工作目录向上查找） * 当前目录 用于项目说明、约束和常用命令封装。所有匹配的md文件将被拼接在一起。 #### 系统提示 用 `.pi/SYSTEM.md` （项目）或 `~/.pi/agent/SYSTEM.md` （全局）替换系统提示词或通过 `APPEND_SYSTEM.md` 追加在系统提示词末尾。 ### 自定义 这部分的内容都可以封装为 [pi package](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#pi-packages) 。 这里整理了公开的 Pi 包 [Packages - pi.dev](https://pi.dev/packages) #### 提示词模板 将提示词封装为Markdown文件，输入 `/文件名` 展开。 ```markdown Review this code for bugs, security issues, and performance problems. Focus on: {{focus}} ``` 放置在 `~/.pi/agent/prompts/` （全局）, `.pi/prompts/` （项目）或封装为 [pi package](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#pi-packages) 分享给别人. #### 技能 按需加载的技能包，遵循 [Agent Skills 标准](https://agentskills.io/) 。可通过输入/skill:name 调用，也可让 Agent 自动加载。 ```markdown # 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](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#pi-packages) 。 详见 [此处](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md). pi作者维护的 [技能包](https://github.com/badlogic/pi-skills) ，包含浏览器控制，brave搜索等技能，pi和其它支持skill的项目都能直接使用。 #### 扩展 放入 `~/.pi/agent/extensions/` （全局）、`.pi/extensions/` （项目）或封装为 [pi package](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#pi-packages) 分享给别人。 参见 [文档](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md) 和 [例子](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/examples/extensions) 。 #### 主题 内置暗色与明亮，修改主题配置后可热重载。 放入 `~/.pi/agent/themes/` （全局），`.pi/themes/` （项目）或封装为 [pi package](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#pi-packages) 分享给别人。 详见 [此处](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/themes.md) 。 **通过扩展与主题系统可以极大增强我们的使用体验！！！** 直接对模型说出需求即可，因为pi的系统提示词中包含了pi的文档路径。 ## Pi Telegram Bot 这是我用pi编写出来的项目，可以在TG上与 Pi Agent 沟通。 且值得一提的是，我没有蠢到像OpenClaw一样手写MD到HTML的转换（难绷），而是直接使用已有包进行转换和标签清洗。 但目前暂时没有记忆系统，因为找不到合适的项目，希望佬友们能出谋划策。不过你可以把重要信息写入工作目录（cwd）下的的AGENTS.md会载入上下文。 具体信息README写的很清晰就不再重复发一遍。使用过程中有困难可以 。 ## 追加内容 • 如遇报错`Error: 403 Your request was blocked.`说明请求被cf阻断。自定义请求头加上UA即可： ```json "headers": { "User-Agent": "MyCustomClient/1.0" }, ``` 另外不建议使用OMP（oh-my-pi），它把一切都搞砸了！！！