1. 为什么四个工具、一千 Token 的 Pi 值得单独聊如果你最近在折腾编码 Agent大概率会有一种疲惫感工具越装越多系统提示词越写越长每次版本更新后行为都可能变。你调好的工作流可能因为一次升级就失效。更隐蔽的问题是上下文窗口被 harness 默认内容吃掉一大块你根本不知道模型实际看到了什么。Pi 走的是另一条路。它默认只给模型四个工具read、write、edit、bash。系统提示词控制在 1000 token 量级是目前主流 harness 里最短的一档。没有内置 sub-agent没有 plan mode没有权限弹窗没有内置 todo也明确不做 MCP。听起来像功能缺失但换个角度看这是把上下文预算和工具编排的控制权交回给你。这篇文章聚焦一件事Pi 凭什么用四个工具、一千 Token 跑赢 Codex 与 Claude Code。我会拆解它的工具编排与 Token 控制策略给出可复制的 Pi 配置骨架并用 TaoToken 统一 Key/API 通道接入示例最后给出对比验证动作和 Token 消耗观测方法。适合已经在用 Claude Code 或 Codex、但对 harness 越来越重感到不适的开发者。先说结论Pi 的赢法不是模型更强而是 harness 层开销更小、上下文更干净、工具选择熵更低。同一个模型在不同 harness 下的产出质量差异往往比换模型本身还大。2. TaoToken 前置统一 Key 与 API 通道在动手配 Pi 之前先把模型通道理顺。Pi 支持多种 provider但如果你手上有多个模型来源逐个配环境变量会很乱。TaoToken 提供统一 Key 和 API 通道一个 Key 就能覆盖多种模型省去反复切换配置的麻烦。TaoToken 官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个不加 UTM。你需要先在控制台创建 API Key然后把它配到 Pi 的环境变量里。这里要强调一点TaoToken 是合规的 API 聚合通道不是灰色中转。你通过它调用模型走的是标准 API 协议Pi 侧只需要按 OpenAI 或 Anthropic 兼容格式配置即可。具体操作路径打开控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite查看 API Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档参考https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite拿到 Key 之后先别急着写 Pi 配置。建议先用模型对话页面验证一下 Key 是否可用、模型是否正常返回https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。这一步能排除掉大部分「Key 没生效」的低级问题。注意API Key 属于敏感凭证不要写进会提交到 git 的配置文件。用环境变量或本地未跟踪的配置文件管理。3. 可复制的 Pi 配置骨架Pi 的安装很直接npm 全局装即可npm install -g --ignore-scripts earendil-works/pi-coding-agent--ignore-scripts会禁用依赖包的生命周期脚本。Pi 在常规 npm 安装下不需要任何 install script加上这个参数是纯收益的安全习惯。装完后命令是pi。接下来是配置骨架分三块模型通道、系统提示词、项目约束。3.1 模型通道配置Pi 支持通过环境变量接入 OpenAI 兼容或 Anthropic 兼容的 provider。用 TaoToken 统一通道时配置大致如下# TaoToken 统一 Key export TAOTOKEN_API_KEYsk-你的key # 指向 TaoToken 的 API 入口 export OPENAI_BASE_URLhttps://taotoken.net/api/v1 export OPENAI_API_KEY$TAOTOKEN_API_KEY如果你用的是 Anthropic 兼容格式则配置对应的 base URL 和 Key。Pi 的 provider 层直接对接原生协议所以只要协议对得上就能正常跑工具调用。对于尚未收录的模型可以写进~/.pi/agent/models.json只要它讲的是 OpenAI、Anthropic、Google 三种 API 之一{ providers: { taotoken: { baseUrl: https://taotoken.net/api/v1, apiKey: $TAOTOKEN_API_KEY, api: openai-completions, models: [ { id: your-model-id, name: Your Model, reasoning: false, input: [text], contextWindow: 128000, maxTokens: 4096 } ] } } }3.2 系统提示词直接接管这是 Pi 区别于多数 harness 的地方。你可以用.pi/SYSTEM.md项目级或~/.pi/agent/SYSTEM.md全局替换默认系统提示词。不想替换只想追加就用APPEND_SYSTEM.md。一千 Token 的默认提示词已经够短但如果你想让 Agent 扮演特定角色比如严格的代码审核者直接重写 SYSTEM.md 比堆叠一堆 prompt 技巧有效得多。3.3 项目约束AGENTS.mdPi 启动时按顺序加载并拼接 AGENTS.md全局~/.pi/agent/AGENTS.md、从当前目录往上各级父目录、当前目录。如果某个目录下有AGENTS.override.md它会替掉该目录的 AGENTS.md其他目录的仍然拼接。monorepo 里这个机制很好用根目录放通用规范特殊子包用 override 完全接管。不想加载任何上下文文件加--no-context-files简写-nc。3.4 工具编排四个工具怎么分工Pi 的四个工具职责非常清晰工具作用编排要点read读文件只把必要片段给模型完整元信息给 UIwrite写文件新建或整体覆盖edit改文件精确替换避免整文件重写bash执行命令万能工具写一次性脚本比调专用工具更可靠关键洞察在这里bash 本身就是万能工具。与其给模型 25 个专用工具让它做选择不如给 4 个工具让模型用 bash 组合出能力。工具越少模型做工具选择时的错误率越低。4. 验证请求与成功结果配置完成后先做一次最小验证确认通道和工具都正常。4.1 启动与模型选择pi进入交互模式后用/model或CtrlL打开模型选择器。在选择器里按CtrlS可把当前高亮模型存为启动默认。CtrlP/ShiftCtrlP在常用模型间前后循环用/scoped-models维护这个循环列表。如果模型目录没刷新执行pi update --models4.2 一次最小请求在编辑器里输入一个简单任务比如读取 package.json告诉我项目名和依赖数量正常情况下你会看到模型调用 read 工具然后返回结果。页脚会显示 token 用量↑ 输入、↓ 输出、R 缓存读、W 缓存写、CH 最近一次缓存命中率、成本、上下文占用、当前模型。把成本和缓存命中率常驻页脚是 Pi 很务实的设计。你能实时看到「这一轮为什么突然贵了」。4.3 验证工具编排再试一个需要多工具协作的任务找出 src 下所有 .ts 文件里 console.log 的数量输出统计观察模型怎么用 bash 组合 grep 和 wc而不是调用某个专用统计工具。这就是四个工具跑赢的关键模型用 bash 自由组合而不是在工具列表里做选择题。4.4 验证 Token 消耗页脚的 token 用量是实时观测入口。做一次对比同一个任务在 Pi 里跑一次记录输入 token 和缓存命中率在 Claude Code 或 Codex 里跑同样的任务记录同样的指标。你会发现Pi 的输入 token 明显更低缓存命中率更高。原因很简单系统提示词短且稳定KV cache 的有效前缀更长重复轮次的实际计费 token 下降。5. 本篇常见错排查5.1 模型不返回或报 401先检查环境变量是否生效echo $OPENAI_API_KEY echo $OPENAI_BASE_URL如果 Key 为空说明 export 没在当前 shell 生效。TaoToken 的 Key 要确认没有多余空格。base URL 要指向https://taotoken.net/api/v1不要漏掉/v1。5.2 工具调用失败Pi 直接对接 provider 原生协议工具调用对协议格式敏感。如果模型返回了工具调用但执行失败先确认你用的模型是否支持 tool calling。部分模型在 OpenAI 兼容层下工具调用支持不完整。用 TaoToken 的模型对话页面先验证模型本身是否正常https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。如果对话正常但工具调用异常问题多半在协议格式。5.3 上下文被默认内容挤占如果你发现输入 token 比预期高检查是不是加载了太多 AGENTS.md。用--no-context-files启动一次对比看 token 差异。启动头部的信息区会显示已加载的 AGENTS.md、prompt 模板、skills、extensions这是确认「上下文里到底装了什么」的第一手信息。5.4 缓存命中率低缓存命中率低通常意味着系统提示词或上下文前缀在变动。检查是否频繁修改 SYSTEM.md是否每轮都注入变动的记忆内容是否加载了大量动态 skill 描述Pi 的 skill 机制是渐进式披露启动时只提取 name 和 description完整内容等模型需要时再读。这样常驻成本只是几十行描述且描述集合在会话内不变不会打破 prompt 缓存。5.5 会话太长导致压缩长会话会耗尽上下文窗口。Pi 默认开启自动压缩手动用/compact。关键一点压缩是有损的但不会销毁历史。完整历史仍在 JSONL 文件里随时可以用/tree回到压缩前的任意位置。如果你需要自定义压缩策略比如用更便宜的模型做摘要可以通过扩展的session_before_compact钩子接管。6. 长期编码与 Agent 场景的接入建议如果你打算把 Pi 当日常生产工具尤其是长期编码或 Agent 场景建议走 Coding Plan 通道成本更可控https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI Key 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite模型对话验证页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite我自己的做法是日常高强度编码用 Pi需要某个重型 harness 特有能力时切回原来的工具skills 目录两边共享避免重复建设。这样既拿到了 Pi 的上下文控制粒度又不丢掉已有生态。最后留一个实用技巧把!和!!用起来。!command执行 shell 并把输出交给模型!!command执行 shell 但不交给模型。你经常需要跑一次git diff或npm test判断现状——如果结果需要模型看用!如果只是自己确认用!!一个 token 都不浪费。这是上下文预算思路在交互层的直接体现。