1. 从 Pi 的“功能缺失”说起为什么它敢不做计划模式如果你最近在折腾 AI 编程 Agent大概率见过一种很统一的界面输入一句话它先给你列一个 Todo List再拆成若干子任务然后挨个执行、汇报进度。看起来很爽但用久了你会发现一个问题——这套流程是它替你定好的你只能顺着走。PiPi 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.jsonAgent 行为与工具边界{ 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_KEYsk-你的KeyWindows 用户用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结尾不要加/v1TaoToken 的兼容层会自动处理路径。加了反而可能 404。4. 三步验证启动、触发任务、检查日志配置写完不算完得跑一遍确认通道真的通了。下面三步是我自己每次换环境都会走的流程。4.1 第一步启动 Agent 并确认模型加载安装 Pi 的编码 Agentnpm 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是不是taotokenendpoint是不是指向taotoken.net/apistatus是不是 200。如果 endpoint 显示的是别的域名说明配置没生效Agent 可能读了默认配置或者环境变量覆盖了你的设置。到这一步通道就算验证完了。你可以把日志留着后面排查问题时会很有用。5. 本篇常见错排查配置过程中最容易踩的坑集中在几个地方我按出现频率排一下。鉴权 401九成是环境变量没读到。Pi 启动时读的是进程环境如果你在.zshrc里 export 但没source新开的终端读不到。另一个可能是 Key 复制时带了空格用echo $TAOTOKEN_API_KEY | wc -c看长度对不对。模型名 404TaoToken 的模型名要和通道支持的列表对齐。如果你写了一个不存在的模型名返回的可能是 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 最终长成什么样由你决定。