1. Pi Agent 到底解决什么问题Pi 是一个把「极简」做到骨子里的 AI Agent。它默认只带四个基础工具读文件、写文件、改文件、跑命令系统提示词大约 1000 Token。你在 Pi 里说一句「你好」上传 Token 大概 1100占上下文 0.4% 左右而在 Codex 里打个招呼就可能吃掉 18000 Token什么都没干先消耗 7% 的上下文窗口。这个差距在长任务里会被放大成真金白银的成本差和响应速度差。它适合谁适合已经用过 Claude Code、Codex但被它们的重上下文、重工具链拖慢节奏的开发者也适合想把 Agent 当一次性 CLI 命令用的人。Pi 没有 MCP、没有 SubAgent、没有 Plan Mode、没有 Todo这些能力全部通过插件和 Skills 按需拼装。官网首页那句话很能说明设计取向让工具来适应你的工作流而不是让你去适应工具。但极简也带来一个现实问题Pi 本身不绑定任何模型供应商你需要自己接模型通道。如果你同时用 Claude Code、Codex、Pi 三套工具每个都配一遍 Key、改一遍 base_url维护成本会迅速失控。这篇就围绕「统一 Key/API 通道 Pi 配置 Skills 扩展」这条线把 settings.json、config.toml、CC Switch 片段和验证动作一次讲透。2. TaoToken 前置统一 Key 与 API 通道TaoToken 在这里扮演的角色是「一个 Key 打通多个 AI 工具」的接入层。你不需要为 Pi、Claude Code、Codex 分别申请不同厂商的 Key而是用同一套 API 通道把模型调用统一收口。对 Pi 这种「模型可插拔」的 Agent 来说这一点尤其关键因为 Pi 的模型配置就是围绕 provider base_url api_key 三件套展开的。先把入口记清楚后面配置会反复用到官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址https://taotoken.net/api这个地址不加 UTM直接用于配置模型对话体验https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan长期编码/Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaude Code / Anthropic 接入https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite注意API 基址统一用https://taotoken.net/api不要在后面拼多余的路径Pi 和 CC Switch 都会在这个基址上自动补全/v1/chat/completions之类的端点。拿到 Key 的路径是进控制台 → API Keys → 新建 → 复制。这个 Key 就是后面所有配置文件里api_key字段的值。建议单独建一个给 Pi 用的 Key方便按工具维度排查调用量和费用。3. 可复制配置settings.json / config.toml / CC SwitchPi 的配置分两层全局配置放在用户目录下的.pi文件夹项目级配置放在项目根目录的.pi文件夹。模型 provider 一般写在全局Skills 和插件可以按项目粒度覆盖。3.1 Pi 的 settings.json 骨架Pi 读取模型配置时核心字段是 provider 名称、base_url、api_key、model。下面这份settings.json可以直接复制把sk-你的TaoTokenKey换成你自己的{ providers: { taotoken: { base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, models: [ { id: claude-opus-4-8, name: Claude Opus 4.8, context_window: 200000 }, { id: gpt-5-6-sol, name: GPT 5.6 Sol, context_window: 272000 } ] } }, default_model: taotoken/claude-opus-4-8, default_thinking: medium }这份配置里default_model用的是provider/model的写法Pi 启动时会按这个去匹配 provider 下的 models 列表。default_thinking控制思考强度可选 low / medium / high对应 ShiftTab 的切换档位。3.2 config.toml 版本适合偏好 TOML 的场景有些团队习惯用 TOML 管理配置Pi 同样支持。下面这份config.toml和上面的 JSON 等价default_model taotoken/claude-opus-4-8 default_thinking medium [providers.taotoken] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey [[providers.taotoken.models]] id claude-opus-4-8 name Claude Opus 4.8 context_window 200000 [[providers.taotoken.models]] id gpt-5-6-sol name GPT 5.6 Sol context_window 272000提示JSON 和 TOML 二选一即可不要同时放两份否则 Pi 的加载顺序可能让你以为配置没生效。3.3 CC Switch 配置片段如果你同时用 Claude Code 和 PiCC Switch 是切换 provider 的常用工具。它的配置本质也是把 base_url 和 api_key 指向同一套通道。下面是一个 CC Switch 的 provider 片段{ name: taotoken, base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, models: { default: claude-opus-4-8, fast: gpt-5-6-sol } }把这段合并进 CC Switch 的 providers 数组后你在 Claude Code 和 Pi 之间切换时底层走的是同一个 Key 和同一个 API 基址。这样排查问题时只需要看一个通道的日志不用在多个厂商后台之间来回跳。3.4 Skills 目录结构Pi 遵循标准 Agent Skills 协议Skills 放在.agents/skills/下面。项目级放项目根目录全局级放用户目录项目目录/ └── .agents/ └── skills/ └── playwright-cli/ └── SKILL.md 用户目录/ └── .agents/ └── skills/ └── playwright-cli/ └── SKILL.md只要SKILL.md在对应目录下Pi 启动时就会自动识别并在 Skills 列表里显示。想关掉某个 Skill直接在 Web UI 的技能面板里切换开关即可关掉后提示词里不再注入能省 Token。4. 验证请求确认 Agent 调用真的生效配置写完不代表生效必须做一次可观测的验证。下面这套动作我实测下来最直接。第一步启动 Pi 并确认模型加载pi进入对话窗口后输入/model看列表里有没有taotoken/claude-opus-4-8。如果没有说明settings.json的路径或字段名有问题优先检查 provider 名称是否和default_model前缀一致。第二步发一条会触发工具调用的指令而不是纯聊天。比如在当前目录创建一个 hello.txt内容写 taotoken ok然后读出来确认如果 Pi 正常调用写文件和读文件工具并且底部状态栏显示输入/输出 Token、缓存命中率、上下文占用百分比说明模型通道和工具链都通了。重点看两个数Cache Read 是否大于 0上下文占用是否在合理范围。如果 Cache Read 一直是 0可能是 base_url 拼错导致每次都是新请求。第三步用非交互模式做一次静默验证pi -p 查询当前目录文件数量写入 count.txt执行完后检查count.txt是否生成。非交互模式特别适合把 Pi 当一次性 CLI 命令用也适合放进脚本做冒烟测试。第四步验证 Skills 是否被识别。启动 Pi 后看加载日志里有没有[Skills]段落或者在 Web UI 的技能面板里确认目标 Skill 处于开启状态。如果 Skill 没出现九成是SKILL.md放错了层级注意是.agents/skills/技能名/SKILL.md不是.agents/skills/SKILL.md。5. 本篇常见错排查5.1 报 401 / invalid api key先确认api_key字段没有多余空格JSON 里字符串不能换行。然后确认 Key 是从 API Keys 页面新建的、状态是启用。如果 Key 没问题检查 base_url 是不是写成了带路径的地址正确写法就是https://taotoken.net/api不要加/v1。5.2 模型列表为空/model里看不到任何模型通常是providers下的models数组没写对或者default_model的前缀和 provider 名称不匹配。比如 provider 叫taotokendefault_model就必须是taotoken/xxx写成taotoken.net/xxx会匹配失败。5.3 Skills 不生效按这个顺序查SKILL.md文件名是否全大写、目录是否是.agents/skills/技能名/、项目启动时是否提示信任当前目录。Pi 在陌生目录启动会询问是否信任并加载插件/Skill选不信任就不会加载。另外项目级 Skill 只对当前项目生效换目录就看不到了需要放到全局.agents目录。5.4 上下文占用异常高如果打个招呼就占用很高百分比检查是不是装了太多全局插件。每装一个插件都会增加系统提示词用不到的插件建议在 Web UI 里关掉。另外执行完一轮任务后优先用/new新开 Session 清空上下文而不是依赖/compact压缩。Agent 领域的通用经验是清空好于压缩过多历史会干扰模型注意力。5.5 工具调用被安全机制拦截Pi 本身没有沙箱运行后就是最高权限。如果你装了权限类插件敏感操作会弹审批窗口。如果发现命令没执行先看是不是审批被拒。想彻底隔离建议把 Pi 放进容器或虚拟机里跑它启动快、占用低很适合容器化批量部署。6. 把 Pi 接进你的日常工作流配置跑通之后真正决定效率的是 Skills 的组合方式。我的做法是全局只留通用 Skill比如浏览器自动化、文档转换项目级放和当前仓库强相关的 Skill插件按需开、用完关。模型通道统一走 TaoToken 的 API 基址Pi、Claude Code、Codex 共用一个 Key切换工具时不用重新配环境。如果你还在验证阶段想先确认模型对话是否正常可以直接用模型对话入口试一条请求如果准备长期把 Pi 当编码 Agent 用建议走 Coding Plan把调用量和成本纳入统一管理。接入过程中遇到 Key 或 base_url 的问题先翻接入文档再对照 API Keys 页面确认 Key 状态。把这几步做完Pi 的极简工作流基本就能稳定跑起来了。
