1. 为什么你的 pi 第一次启动就卡在 No models available刚接触 Pi Coding Agent 的开发者十有八九会在第一次敲下pi回车后愣住界面出来了但顶部一行黄字Warning: No models available输入框能打字却没人理你。这不是装坏了也不是版本不对而是 pi 的设计逻辑——它本体只是一个终端里的智能体外壳真正干活的模型需要你自己接上去。没接模型它就像一个没有大脑的终端能显示界面但不会思考。我见过太多人在这里放弃以为要配一堆复杂的环境变量。其实从零到跑通第一个任务核心就三件事装好 pi、给它一个能用的模型入口、在 git 仓库里让它改一次代码并验证结果。这篇手册按“安装 → 接模型 → 初始化配置 → 跑通首个任务 → 排障”的顺序走一遍命令都能直接抄macOS、Linux、Windows 都适用差异处我会单独标出来。先明确 pi 是什么它是一个跑在终端里的开源 AI 智能体coding agent你打一句话它思考、读文件、改文件、跑命令、看图然后把结果交给你。它只有终端界面没有图形窗口这是设计如此。两个预期先摆好第一pi 会在你当前目录里真的动手改文件所以在 git 仓库里用它、改坏能回滚是官方推荐的工作方式第二它的核心故意做得很小MCP、子代理这类进阶能力靠扩展extensions、技能skills、包packages往上加本篇只覆盖核心用法够你跑通第一个任务。适合谁读刚接触 Pi Coding Agent、想在本地快速确认 Agent 能正常工作的开发者不预设公司环境、不预设特定模型。读完你能独立完成一次“让 pi 读代码 → 改代码 → 跑测试 → 验证结果”的闭环。2. 安装 pi 与 Node 环境准备npm 全局安装报错怎么解2.1 先确认 Node 版本pi 要求 Node.js ≥ 20。打开终端敲node -v如果打印v20.x.x或更高就跳过这步。没装或版本太旧macOS 用brew install nodeWindows 和 Linux 去 nodejs.org 下 LTS 版装。Windows 用户注意装完要重开一个终端让 PATH 生效否则node -v还是提示找不到命令。2.2 全局安装 pinpm install -g mariozechner/pi-coding-agent大陆网络慢的话可以这一次临时加国内镜像提速npm install -g mariozechner/pi-coding-agent --registryhttps://registry.npmmirror.com注意是“这一次临时加”别去改全局 npm 配置以免影响你其他包的源。踩过的坑有人图省事npm config set registry改了全局结果公司私有包拉不下来排查半天。2.3 验证安装pi --version打印版本号如0.73.0即成功。以后升级用pi update只升 pi 本体用pi update --self。2.4 安装阶段的常见报错EACCES permission deniedLinux/macOS 上全局目录没权限别用 sudo 硬装改用 nvm 管理 Node或按 npm 官方文档改全局前缀。npm ERR! code EINTEGRITY缓存坏了npm cache clean --force后重装。pi: command not found全局 bin 目录不在 PATH 里。用npm bin -g看路径把它加进 shell 配置。装完先别急着接模型下一步才是关键。3. 给 pi 接上模型auth.json 与 models.json 可复制配置3.1 两条接模型的路先cd到你想让 pi 干活的项目目录再敲pi回车。什么都没配时你会看到Warning: No models available这就是在催你接模型。接模型有两条路路线 A 用/login走 OAuth 登录路线 B 直接配 API key。长期用推荐路线 B配置一次到处能用。常见 provider 与环境变量对照Provider环境变量AnthropicANTHROPIC_API_KEYOpenAIOPENAI_API_KEYGoogle GeminiGEMINI_API_KEYDeepSeekDEEPSEEK_API_KEYOpenRouterOPENROUTER_API_KEYMistralMISTRAL_API_KEYGroqGROQ_API_KEYxAIXAI_API_KEYHugging FaceHF_TOKENKimi For CodingKIMI_API_KEYMiniMax国内MINIMAX_CN_API_KEY3.2 用 auth.json 持久化凭证长期用可直接编辑~/.pi/agent/auth.json文件会自动设成仅本人可读写{ anthropic: { type: api_key, key: sk-ant-... }, openai: { type: api_key, key: sk-... }, deepseek: { type: api_key, key: sk-... } }配好后界面里/model或CtrlL选一个模型就可以开工了。3.3 接任意 OpenAI 兼容服务models.json内置 provider 不够用本地 Ollama、LM Studio、vLLM、公司代理、任何 OpenAI 兼容服务时写~/.pi/agent/models.json。这个文件每次打开/model都会重新读改完不用重启 pi。最小例子本地 Ollama{ providers: { ollama: { baseUrl: http://localhost:11434/v1, api: openai-completions, apiKey: ollama, models: [ { id: qwen2.5-coder:7b } ] } } }Ollama 不校验 keyapiKey 填任意值即可。接任意 OpenAI 兼容服务的完整例子字段含义见注释{ providers: { my-service: { baseUrl: https://你的服务地址/v1, api: openai-completions, apiKey: MY_ENV_KEY, compat: { supportsDeveloperRole: false }, models: [ { id: 模型id, name: 显示名, reasoning: true, input: [text, image], contextWindow: 1000000, maxTokens: 131072 } ] } } }关键字段大白话api是对方说哪种“方言”四选一openai-completions最通用、openai-responses、anthropic-messages、google-generative-ai。input填[text]或[text, image]请如实填——填了 image 却实际不能看图的模型会收到图然后瞎编该锁 text 的就锁 textpi 会在客户端替你拦图。compat.supportsDeveloperRole: false是因为很多 OpenAI 兼容服务不认 developer 角色加上这个让 pi 改发 system若还不认reasoning_effort再加supportsReasoningEffort: false。Ollama、vLLM、SGLang 一类基本都要加。如果你用的是 TaoToken 这类聚合入口把baseUrl指向https://taotoken.net/apiapi填openai-completionsapiKey填你在控制台生成的 key模型 id 按文档里列出的填即可。这样一套配置能同时挂多个模型/model里切换。3.4 配置不生效怎么排查改了models.json没反应确认文件路径是~/.pi/agent/models.json不是项目目录下的。JSON 语法错一个逗号都会静默失败用cat ~/.pi/agent/models.json | python -m json.tool校验一下。/model里看不到新模型baseUrl结尾多了或少了/v1OpenAI 兼容服务通常要带/v1。4. 跑通第一个任务让 pi 读代码、改代码、跑测试4.1 准备工作目录mkdir pi-demo cd pi-demo git init npm init -y建一个待改的小文件src/math.jsfunction add(a, b) { return a b; } module.exports { add };提交一次方便回滚git add . git commit -m init4.2 启动 pi 并选模型pi界面出来后按CtrlL打开模型选择器选你刚配好的模型。状态栏会显示当前模型名和 token 花费。4.3 第一个任务加一个函数并写测试在输入框里打src/math.js 给这个文件加一个 subtract 函数并写一个对应的测试文件 src/math.test.js用 node 内置的 assert注意src/math.js必须是独立参数别把它写进引号里的问题文本否则会被当成普通文件名报File not found。pi 会开始工作读文件、思考、改文件、创建测试文件。你会看到对话区出现工具块默认折叠摘要按ctrlo展开看完整输出。4.4 让它跑测试验证等它改完输入!node src/math.test.js!命令会先跑命令把输出一起发给模型。如果测试通过你会看到类似all tests passed的输出如果失败pi 会读报错并尝试修复。4.5 验证结果退出 pictrld在终端里看 diffgit diff你应该能看到subtract函数被加进src/math.js以及新建的src/math.test.js。再手动跑一次node src/math.test.js打印通过信息说明 Agent 已经正常工作。这一步是整个手册的核心验证点——能读、能改、能跑、结果可复现闭环就通了。4.6 一次性用法不进界面不想进交互界面时pi -p 总结一下这个代码库 cat README.md | pi -p 总结这段文字 pi -p 截图.png 图里是什么 pi --tools read,grep,find,ls -p 审查代码最后一条是只读模式不许改不许跑适合先让 pi 熟悉代码库再动手。脚本集成用--mode json事件流或--mode rpc进程间协议。5. 常见报错排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常见。原因key 填错、key 过期、或者auth.json里 provider 名字和实际用的对不上。排查顺序先cat ~/.pi/agent/auth.json确认 key 没多空格再用 curl 直接打一次接口验证 key 本身有效curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer 你的key如果 curl 也 401是 key 的问题curl 通了但 pi 报 401是 pi 配置里baseUrl或api字段写错了。5.2 local proxy failed这个报错通常出现在你配了本地代理或本地模型服务Ollama、LM Studio但服务没起来。先确认服务在跑curl http://localhost:11434/v1/models连不上就先把本地服务启动。如果models.json里baseUrl写的是http://localhost:11434少了/v1也会报这个。5.3 reading choices / cannot read property choices这是响应格式不匹配。多半是api字段填错了——对方是 Anthropic 方言你填了openai-completions或者反过来。对照服务商文档改api字段。另一个可能是compat.supportsDeveloperRole没设 false服务端返回了非标准结构。5.4 OAuth 登录失败/login走 OAuth 时如果卡在回调或报 token 交换失败先检查系统时间是否准确差几分钟就会失败再确认浏览器能正常打开回调地址。公司网络限制回调端口的话改用 API key 路线更省事。5.5 贴图提示 does not support images当前模型是纯文本模型pi 在客户端把图拦下了。CtrlP换能看图的模型。这不是故障是防止把图发给“会瞎编”的模型。5.6 改了配置没生效models.json每次开/model会重读但auth.json和settings.json改动后建议/reload。AGENTS.md改完也要/reload。5.7 它改坏了我的代码怎么办所以建议在 git 仓库里用 pi。会话里的/tree能回退“对话”但回退不了“文件”——文件回滚靠 git。养成每让 pi 动一次手就 commit 一次的习惯。5.8 回答又慢又贵ShiftTab调低思考级别/compact压缩上下文换便宜模型CtrlP。状态栏实时显示 token 与花费盯着它调。6. 把 pi 用顺手的几个配置与下一步跑通第一个任务后有几件事能让 pi 更贴合你的项目。第一是AGENTS.mdpi 启动时会自动读它当“项目说明书”告诉它这个项目的规矩# Project Instructions - 改完代码跑 npm run check。 - 不要在本地跑生产库迁移。 - 回答保持简洁。全局放~/.pi/agent/AGENTS.md项目级放当前目录及上级目录的AGENTS.md或CLAUDE.md。改完/reload生效。第二是会话管理。会话按工作目录自动保存在~/.pi/agent/sessions/关掉终端也不丢pi -c # 继续最近一次会话 pi -r # 浏览、挑一个历史会话 pi --no-session # 这次不保存 pi --session 路径|id # 打开指定会话界面里/new开新会话/resume挑历史/export导出 HTML/share传成私密 gist 拿分享链接。第三是快捷键。记不住随时/hotkeys看全部。常用的Enter发送它忙时变为排队插话ShiftEnter换行escape打断当前回答ctrlc清空输入框ctrld退出CtrlL模型选择器ShiftTab循环思考级别ctrlo展开工具输出ctrlg把正在写的内容丢进外部编辑器。键位不顺手可以改~/.pi/agent/keybindings.json官方给了 vim / emacs 两套示例。第四是接更多模型。内置 provider 不够用时models.json里加自定义 provider本地 Ollama、vLLM、公司代理、任何 OpenAI 兼容服务都能挂。如果你想让 pi 同时能切多个模型、又不想一个个配 key可以用 TaoToken 的聚合入口把baseUrl指向https://taotoken.net/api在控制台生成 key 后填进apiKey模型 id 按文档填。这样/model里就能一次看到多个可选模型切换成本很低。想完全离线启动不检查更新等用PI_OFFLINE1 pi。到这里你已经完成了从零安装、接模型、初始化配置到跑通第一个编码任务的完整路径。接下来最值得做的一件事是把你手头真实项目的一个小需求交给 pi比如“给这个函数补边界检查并写测试”在 git 仓库里跑一遍。跑通一次真实任务比读十篇教程都管用。
Pi Coding Agent 0-1 用户手册：从零配置到首个任务跑通
1. 为什么你的 pi 第一次启动就卡在 No models available刚接触 Pi Coding Agent 的开发者十有八九会在第一次敲下pi回车后愣住界面出来了但顶部一行黄字Warning: No models available输入框能打字却没人理你。这不是装坏了也不是版本不对而是 pi 的设计逻辑——它本体只是一个终端里的智能体外壳真正干活的模型需要你自己接上去。没接模型它就像一个没有大脑的终端能显示界面但不会思考。我见过太多人在这里放弃以为要配一堆复杂的环境变量。其实从零到跑通第一个任务核心就三件事装好 pi、给它一个能用的模型入口、在 git 仓库里让它改一次代码并验证结果。这篇手册按“安装 → 接模型 → 初始化配置 → 跑通首个任务 → 排障”的顺序走一遍命令都能直接抄macOS、Linux、Windows 都适用差异处我会单独标出来。先明确 pi 是什么它是一个跑在终端里的开源 AI 智能体coding agent你打一句话它思考、读文件、改文件、跑命令、看图然后把结果交给你。它只有终端界面没有图形窗口这是设计如此。两个预期先摆好第一pi 会在你当前目录里真的动手改文件所以在 git 仓库里用它、改坏能回滚是官方推荐的工作方式第二它的核心故意做得很小MCP、子代理这类进阶能力靠扩展extensions、技能skills、包packages往上加本篇只覆盖核心用法够你跑通第一个任务。适合谁读刚接触 Pi Coding Agent、想在本地快速确认 Agent 能正常工作的开发者不预设公司环境、不预设特定模型。读完你能独立完成一次“让 pi 读代码 → 改代码 → 跑测试 → 验证结果”的闭环。2. 安装 pi 与 Node 环境准备npm 全局安装报错怎么解2.1 先确认 Node 版本pi 要求 Node.js ≥ 20。打开终端敲node -v如果打印v20.x.x或更高就跳过这步。没装或版本太旧macOS 用brew install nodeWindows 和 Linux 去 nodejs.org 下 LTS 版装。Windows 用户注意装完要重开一个终端让 PATH 生效否则node -v还是提示找不到命令。2.2 全局安装 pinpm install -g mariozechner/pi-coding-agent大陆网络慢的话可以这一次临时加国内镜像提速npm install -g mariozechner/pi-coding-agent --registryhttps://registry.npmmirror.com注意是“这一次临时加”别去改全局 npm 配置以免影响你其他包的源。踩过的坑有人图省事npm config set registry改了全局结果公司私有包拉不下来排查半天。2.3 验证安装pi --version打印版本号如0.73.0即成功。以后升级用pi update只升 pi 本体用pi update --self。2.4 安装阶段的常见报错EACCES permission deniedLinux/macOS 上全局目录没权限别用 sudo 硬装改用 nvm 管理 Node或按 npm 官方文档改全局前缀。npm ERR! code EINTEGRITY缓存坏了npm cache clean --force后重装。pi: command not found全局 bin 目录不在 PATH 里。用npm bin -g看路径把它加进 shell 配置。装完先别急着接模型下一步才是关键。3. 给 pi 接上模型auth.json 与 models.json 可复制配置3.1 两条接模型的路先cd到你想让 pi 干活的项目目录再敲pi回车。什么都没配时你会看到Warning: No models available这就是在催你接模型。接模型有两条路路线 A 用/login走 OAuth 登录路线 B 直接配 API key。长期用推荐路线 B配置一次到处能用。常见 provider 与环境变量对照Provider环境变量AnthropicANTHROPIC_API_KEYOpenAIOPENAI_API_KEYGoogle GeminiGEMINI_API_KEYDeepSeekDEEPSEEK_API_KEYOpenRouterOPENROUTER_API_KEYMistralMISTRAL_API_KEYGroqGROQ_API_KEYxAIXAI_API_KEYHugging FaceHF_TOKENKimi For CodingKIMI_API_KEYMiniMax国内MINIMAX_CN_API_KEY3.2 用 auth.json 持久化凭证长期用可直接编辑~/.pi/agent/auth.json文件会自动设成仅本人可读写{ anthropic: { type: api_key, key: sk-ant-... }, openai: { type: api_key, key: sk-... }, deepseek: { type: api_key, key: sk-... } }配好后界面里/model或CtrlL选一个模型就可以开工了。3.3 接任意 OpenAI 兼容服务models.json内置 provider 不够用本地 Ollama、LM Studio、vLLM、公司代理、任何 OpenAI 兼容服务时写~/.pi/agent/models.json。这个文件每次打开/model都会重新读改完不用重启 pi。最小例子本地 Ollama{ providers: { ollama: { baseUrl: http://localhost:11434/v1, api: openai-completions, apiKey: ollama, models: [ { id: qwen2.5-coder:7b } ] } } }Ollama 不校验 keyapiKey 填任意值即可。接任意 OpenAI 兼容服务的完整例子字段含义见注释{ providers: { my-service: { baseUrl: https://你的服务地址/v1, api: openai-completions, apiKey: MY_ENV_KEY, compat: { supportsDeveloperRole: false }, models: [ { id: 模型id, name: 显示名, reasoning: true, input: [text, image], contextWindow: 1000000, maxTokens: 131072 } ] } } }关键字段大白话api是对方说哪种“方言”四选一openai-completions最通用、openai-responses、anthropic-messages、google-generative-ai。input填[text]或[text, image]请如实填——填了 image 却实际不能看图的模型会收到图然后瞎编该锁 text 的就锁 textpi 会在客户端替你拦图。compat.supportsDeveloperRole: false是因为很多 OpenAI 兼容服务不认 developer 角色加上这个让 pi 改发 system若还不认reasoning_effort再加supportsReasoningEffort: false。Ollama、vLLM、SGLang 一类基本都要加。如果你用的是 TaoToken 这类聚合入口把baseUrl指向https://taotoken.net/apiapi填openai-completionsapiKey填你在控制台生成的 key模型 id 按文档里列出的填即可。这样一套配置能同时挂多个模型/model里切换。3.4 配置不生效怎么排查改了models.json没反应确认文件路径是~/.pi/agent/models.json不是项目目录下的。JSON 语法错一个逗号都会静默失败用cat ~/.pi/agent/models.json | python -m json.tool校验一下。/model里看不到新模型baseUrl结尾多了或少了/v1OpenAI 兼容服务通常要带/v1。4. 跑通第一个任务让 pi 读代码、改代码、跑测试4.1 准备工作目录mkdir pi-demo cd pi-demo git init npm init -y建一个待改的小文件src/math.jsfunction add(a, b) { return a b; } module.exports { add };提交一次方便回滚git add . git commit -m init4.2 启动 pi 并选模型pi界面出来后按CtrlL打开模型选择器选你刚配好的模型。状态栏会显示当前模型名和 token 花费。4.3 第一个任务加一个函数并写测试在输入框里打src/math.js 给这个文件加一个 subtract 函数并写一个对应的测试文件 src/math.test.js用 node 内置的 assert注意src/math.js必须是独立参数别把它写进引号里的问题文本否则会被当成普通文件名报File not found。pi 会开始工作读文件、思考、改文件、创建测试文件。你会看到对话区出现工具块默认折叠摘要按ctrlo展开看完整输出。4.4 让它跑测试验证等它改完输入!node src/math.test.js!命令会先跑命令把输出一起发给模型。如果测试通过你会看到类似all tests passed的输出如果失败pi 会读报错并尝试修复。4.5 验证结果退出 pictrld在终端里看 diffgit diff你应该能看到subtract函数被加进src/math.js以及新建的src/math.test.js。再手动跑一次node src/math.test.js打印通过信息说明 Agent 已经正常工作。这一步是整个手册的核心验证点——能读、能改、能跑、结果可复现闭环就通了。4.6 一次性用法不进界面不想进交互界面时pi -p 总结一下这个代码库 cat README.md | pi -p 总结这段文字 pi -p 截图.png 图里是什么 pi --tools read,grep,find,ls -p 审查代码最后一条是只读模式不许改不许跑适合先让 pi 熟悉代码库再动手。脚本集成用--mode json事件流或--mode rpc进程间协议。5. 常见报错排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常见。原因key 填错、key 过期、或者auth.json里 provider 名字和实际用的对不上。排查顺序先cat ~/.pi/agent/auth.json确认 key 没多空格再用 curl 直接打一次接口验证 key 本身有效curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer 你的key如果 curl 也 401是 key 的问题curl 通了但 pi 报 401是 pi 配置里baseUrl或api字段写错了。5.2 local proxy failed这个报错通常出现在你配了本地代理或本地模型服务Ollama、LM Studio但服务没起来。先确认服务在跑curl http://localhost:11434/v1/models连不上就先把本地服务启动。如果models.json里baseUrl写的是http://localhost:11434少了/v1也会报这个。5.3 reading choices / cannot read property choices这是响应格式不匹配。多半是api字段填错了——对方是 Anthropic 方言你填了openai-completions或者反过来。对照服务商文档改api字段。另一个可能是compat.supportsDeveloperRole没设 false服务端返回了非标准结构。5.4 OAuth 登录失败/login走 OAuth 时如果卡在回调或报 token 交换失败先检查系统时间是否准确差几分钟就会失败再确认浏览器能正常打开回调地址。公司网络限制回调端口的话改用 API key 路线更省事。5.5 贴图提示 does not support images当前模型是纯文本模型pi 在客户端把图拦下了。CtrlP换能看图的模型。这不是故障是防止把图发给“会瞎编”的模型。5.6 改了配置没生效models.json每次开/model会重读但auth.json和settings.json改动后建议/reload。AGENTS.md改完也要/reload。5.7 它改坏了我的代码怎么办所以建议在 git 仓库里用 pi。会话里的/tree能回退“对话”但回退不了“文件”——文件回滚靠 git。养成每让 pi 动一次手就 commit 一次的习惯。5.8 回答又慢又贵ShiftTab调低思考级别/compact压缩上下文换便宜模型CtrlP。状态栏实时显示 token 与花费盯着它调。6. 把 pi 用顺手的几个配置与下一步跑通第一个任务后有几件事能让 pi 更贴合你的项目。第一是AGENTS.mdpi 启动时会自动读它当“项目说明书”告诉它这个项目的规矩# Project Instructions - 改完代码跑 npm run check。 - 不要在本地跑生产库迁移。 - 回答保持简洁。全局放~/.pi/agent/AGENTS.md项目级放当前目录及上级目录的AGENTS.md或CLAUDE.md。改完/reload生效。第二是会话管理。会话按工作目录自动保存在~/.pi/agent/sessions/关掉终端也不丢pi -c # 继续最近一次会话 pi -r # 浏览、挑一个历史会话 pi --no-session # 这次不保存 pi --session 路径|id # 打开指定会话界面里/new开新会话/resume挑历史/export导出 HTML/share传成私密 gist 拿分享链接。第三是快捷键。记不住随时/hotkeys看全部。常用的Enter发送它忙时变为排队插话ShiftEnter换行escape打断当前回答ctrlc清空输入框ctrld退出CtrlL模型选择器ShiftTab循环思考级别ctrlo展开工具输出ctrlg把正在写的内容丢进外部编辑器。键位不顺手可以改~/.pi/agent/keybindings.json官方给了 vim / emacs 两套示例。第四是接更多模型。内置 provider 不够用时models.json里加自定义 provider本地 Ollama、vLLM、公司代理、任何 OpenAI 兼容服务都能挂。如果你想让 pi 同时能切多个模型、又不想一个个配 key可以用 TaoToken 的聚合入口把baseUrl指向https://taotoken.net/api在控制台生成 key 后填进apiKey模型 id 按文档填。这样/model里就能一次看到多个可选模型切换成本很低。想完全离线启动不检查更新等用PI_OFFLINE1 pi。到这里你已经完成了从零安装、接模型、初始化配置到跑通第一个编码任务的完整路径。接下来最值得做的一件事是把你手头真实项目的一个小需求交给 pi比如“给这个函数补边界检查并写测试”在 git 仓库里跑一遍。跑通一次真实任务比读十篇教程都管用。
