Pi Coding Agent 接入开桥 ​

Pi Coding Agent 支持两种开桥接入方式：

安装 Pi Coding Agent ​

Pi 目前使用官方包 @earendil-works/pi-coding-agent，需要 Node.js 22.19.0 或更高版本：

npm install -g @earendil-works/pi-coding-agent

验证安装结果：

pi --version

npm uninstall -g @mariozechner/pi-coding-agent
npm install -g @earendil-works/pi-coding-agent

配置普通 API Key ​

这种方式直接使用 Pi 自带的自定义 Provider 能力，不需要安装开桥 OAuth 扩展。

首先设置开桥 API Key：

export OPENQIAO_API_KEY="sk-ai-v1-xxx"

然后在 ~/.pi/agent/models.json 中添加 openqiao Provider：

{
  "providers": {
    "openqiao": {
      "baseUrl": "https://openqiao.com/api/v1",
      "api": "openai-completions",
      "apiKey": "$OPENQIAO_API_KEY",
      "models": [
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash"
        }
      ]
    }
  }
}

如果 models.json 已经包含其他 Provider，请把 openqiao 合并到现有的 providers 对象中，不要覆盖整个文件。需要使用其他开桥模型时，在 models 数组中继续添加对应的模型 ID。

启动 Pi，运行 /model，选择 openqiao/deepseek-v4-flash。也可以在启动时直接选择：

pi --provider openqiao --model deepseek-v4-flash

这里的 apiKey 保存的是环境变量引用，不会把 API Key 本身写入 models.json。如果需要长期使用，请根据当前 Shell，把 export 命令加入 ~/.zshrc 或 ~/.bashrc，然后重新打开终端。

使用 OAuth PKCE ​

官方扩展 @openqiao/pi-openqiao-oauth 会在浏览器中打开开桥授权页面，不需要创建或复制开桥 API Key，并会自动刷新 OAuth Token。

使用 Pi 安装扩展：

pi install npm:@openqiao/pi-openqiao-oauth

启动 Pi 后登录：

/login openqiao

在浏览器中确认授权。回调页面显示连接成功后返回 Pi，运行 /model 并选择开桥模型。

该扩展会：

• 动态获取开桥模型目录，并将最后一次有效目录缓存到 ~/.pi/agent/models-store.json。
• 根据开桥为每个模型声明的协议，选择 Anthropic Messages、OpenAI Responses 或 Chat Completions。
• 在 Pi 的 Provider 凭据存储中保存 Access Token 与 Refresh Token，并保存轮换后的 Refresh Token。
• 仅申请 inference:invoke 和 offline_access 权限。

如需退出登录，在 Pi 中运行 /logout 并选择开桥。也可以在开桥的已授权应用中撤销授权。

授权流程和凭据安全的详细说明请参阅 OAuth PKCE 接入指南。

如何选择 ​

常见问题 ​

找不到开桥模型 ​

使用普通 API Key 时，请确认：

• ~/.pi/agent/models.json 是合法的 JSON。
• Provider 包含 baseUrl、api 和至少一个模型 ID。
• 启动 Pi 的同一个终端中存在 OPENQIAO_API_KEY。

可以直接检查 Pi 已加载的模型：

pi --list-models openqiao

使用 OAuth 时，请确认扩展已经安装：

pi list

必要时更新扩展并重新登录：

pi update npm:@openqiao/pi-openqiao-oauth

浏览器已经打开，但授权无法完成 ​

OAuth 回调使用 127.0.0.1 上的临时端口，浏览器和 Pi 必须访问同一台机器的回环地址。远程服务器、容器、SSH 会话或浏览器代理环境可能需要端口转发，或者改为在本机运行 Pi。

请求返回 401 ​

• 普通 API Key：确认 OPENQIAO_API_KEY 仍然有效，并且在启动 Pi 前已经导出。
• OAuth：重新运行 /login openqiao。如果仍然失败，请先在开桥已授权应用中撤销旧授权，再重新登录。

不要把 API Key 或 OAuth Token 粘贴到提示词、项目文件、日志或截图中。