Pi Coding Agent 入门教程：用 TaoToken 统一 Key 打通 CLI 与 SDK 配置

1. 为什么 Pi Coding Agent 值得配一个统一 KeyPi Coding Agent 是一个跑在终端里的 AI 编码 Agent你给它一句话它就能在当前项目目录里读文件、改文件、执行命令循环调用大模型直到把任务做完。它和 Claude Code、OpenAI Codex CLI 属于同一类工具但设计思路更偏“最小内核 强扩展”官方那句 “There are many agent harnesses but this one is yours” 说的就是这件事——工具本身不塞满功能而是让你按自己的工作流去拼装。它适合谁习惯终端工作流、不想在 IDE 和命令行之间来回切的开发者需要同时接多家模型Anthropic、OpenAI、Google、DeepSeek 等的人以及想把 Agent 能力嵌进自己程序的开发者SDK / RPC 模式。Pi 由四个 npm 包组成普通用户只装最上层的earendil-works/pi-coding-agent就能拿到开箱即用的 CLI。问题在于Pi 本身不含大模型它需要你提供至少一个 Provider 的凭证。如果你手上有好几家 Key或者团队里多人共用一套额度逐个往auth.json里塞、还要记不同环境变量名很快就会乱。这篇就聚焦一件事——用 TaoToken 的统一 Key 和 API 通道把 Pi 的 CLI 与 SDK 配置一次打通然后跑通第一个 Agent 任务。全程可复制装完就能验证通道是否连通、模型是否可用。2. TaoToken 前置拿到统一 Key 与通道地址TaoToken 在这里扮演的角色是“统一入口”你不需要为每个模型厂商分别维护一套 Key 和 base URL而是用同一个 Key、同一个 API 地址去访问不同模型。对 Pi 这种支持自定义 Provider 的工具来说正好可以把 TaoToken 当成一个 OpenAI 兼容的供应商接进去。你需要先准备两样东西一个 TaoToken API Key通道地址https://taotoken.net/api获取 Key 的入口在控制台的 API Keys 页面登录后新建一个即可。建议给这个 Key 起个能认出来的名字比如pi-coding-agent-dev方便以后按用途区分和吊销。注意Key 只显示一次复制后先存进密码管理器或环境变量不要直接写进会提交到 git 的配置文件。关于模型选择TaoToken 的模型对话页可以直接试跑确认某个模型在你的账号下可用再去配 Pi。这一步能省掉很多“配完了才发现模型没权限”的来回。如果你后续要长期跑编码任务或 Agent 自动化可以顺带了解一下 Coding Plan它更适合高频、长会话的场景只是先跑通入门验证的话按量用 API Key 就够了。3. 可复制配置CLI 安装 config.toml settings.json3.1 安装 Pi CLI先确认 Node.js 版本建议 18然后用 npm 全局安装。注意--ignore-scripts参数它会跳过依赖的安装期生命周期脚本Pi 正常使用不需要这些脚本加上更安全npm install -g --ignore-scripts earendil-works/pi-coding-agent装完验证版本pi --version # 例如输出0.80.63.2 用环境变量传入 TaoToken Key最通用的方式是把 Key 放进环境变量。Linux / macOSexport TAOTOKEN_API_KEY你的 TaoToken API KeyWindows PowerShell$env:TAOTOKEN_API_KEY你的 TaoToken API Key想持久化就写进~/.bashrc、~/.zshrc或系统环境变量里。3.3 config.toml 骨架Pi 的自定义 Provider 走models.json但很多团队习惯用一份config.toml统一管理本地参数。下面这份骨架把 TaoToken 作为 OpenAI 兼容供应商接进来放在项目根目录或~/.pi/agent/下都行# config.toml —— Pi Coding Agent 接入 TaoToken 统一通道 [provider.taotoken] name TaoToken base_url https://taotoken.net/api api openai-completions api_key_env TAOTOKEN_API_KEY [[provider.taotoken.models]] id claude-sonnet name Claude Sonnet (via TaoToken) context_window 200000 max_tokens 8192 input [text] [[provider.taotoken.models]] id gpt-4o name GPT-4o (via TaoToken) context_window 128000 max_tokens 4096 input [text]这里的关键字段是base_url指向https://taotoken.net/apiapi用openai-completions协议api_key_env指向你刚设的环境变量名。模型 id 按你账号下实际可用的填别照抄。3.4 settings.json 骨架settings.json用来控制 Pi 的运行时行为比如默认模型、思考强度、项目信任策略。放在~/.pi/agent/settings.json全局或.pi/settings.json项目级{ defaultProvider: taotoken, defaultModel: claude-sonnet, defaultProjectTrust: ask, thinkingLevel: medium, tools: [read, write, edit, bash] }defaultProjectTrust设成ask是稳妥做法进入带.pi/配置的仓库时Pi 会先问你信不信任避免仓库静默加载扩展改你的设置。3.5 SDK 侧配置如果你要在自己的 Node 程序里嵌入 PiSDK 模式同样读这套 Provider 配置。最小示例import { createAgent } from earendil-works/pi-coding-agent; const agent await createAgent({ provider: taotoken, model: claude-sonnet, apiKey: process.env.TAOTOKEN_API_KEY, baseUrl: https://taotoken.net/api, }); const result await agent.run(列出当前目录下所有 .ts 文件并统计行数); console.log(result.text);CLI 和 SDK 共用同一个 Key、同一个 base URL这就是“统一 Key 打通”的实际含义——换模型只改model字段通道不用动。4. 验证请求跑通第一个 Agent 任务配置写完先做一次最小验证确认通道连通、模型可用。4.1 非交互式单次提问用-p让 Pi 回答完就退出最适合脚本化验证pi -p 用一句话说明当前目录是什么项目如果返回了合理回答说明 Key、base URL、模型三者都通了。如果报鉴权错误先回去查环境变量有没有生效。4.2 跑一个真正的 Agent 任务单次问答只验证了对话通道Agent 任务还要验证工具调用循环。进入一个测试项目目录cd /path/to/my-project pi -p 统计 src 目录下每个 .ts 文件的行数输出一个表格Pi 会自动调用read、bash等工具读文件、跑命令最后给出表格。你能在输出里看到它调用了哪些工具、执行了什么命令——这就是 agent 循环在跑。4.3 交互模式确认模型切换启动交互模式pi在编辑器里输入/model应该能看到taotoken下的模型列表。选一个切换再发一句话确认响应正常。这一步验证的是多模型切换是否走同一个通道。4.4 验证结果对照验证项命令期望结果版本pi --version输出具体版本号通道连通pi -p 你好返回模型回复无鉴权报错工具调用pi -p 统计 .ts 文件行数输出表格过程有工具调用模型切换交互模式/model列出 taotoken 下模型并可切换SDK 嵌入运行 SDK 示例打印 Agent 返回文本5. 本篇常见错排查5.1 报 401 / 鉴权失败最常见的原因是环境变量没生效。先确认echo $TAOTOKEN_API_KEY如果为空说明当前 shell 没加载。检查是不是写进了别的 shell 的配置文件或者新开终端后忘了重新 export。另一个坑是auth.json里的旧凭证优先级高于环境变量如果之前手动配过别的 Key去~/.pi/agent/auth.json里清掉冲突项。5.2 报模型不存在 / model not foundconfig.toml或models.json里的模型 id 必须和 TaoToken 账号下实际可用的对齐。先去模型对话页确认模型名再回填。别照抄示例里的claude-sonnet那只是占位。5.3 base URL 写错导致连接超时通道地址是https://taotoken.net/api注意结尾不要多加/v1之类的路径除非文档明确要求。多一层路径会 404。用 curl 快速验证curl -s https://taotoken.net/api/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head能返回模型列表就说明地址和 Key 都对。5.4 工具调用不触发如果 Pi 只聊天不调工具检查settings.json里的tools数组有没有把read、bash等加进去。另外用--tools参数可以临时限定pi --tools read,grep,find,ls -p 审查这段代码只读模式适合先观察 Agent 行为确认没问题再放开写权限。5.5 项目信任弹窗反复出现信任决策存在~/.pi/agent/trust.json按目录路径记录。如果你在多个临时目录里跑每次都会问。确认仓库可信后可以用-a参数跳过或在settings.json里把defaultProjectTrust设为always。但别对来路不明的仓库这么干。5.6 SDK 里读不到环境变量Node 程序不会自动继承你 shell 里 export 的变量取决于启动方式。用dotenv加载.env或者在启动命令前显式带上TAOTOKEN_API_KEYxxx node your-agent.js排查时优先看这几点Key 是否生效、base URL 是否精确、模型 id 是否真实存在、凭证优先级是否冲突。这四样对了通道基本就通了。6. 接下来怎么走通道打通之后Pi 的玩法才刚开始。你可以把常用模型固定进settings.json的defaultModel用/model在任务复杂度变化时临时切换也可以写一个扩展把团队内部的接口注册成自定义工具让 Agent 直接调用。如果你打算长期跑编码任务、Agent 自动化或者多会话并行按量 API Key 之外可以看看 Coding Plan它在高频场景下更省心。想先试模型效果模型对话页可以直接对比不同模型在同一任务上的表现确认哪个更适合你的项目再写进配置。配置这件事一次写对后面就是复制粘贴。把config.toml和settings.json存进你的 dotfiles 仓库换机器时几分钟就能恢复整套 Agent 环境。