
从 OpenCode 换到 Pi,先迁移配置关系
已经在 OpenCode 接通 AIGoCode,准备换用 Pi 时,不要把 opencode.json 改个文件名就交给新工具。两份官方教程使用不同配置层级、字段名与协议选择方式;甚至 Claude 示例的地址后缀也不同。
本文帮助你为同一项项目任务重新建立 Pi 配置,并保留原工具作为对照。迁移对象限于模型连接配置;不把它描述成聊天历史、工具权限、工作区设置都会自动转移的方案。
第一步:记录旧配置,另建新工具的文件
按官方教程,OpenCode 的全局文件在 Windows 的 %USERPROFILE%\.config\opencode\opencode.json,macOS/Linux 的 ~/.config/opencode/opencode.json。Pi 则读取 Windows 的 %USERPROFILE%\.pi\agent\models.json 或 macOS/Linux 的 ~/.pi/agent/models.json。
建议先在本机受控位置保留旧文件副本,再记录不含密钥值的三项信息:所用协议、当前模型 ID、Key 分组。新文件放到 Pi 的路径;如果已有其他供应商,按 Pi 官方说明把新项合入现有 providers,保留原内容,确认没有额外的 .txt 后缀。
原文件副本也可能包含密钥,不能作为普通排错附件公开。这里的保留副本是维护建议,不代表客户端会提供跨工具的一键回滚。
第二步:逐个翻译结构,不原样复制字段
两页示例中,同样的“配置一个供应商”采用下列不同写法:
| 配置关系 | OpenCode 示例 | Pi 示例 |
|---|---|---|
| 供应商容器 | provider | providers |
| 协议选择 | npm 适配器,例如 @ai-sdk/anthropic | api,例如 anthropic-messages |
| 地址字段 | options.baseURL | 供应商下的 baseUrl |
| 密钥字段 | options.apiKey | 供应商下的 apiKey |
| 模型登记 | models 对象中的模型键 | models 数组中对象的 id |
| 示例模型选择 | 顶层 model 含供应商标识与模型 ID | 登记后在 Pi 中用 /model 选择 |
特别留意 baseURL 与 baseUrl 的大小写和所在层级。把字段改成相似名称并不会自动把其余结构转换好。建议以 Pi 官方完整示例为骨架,按项填入经过核对的信息,而不是在旧文件上连续替换字符串。
这张表说明本次官方示例的对应关系,不声称列出了两个工具的全部配置能力。
第三步:按协议核对地址、适配器和分组
| 协议方向 | OpenCode 教程示例 | Pi 教程示例 |
|---|---|---|
| OpenAI | @ai-sdk/openai;https://api.aigocode.dev/v1;ChatGPT API(Azure)分组 | openai-responses;https://api.aigocode.dev/v1;Codex(可外接)分组 |
| Claude | @ai-sdk/anthropic;https://api.aigocode.dev/v1;Claude API(AWS)分组 | anthropic-messages;https://api.aigocode.dev;Claude Code(可外接)分组 |
| Gemini | @ai-sdk/google;https://api.aigocode.dev/v1beta;Gemini 分组 | google-generative-ai;https://api.aigocode.dev/v1beta;Gemini 分组 |
Claude 这一行最容易因旧配置能用而被忽略:在 Pi 中应核对 Pi 示例的根地址,不能因为 OpenCode 示例带 /v1 就原封不动搬过去。OpenAI 行的地址虽然一致,协议字段仍需改成 Pi 的写法。
两篇教程中 OpenAI 和 Claude 的示例分组名称也不同。不能据此保证原 Key 可复用,也不需要仅凭名称不同就先删除旧 Key。去当前分组说明中核对适用工具、接入协议、外接调用及目标模型,再按 Pi 教程选择匹配的 Key;尚未确认的条件先记为待核实。
获取 API Key 明确说明分组决定模型、工具、协议和价格。备注名称不改变调用能力,多把 Key 共用账户额度,所以为迁移新建 Key 也不会获得额外额度。
第四步:模型 ID 只迁移原始值,选择动作重新做
OpenCode 示例顶层使用 aigocode/gpt-6-astra 一类“供应商标识/模型 ID”组合;Pi 的 OpenAI 示例在 models 数组中登记的是 id 为 gpt-6-astra 的对象。不要把组合字符串整个当成 Pi 示例中的模型 ID。
官方两页还分别展示 claude-sonnet-5-5 与 gemini-3.8-flash。它们只是示例;若要继续用自己原先的模型,应核对当前分组目录,而不是认定写入后一定有权限调用。
Pi 保存配置后在项目文件夹运行 pi,用 /model 选择目标模型。OpenCode 已经选好的默认模型,不能代替这次 Pi 会话里的实际选择。
第五步:保留旧工具结果,分两项验收新工具
Pi 文档要求 Node.js 22.19 或更高版本,Windows 还需要 Git for Windows。先确认 pi --version 能显示版本,再进入连接验证。命令无法启动时,应先处理环境,而不是反复更换 Key。
建议准备一个不含业务秘密的短说明文件,并记录下面两项新结果:
- 在 Pi 选择模型后发送一句简单消息,是否收到正常回复。
- 请 Pi 读取指定文件并简要说明,是否与原文相符。
官方 Pi 教程同时提供消息验证与项目文件读取建议。二者分别回答“模型能否回复”与“本次工具读取能否完成”;不能因为旧 OpenCode 会话成功就跳过,也不把新的一次成功扩大成所有项目工具权限都已迁移。
如果失败,记录 Pi 版本、所选协议与模型、配置路径及脱敏错误;原 OpenCode 结果只作旧环境对照。单工具的完整步骤可分别查阅 OpenCode 配置指南 和 Pi 接入指南。完成这份跨工具核对表后,再决定是否停止使用旧工具,避免在新连接尚未验证时先丢掉可用对照。