1. 初次上手 Π agent模型配置、SKILL 与 Session 管理到底解决什么问题Π agent也写作 Pi agent是一个跑在终端里的编码智能体它能读你本地的代码仓库、执行命令、改文件、跑测试把「对话式编程」落到真实工程目录里。很多人第一次听到它会把它和网页版聊天机器人混为一谈其实差别很大网页版只能给你一段代码让你自己复制而 Π agent 直接在你的项目里动手改完还能自己验证。它适合谁适合已经会用命令行、想让 AI 真正参与日常开发流程的开发者尤其是那些厌倦了「复制粘贴—手动改路径—再报错」循环的人。但初次接触 Π agent 的人卡点往往不在「它能不能写代码」而在三个基础环节模型怎么配、SKILL 和 Extensions 怎么启用、Session 怎么管理。这三个环节没打通你会觉得它「时好时坏」——其实是配置没到位。这篇就按「配置模型 → 启用 SKILL 与 Extensions → 管理 Session」的顺序给你一份能直接复制、逐步验证的最小可用流程同时说明怎么用 TaoToken 统一 Key 和 API 通道接入省去到处找 Key、改 baseUrl 的麻烦。先说清楚 Π agent 的配置文件结构这是后面所有操作的地基。它的模型配置放在用户主目录下的~/.pi/agent/models.jsonSession 和认证信息在~/.pi/agent/目录里项目级的 SKILL 则放在项目根目录的.pi/skills/或.agents/skills/。理解了这个目录约定你后面遇到「配置改了没生效」时第一反应就知道该去哪个路径确认。我实测下来最容易出问题的是模型配置里的api字段和baseUrl结尾的斜杠。api要写openai-completions这类协议标识baseUrl结尾带不带/v1会直接影响请求能不能通。下面第二节先把 TaoToken 的接入准备好第三节再给完整可复制的配置片段。2. 用 TaoToken 统一 Key 与 API 通道接入前的准备在配 Π agent 之前先解决「Key 从哪来、请求打到哪」的问题。如果你每个模型都单独去申请 Key、记不同的 baseUrl配置会越堆越乱换模型时还要改一堆字段。TaoToken 的作用就是把这些统一起来一个 Key、一个 API 通道兼容 OpenAI 风格的 completions 协议Π agent 的models.json里只要填一次 baseUrl 和 apiKey后面加模型只改models数组就行。你需要准备的东西不多一个 TaoToken 账号、一个 API Key、以及确认要用的模型 ID。API Key 在控制台的 API Keys 页面创建创建后复制保存因为它只完整显示一次。模型 ID 则取决于你在 TaoToken 里开通了哪些模型填进配置时用模型的实际 ID不要自己编。这里有个关键点Π agent 的模型配置走的是 OpenAI 兼容协议所以api字段统一写openai-completionsbaseUrl指向 TaoToken 的 API 地址。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 baseUrl 使用。如果你在别处看到带/v1的写法要确认它和 Π agent 的拼接逻辑是否匹配——Π agent 会在 baseUrl 后面拼/chat/completions之类的路径所以 baseUrl 本身不要重复带/v1否则会变成/v1/v1/...导致 404。创建 Key 的入口在控制台模型对话可以用来先验证 Key 是否可用接入文档里有完整的协议说明。建议的顺序是先在模型对话里发一条测试消息确认 Key 有效、模型能返回再把它填进 Π agent 的配置。这样如果后面 Π agent 报 401你就能确定问题出在配置格式而不是 Key 本身。注意API Key 属于敏感凭证不要提交到 Git 仓库也不要在截图里暴露。models.json如果放在项目里被版本控制记得加进.gitignore。准备好 Key 和模型 ID 后就可以进入第三节的配置环节了。TaoToken 的 Coding Plan 适合长期编码和 Agent 场景如果你打算把 Π agent 当日常工具用可以了解下它的额度策略只是临时验证的话按量用 API 也够。3. 可复制配置models.json 与 settings.json 完整片段这一节是全文的核心给你能直接复制粘贴的配置。先确认路径模型配置在~/.pi/agent/models.json推理强度等设置在~/.pi/agent/settings.json。两个文件如果不存在就新建JSON 格式对缩进不敏感但括号和逗号必须配对。先看models.json。下面这份配置用 TaoToken 作为 providerbaseUrl 指向https://taotoken.net/apiapiKey 换成你自己的models 数组里放你要用的模型。模型 ID 和 name 按实际填写input表示支持文本和图片输入contextWindow和maxTokens按模型能力填不确定就先填保守值。{ providers: { TaoToken: { name: TaoToken Unified, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, api: openai-completions, models: [ { id: claude-sonnet-4-20250514, name: Claude Sonnet 4, input: [text, image], contextWindow: 200000, maxTokens: 64000 }, { id: gpt-4.1, name: GPT-4.1, input: [text, image], contextWindow: 1000000, maxTokens: 128000 } ] } } }这份配置里providers下可以有多个 provider比如你同时用 TaoToken 和别的通道就再加一个键。每个 provider 的api字段决定协议TaoToken 走 OpenAI 兼容所以写openai-completions。models数组里每个对象的id是请求时真正发给服务端的模型标识name是你在/model列表里看到的名字两者可以不同但id必须和服务端一致。配完模型再处理推理强度。GPT 类模型支持 reasoning level可选值通常是low、medium、high、xhigh。Π agent 的交互界面里改不了这个得手动编辑~/.pi/agent/settings.json找到defaultThinkingLevel属性改值。下面是一个最小示例{ defaultThinkingLevel: medium }如果你之前没建过这个文件直接写入上面内容即可。改完保存重启 Π agent 生效。这里踩过的坑是settings.json 里如果已有其他字段不要整个覆盖只加或改defaultThinkingLevel这一项否则可能丢掉别的设置。配置 Provider 还有另一种方式就是在 Π agent 里执行/login它会让你选 subscription 或 API Key。选 API Key 本质就是走上面models.json的配置选 subscription 会弹登录页面适合有对应订阅的场景。两种方式不冲突但建议统一用models.json管理便于版本化和迁移。提示改完models.json后用/model命令看列表里有没有你配的模型。如果没出现多半是 JSON 语法错误或路径不对先用python -m json.tool ~/.pi/agent/models.json校验格式。4. 验证请求从 /model 到一次真实对话配置写完不代表能用得验证。第一步启动 Π agent输入/model看列表里是否出现你在models.json里配的模型名。如果出现了说明配置被正确读取如果没出现回到第三节检查 JSON 格式和文件路径。第二步选一个模型发一条最简单的消息比如「用一句话说明这个仓库是做什么的」。这一步会触发真实 API 请求。如果返回正常说明 baseUrl、apiKey、模型 ID 三者都对上了。如果报错先看错误类型401 通常是 Key 问题404 多半是 baseUrl 拼接问题reading choices之类的解析错误则可能是协议不匹配。第三步验证 SKILL 是否加载。SKILL 的搜索路径分全局和项目级全局是~/.pi/agent/skills/和~/.agents/skills/项目级是项目根目录下的.pi/skills/和.agents/skills/。你可以先装一个官方示例 SKILL比如pi install npm:tomxprime/planning-with-files装完重启看它是否出现在可用列表里。如果想临时不加载任何 SKILL 启动用pi --no-skills这在排查「是不是某个 SKILL 导致异常」时很有用。第四步验证 Extensions。以 subagents 扩展为例安装命令是pi install npm:pi-subagents装完重启。Extensions 和 SKILL 的区别在于Extensions 通常提供新的命令或能力比如异步子 Agent 委托SKILL 更偏向给 Agent 注入领域知识或工作流。两者都装完后你可以跑一个需要多步的任务观察 Agent 是否会调用子 Agent 或按 SKILL 定义的流程走。第五步验证 Session 管理。Π agent 用/resume恢复历史会话用Ctrl d选择删除历史会话再按 Enter 确认。你可以先开一个会话做点操作退出再用/resume看能不能找回。这一步验证的是会话持久化是否正常如果/resume列表为空检查~/.pi/agent/目录的写权限。整个验证流程走下来你应该能确认四件事模型能调通、SKILL 能加载、Extensions 能生效、Session 能恢复。这四件事都过了最小可用流程就算跑通了。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth这一节按真实报错来对照帮你快速定位。第一个高频错误是 401 Unauthorized。原因通常是 apiKey 填错、Key 被撤销、或者 baseUrl 指向了错误的通道。排查顺序先用模型对话验证同一个 Key 是否可用可用则问题在 Π agent 配置不可用则去控制台重新生成 Key。注意models.json里 apiKey 不要带多余空格或引号嵌套错误。第二个是local proxy failed或连接被拒绝。这通常意味着 baseUrl 写错或者本机网络无法访问该地址。检查 baseUrl 是否是https://taotoken.net/api结尾不要多加/v1。如果地址正确仍失败确认本机能否正常访问该域名排除本地网络策略问题。第三个是reading choices或类似解析错误。这类错误说明请求发出去了但返回结构不符合预期。常见原因是api字段写错比如把openai-completions写成了别的协议标识导致 Π agent 按错误格式解析响应。回到models.json确认api字段拼写。第四个是 OAuth 相关错误多出现在用 subscription 方式登录时。如果你走的是/login的 subscription 分支弹出登录页面后授权失败先确认账号状态正常。如果之前配过 GitHub Copilot 且遇到模型丢失可以检查~/.pi/agent/auth.json删掉availableModelIds及其内容重启后再看模型列表是否恢复。这个操作相当于清掉缓存的模型清单让它重新拉取。第五个是模型列表里缺少某些模型。除了上面的 auth.json 缓存问题还要确认models.json里models数组是否真的包含了那个模型以及id是否和服务端一致。有时候你配了name但id写错列表里会显示但调用时报模型不存在。排查时有个通用技巧把models.json和settings.json都用 JSON 校验工具过一遍语法错误是最容易被忽略的原因。另外每次改完配置记得重启 Π agent它不会热加载配置文件。注意如果报错信息里出现代理相关字样先检查本机环境变量里有没有遗留的代理设置这类设置可能干扰正常请求。清理掉不需要的代理变量再试。6. 把流程固化下来Session 管理与长期使用建议跑通最小流程后下一步是让它稳定服务于日常开发。Session 管理是长期使用的关键。/resume让你回到之前的会话继续Ctrl d删除不再需要的会话。建议按任务拆分会话比如一个会话专注一个功能模块做完就归档或删除避免单个会话过长导致上下文膨胀、响应变慢。SKILL 和 Extensions 的管理也建议有节制。全局 SKILL 放在~/.pi/agent/skills/所有项目共享项目专属的放.pi/skills/跟着仓库走。装 Extensions 前想清楚是否真的需要装多了会拖慢启动、增加排查难度。用pi --no-skills可以快速判断问题是否由 SKILL 引起。模型配置方面如果你用 TaoToken 统一通道加新模型只需在models.json的models数组里追加一项不用改 baseUrl 和 apiKey。推理强度按任务调日常改代码用medium复杂重构或需要深度推理时切high简单问答用low省额度。这些都在settings.json的defaultThinkingLevel里改。最后给一个实用习惯把models.json和settings.json备份一份换机器或重装时直接复制回去省去重新配置的时间。配置里的 apiKey 用环境变量或单独的密钥管理方式注入更安全但 Π agent 当前直接读文件所以至少确保这些文件不被提交到公开仓库。整套流程走下来你会发现 Π agent 的基础使用并不复杂难点在于配置细节和报错定位。把第三节的配置片段复制好、第四节验证步骤走一遍、第五节报错对照表存下来后面遇到问题基本能自己解决。需要创建 Key 或查看接入细节时去控制台和接入文档想先验证模型是否可用用模型对话发一条消息最快如果打算长期用它做编码和 Agent 任务Coding Plan 的额度方式更适合持续使用。