先让 Pi 能启动，再检查模型配置
Pi Coding Agent 接入 AIGoCode 时，安装完成、模型能回复、工具能读取项目文件，是三个需要分开验证的结果。只看到 pi 的版本号，还不能说明模型已经连通；只收到一句问候语，也没有替你验证项目文件读取。
本文按“环境、models.json、选择模型、读取文件”完成一次最小接入检查。字段依据本轮官方 Pi 接入教程，不把 OpenCode 的 opencode.json 或 OpenClaw 的默认模型配置搬过来。
环境先核对 Node.js 与 Windows 的 Git
官方要求 Pi 使用 Node.js 22.19 或更高版本。Windows 用户还需要安装 Git for Windows，使用默认安装路径，并在安装后重新打开终端。
教程给出的安装命令是 npm install -g --ignore-scripts @earendil-works/pi-coding-agent，安装后运行 pi --version，能看到版本号再继续配置。官方说明它已在 Windows 的 Pi 0.86.1 验证；这是文档的验证范围，不是本文在你的环境中测过的结果。
如果命令还无法启动，先处理安装环境；不要在这个阶段反复替换 AIGoCode Key。本文没有代你执行安装，也不推断所有系统与版本都会得到相同结果。
找到 models.json，别多出一个 .txt 后缀
Windows 的配置文件在 %USERPROFILE%.pi\agent\models.json，macOS/Linux 则为 ~/.pi/agent/models.json。文件或目录不存在时先创建，教程特别提醒不要保存成 models.json.txt。
如果已有其他供应商，不要用一份最小示例直接覆盖整个文件。官方要求把新供应商添加到现有 providers 中、保留原有内容。修改前建议留副本；保存后确认路径和文件名，而不仅看编辑器标签上显示的名称。
按协议把分组、api 和 baseUrl 配成一组
在 API Key 页面按教程选择支持第三方调用的分组，再替换配置里的 sk-your-api-key 占位符。三种配置的对应关系如下：
| 接入方式 | Key 分组 | Provider 示例标识 | api | baseUrl |
|---|---|---|---|---|
| OpenAI | Codex（可外接） | aigocode-openai | openai-responses | https://api.aigocode.dev/v1 |
| Claude | Claude Code（可外接） | aigocode-claude | anthropic-messages | https://api.aigocode.dev |
| Gemini | Gemini | aigocode-gemini | google-generative-ai | https://api.aigocode.dev/v1beta |
三份示例在各自的 models 数组中登记一个模型 ID：分别是 gpt-6-astra、claude-sonnet-5-5、gemini-3.8-flash。它们是教程演示，不是全部可用模型清单。配置其他模型前，仍要核对当前模型名称列表。
复制配置时，从所选协议的完整示例开始核对。不要保留 Claude 的 api 字段，却只把模型 ID 改成 Gemini；也不要把另一个工具对“根地址”的要求当成所有 Pi Provider 都通用的规则。相关概念可继续参考本站模型名与协议示例，但具体配置以 Pi 这一页为准。
在项目目录启动，并用 /model 确认当前选择
保存 models.json 后，在准备使用的项目文件夹打开终端，运行 pi。先发送一句“你好”，正常回复表示教程中的基本模型接入验证通过。需要切换模型时，输入 /model，选择目标模型后继续发送消息。
这一步应记下实际选择的 Provider 与模型，而不是根据配置文件里存在某个条目，就推断会话一定选中了它。本文没有替你请求模型，也不承诺固定回复或所有模型都可用。
再做一次受控的项目文件读取
官方还建议让 Pi 读取项目中的一个文件，并简要说明内容，以确认工具调用正常。为了让这一步容易核对，可以自行准备一个不含密钥和业务隐私的短说明文件，请它概述其中内容，再与原文对照。
这里的文件选择是操作建议；不要为了验证工具调用，直接要求它遍历整台电脑或读取凭据文件。验证结果也只说明本次文件读取任务完成，不能扩大为 Pi 已经理解整个仓库或所有工具都可正常运行。
因此可以分别记录两项验收：一句消息是否收到回复，以及指定文件是否被正确读取并概述。若后者失败，先保留工具执行的具体错误，不要把两项都混成“模型没有连上”。
按失败阶段继续排查
官方列出的常见问题包括 Windows 找不到 Bash，或执行命令时误启动 WSL；遇到这些现象，先回到运行环境检查。返回 401、403、429 时查看错误码；模型不可用则检查 Key 所属分组、请求地址和模型名称列表；连接失败时检查网络或代理设置。
认证与额度问题可以衔接本站401 与 403 分开排查。日志只保留版本、配置路径、协议和脱敏错误，不贴出 apiKey 的值。
完成后，你应能明确回答：Pi 是否能启动，models.json 是否保存到正确路径，当前会话选了哪个模型，指定文件读取是否成功。按这四个结果定位问题，比重复覆盖配置文件更有依据。