Pi Coding Agent 接入

本指南帮助你在 Pi Coding Agent 中配置 MoaCode 作为 AI 模型供应商，通过统一网关调用所需的大模型，享受自动故障切换与统一计费。

前提条件

• 已安装并正常使用 Pi Coding Agent
• 已注册 MoaCode 账号，并获取有效 API Key（cr_ 开头）
• 明确计划使用的模型 ID（如 gpt-5.5、gpt-5.4-mini），完整列表见模型目录与价格或站内 Model catalog

配置步骤

1. 创建或编辑配置文件

Pi Coding Agent 的自定义供应商配置存储在 ~/.pi/agent/models.json。若目录或文件不存在，手动创建：

mkdir -p ~/.pi/agent
touch ~/.pi/agent/models.json

2. 编写供应商配置

用文本编辑器打开 ~/.pi/agent/models.json，添加：

{
  "providers": {
    "moacode": {
      "name": "Moacode",
      "baseUrl": "https://moacode.org/v1",
      "api": "openai-responses",
      "apiKey": "$MOACODE_API_KEY",
      "models": [
        {
          "id": "gpt-5.5",
          "name": "GPT-5.5"
        },
        {
          "id": "gpt-5.4-mini",
          "name": "GPT-5.4 mini"
        }
      ]
    }
  }
}

两个必查项

• baseUrl 末尾必须带 /v1（openai-responses 协议对应 https://moacode.org/v1），这是常见漏填点
• models[].id 必须填 MoaCode 实际支持的模型标识符，以模型目录为准替换示例；注意最后一个模型对象后不要有多余逗号

配置字段说明：

字段	说明	示例
providers	顶层对象，包含所有自定义供应商	-
"moacode"	供应商唯一标识名（可自定义）	"moacode"
name	供应商显示名称（在 /model 中显示）	"Moacode"
baseUrl	API 基础 URL	"https://moacode.org/v1"
api	API 协议类型，MoaCode 兼容 OpenAI 格式	"openai-responses"
apiKey	API 密钥，推荐用环境变量引用	"$MOACODE_API_KEY"
models[].id	模型唯一标识符（由 MoaCode 定义）	"gpt-5.5"
models[].name	模型显示名称（可自定义）	"GPT-5.5"

3. 设置 API Key 环境变量（推荐）

在终端导出 API Key：

export MOACODE_API_KEY='你的密钥'

使用单引号

API Key 可能包含 $、!、& 等特殊字符，单引号会原样保留，避免 Shell 解析错误。

永久生效（写入 Shell 配置，bash 用 ~/.bashrc）：

echo "export MOACODE_API_KEY='你的密钥'" >> ~/.zshrc
source ~/.zshrc

也可以直接在 models.json 里把 apiKey 写成明文字符串，但会暴露密钥，仅建议测试时使用。

4. 验证配置

检查 JSON 格式：

cat ~/.pi/agent/models.json | python3 -m json.tool

如有报错按提示修正（常见问题：多余的逗号、缺少引号）。

重启 Pi Coding Agent：完全退出并重新启动，使配置生效。

切换模型：在聊天框输入 /model，从下拉列表选择 moacode/ 开头的模型（如 moacode/gpt-5.5）。

发送测试消息：发一条简单消息（如 "Hello"），正常响应即配置成功。

故障排除

问题现象	可能原因	解决方案
/model 列表未出现 Moacode	配置文件路径错误或 JSON 格式有误	检查 ~/.pi/agent/models.json 是否存在、格式合法，重启 Pi
请求返回 401 / 403	API Key 无效或环境变量未加载	确认 echo $MOACODE_API_KEY 有输出、密钥有效；专用 Key 检查授权范围
请求返回 404	模型 ID 不支持或 baseUrl 漏了 /v1	对照模型目录更正模型 ID；核对 baseUrl
连接超时	baseUrl 错误或网络不通	核对 API 入口地址，检查网络 / 代理
响应异常	协议类型错误	确认 api 为 "openai-responses"

仍未解决可通过工单与 QQ 群联系我们。

相关页面

• 模型目录与价格
• OpenClaw 接入 / OpenCode 接入 — 同类配置方式
• 常见报错与排查