1. 从 Pi 的“功能缺失”说起：为什么它敢不做计划模式
如果你最近在折腾 AI 编程 Agent，大概率见过一种很统一的界面：输入一句话，它先给你列一个 Todo List，再拆成若干子任务，然后挨个执行、汇报进度。看起来很爽，但用久了你会发现一个问题——这套流程是它替你定好的，你只能顺着走。
Pi（Pi Agent Harness）走的是另一条路。它的 README 里明确写着：不内置子代理、不内置计划模式、不内置待办列表、不提供后台 Bash，连 MCP 都没放进核心。第一次看到这段描述，我以为是功能没做完，翻完包结构和调用链才反应过来，这是刻意的设计取舍。
它把“计划”这件事从核心里拿掉了，交给你用文件、扩展或者外部工具去实现。核心只保留 Agent 运行时该有的东西：状态、消息、工具执行、事件流。换句话说，Pi 不替你决定工作流，它只保证模型能真正动手改代码。
这篇文章不聊空泛的设计哲学，重点解决一个具体问题：怎么在本地把 Pi 类 Agent 跑起来，并且让它通过 TaoToken 的统一 API 通道调用模型。我会给出可复制的settings.json和config.toml骨架，再走一遍三步验证：启动 Agent、触发一次无计划模式任务、检查请求日志确认通道生效。适合已经用过一两个 AI 编程工具、想搞清楚配置层到底发生了什么的人。
2. 前置准备：TaoToken 统一 Key 与 API 通道
Pi 这类 Agent 的核心抽象是pi-ai这一层，它把不同厂商的模型、鉴权、工具调用、流式输出统一到一套接口下。这意味着你不需要为每个模型单独写适配代码，只要提供一个兼容 OpenAI 协议的 endpoint 和 Key，就能接进来。
TaoToken 在这里扮演的角色就是那个统一入口。你申请一个 Key，拿到一个 API 地址，然后所有模型调用都走这个通道。对 Agent 来说，它只知道自己连了一个 OpenAI 兼容服务，不关心背后是哪个模型。
先做两件事：
第一，去控制台创建一个 API Key。地址是https://taotoken.net/console，登录后在 API Keys 页面新建一个，复制出来，形如sk-xxxxxxxx。这个 Key 只显示一次，建议先存到本地环境变量里，别直接写进会提交到 Git 的配置文件。
第二，确认 API 基础地址。TaoToken 的 API 入口是https://taotoken.net/api，注意这个地址不带任何查询参数，配置时直接用它作为base_url。
注意：不要把 Key 硬编码进
settings.json然后提交到仓库。用环境变量引用，或者放在.gitignore覆盖的本地文件里。
如果你还没决定用哪个模型，可以先在模型对话页面试一下通道是否通：https://taotoken.net/models。这一步不是必须的，但能帮你排除“Key 本身有问题”这种低级错误。
3. 可复制配置：settings.json 与 config.toml 骨架
Pi 的配置分两层：一层是 Agent 自己的行为配置，通常放在项目根目录或用户目录下的settings.json；另一层是模型通道配置，很多团队习惯用config.toml管理。下面两份骨架你可以直接抄，改掉 Key 和模型名即可。
3.1 settings.json：Agent 行为与工具边界
{ "agent": { "name": "pi-local", "mode": "interactive", "planMode": false, "subAgents": false, "todoList": false, "backgroundBash": false }, "tools": { "read": true, "write": true, "edit": true, "bash": { "enabled": true, "parallel": true, "timeoutMs": 120000 } }, "session": { "storage": "jsonl", "tree": true, "autoCompact": true, "compactThreshold": 0.8 }, "model": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "model": "claude-sonnet-4-20250514", "stream": true } }几个关键字段解释一下。planMode设为false是刻意的，Pi 本来就不内置计划模式，这里显式关掉是防止某些扩展偷偷打开。tools.bash.parallel设为true表示工具可以并行执行，如果你在调试复杂任务，建议先改成false，方便看日志。session.tree打开树状会话，配合 JSONL 存储，你可以在任意节点 fork 出新分支。
apiKeyEnv指向环境变量名，而不是 Key 本身。启动前先执行：
export TAOTOKEN_API_KEY="sk-你的Key"Windows 用户用set或 PowerShell 的$env:语法，效果一样。
3.2 config.toml：模型通道与多 Provider 切换
[default] provider = "taotoken" model = "claude-sonnet-4-20250514" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" stream = true timeout_seconds = 120 [providers.taotoken] type = "openai-compatible" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" [providers.taotoken.models] fast = "gpt-4o-mini" balanced = "claude-sonnet-4-20250514" reasoning = "deepseek-reasoner" [context] auto_compact = true compact_ratio = 0.8 preserve_tool_results = true [logging] level = "info" request_log = "./logs/pi-requests.jsonl"这份 TOML 里我加了request_log，这是后面验证通道是否生效的关键。日志会以 JSONL 格式记录每次请求的 endpoint、模型名、耗时和 token 数。providers.taotoken.models里定义了三个档位的模型，你可以在 Agent 运行时通过命令切换，比如常规任务用fast，复杂重构切到reasoning。
提示：
base_url结尾不要加/v1，TaoToken 的兼容层会自动处理路径。加了反而可能 404。
4. 三步验证：启动、触发任务、检查日志
配置写完不算完，得跑一遍确认通道真的通了。下面三步是我自己每次换环境都会走的流程。
4.1 第一步：启动 Agent 并确认模型加载
安装 Pi 的编码 Agent：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent然后在你想要操作的项目目录下启动：
cd ~/projects/my-app pi --config ./settings.json如果一切正常，终端会进入交互模式，顶部状态栏显示当前模型名和 provider。如果显示的是unknown或者直接报鉴权错误，先检查环境变量有没有 export 成功：
echo $TAOTOKEN_API_KEY输出应该是sk-开头的一串字符。如果为空，说明当前 shell 会话没读到，重新 export 一次再启动。
4.2 第二步：触发一次无计划模式任务
Pi 不做计划模式，所以你的指令要直接落到具体动作上。比如让它读一个文件并改一行：
读取 src/utils/format.ts，把 formatDate 函数里的 'YYYY-MM-DD' 改成 'YYYY/MM/DD'，改完告诉我改了哪一行。注意这个指令没有“先列计划”“分几步”这种要求。Pi 会直接调用read工具读文件，然后调用edit工具改内容，最后返回结果。整个过程你能在终端看到工具调用事件流，而不是一个 Todo List 在打勾。
如果你看到它开始输出“首先我会……然后我会……”这种计划式文本，说明某个扩展或者系统提示词在起作用，检查settings.json里有没有加载额外的 prompt template。
4.3 第三步：检查请求日志确认通道生效
任务跑完后，去看config.toml里配置的日志文件：
tail -n 5 ./logs/pi-requests.jsonl每行应该是一条 JSON，包含类似字段：
{"ts":"2025-06-01T10:23:45Z","provider":"taotoken","model":"claude-sonnet-4-20250514","endpoint":"https://taotoken.net/api/chat/completions","status":200,"latency_ms":1840,"prompt_tokens":1203,"completion_tokens":156}重点看三个地方：provider是不是taotoken，endpoint是不是指向taotoken.net/api，status是不是 200。如果 endpoint 显示的是别的域名，说明配置没生效，Agent 可能读了默认配置或者环境变量覆盖了你的设置。
到这一步，通道就算验证完了。你可以把日志留着，后面排查问题时会很有用。
5. 本篇常见错排查
配置过程中最容易踩的坑集中在几个地方，我按出现频率排一下。
鉴权 401：九成是环境变量没读到。Pi 启动时读的是进程环境，如果你在.zshrc里 export 但没source，新开的终端读不到。另一个可能是 Key 复制时带了空格，用echo $TAOTOKEN_API_KEY | wc -c看长度对不对。
模型名 404：TaoToken 的模型名要和通道支持的列表对齐。如果你写了一个不存在的模型名，返回的可能是 404 而不是 400。先去模型对话页面确认可用模型名，再填进配置。
工具调用不执行：检查settings.json里tools.bash.enabled是不是true，以及当前用户有没有执行权限。有些容器环境默认禁止子进程，Agent 会卡在工具调用那一步。
会话文件膨胀：JSONL 会话文件会随着对话变长越来越大。autoCompact打开后会在上下文达到阈值时自动压缩，但完整历史仍然保留在文件里。如果磁盘紧张，定期归档旧的 JSONL 文件。
并行工具导致日志乱序：tools.bash.parallel为true时，多个工具同时执行，日志时间戳可能交错。调试阶段建议先关掉并行，等流程跑通再打开。
注意：如果你在容器或沙箱里跑 Pi，确保容器能访问外网，并且 DNS 能解析
taotoken.net。有些隔离环境默认只允许内网，会导致请求超时。
6. 继续往下走：从验证到长期使用
通道验证通过之后，你手里就有了一套可复现的本地 Agent 环境。接下来可以做的事取决于你的使用场景。
如果你只是偶尔用它改改代码，现在的配置就够了。把settings.json和config.toml放进项目模板，下次新项目直接复制，改一下模型名就能用。
如果你打算把它接进日常编码流程，比如让它跑测试、做重构、维护 TODO 文件，那可以考虑 Coding Plan 这条路径：https://taotoken.net/coding-plan。它更适合长时间运行的编码任务，上下文管理和模型切换策略会更省心。
如果你想把 Agent 嵌进自己的工具链，比如通过 RPC 或 SDK 调用，那就需要去看接入文档：https://taotoken.net/doc。里面会讲清楚流式输出、工具调用事件和上下文交接的具体协议。
回到最开始那个问题——Pi 为什么故意不做计划模式。跑完这一套配置你大概能感觉到，计划模式本质上是一种预设的工作流。Pi 把这块空白留出来，不是因为它做不到，而是因为它不想替你把工作流定死。你可以用文件写计划，可以用扩展实现待办，也可以什么都不用，直接让模型动手。
方向盘留给自己，代价是配置要多写几行。但换来的是，这套 Agent 最终长成什么样，由你决定。
