如何在 Pi Agent 中配置 DashScope 团队版 Token Plan

要在 Pi Agent 里接入阿里云百炼 DashScope 的 Token Plan，核心在于把 [https://coding.dashscope.aliyuncs.com/v1](https://coding.dashscope.aliyuncs.com/v1) 当作 OpenAI 兼容服务注册进 Pi 的配置文件。

终端交互界面（/login）默认只展示原生预设的服务商，找不着输入 Custom Endpoint 的选项。解决办法是直接在本地写一份 models.json 配置。把配置填对、模型 ID 映射清楚，重启 Pi 就能在 /model 菜单里直接调用。

下面是具体的配置全流程、踩坑细节以及排错方法。

问题定位：为什么在 /login 菜单里找不到自定义 Endpoint 设置？

Pi Agent 的 UI 交互逻辑决定了它不会在初始化菜单里放一个无穷无尽的配置表。如果你在 /login 交互列表中搜不到 Use an API key 或自定义 Provider 的入口，是因为 Pi 需要先读取到本地的第三方服务提供商定义，才会激活对应的 API 接入通道。

简而言之：先改配置文件，再启动客户端，最后切换模型。

这里还藏着一个网络层面的隐患。阿里云 Coding 节点（coding.dashscope.aliyuncs.com）部署在国内。许多开发者在终端常年挂着全局代理（如 Clash、V2Ray 等），请求发出去后会被代理接管，结果直接抛出 404、500 或者连接超时。在配置前，必须搞清楚配置的层级与网络环境。

手把手配置：从零手写 models.json

核心操作是编辑 Pi 的全局模型配置文件 ~/.pi/agent/models.json。

1. 创建或打开配置文件

在终端执行以下指令，确保配置目录存在：

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

如果你习惯用其他的编辑器（比如 VS Code），可以直接定位到该路径进行修改。

2. 写入 DashScope 兼容配置

把下面的 JSON 结构写入文件。注意将 YOUR_ACTUAL_API_KEY 替换为你自己在百炼控制台获取的密钥（通常以 sk-sp- 或 sk- 开头）。

{
  "providers": {
    "dashscope-coding": {
      "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-sp-YOUR_ACTUAL_API_KEY",
      "models": [
        {
          "id": "qwen3.5-plus"
        }
      ]
    }
  }
}

字段细节说明：

配置字段	类型	说明与注意事项
`baseUrl`	String	必须填 `[https://coding.dashscope.aliyuncs.com/v1](https://coding.dashscope.aliyuncs.com/v1)`，末尾带 `/v1`
`api`	String	声明协议类型，填 `openai-completions` 以兼容 OpenAI 格式
`apiKey`	String	明文 API Key，或指定环境变量（如 `"$DASHSCOPE_API_KEY"`）
`models`	Array	数组，填入你的 Token Plan 授权的模型 ID，如 `qwen3.5-plus` 或 `deepseek-v3`

3. 保护你的 Key：使用环境变量（推荐）

直接在 JSON 里硬编码 API Key 虽然方便，但在团队协作或配置同步时容易泄漏。更安全的做法是借用环境变量。

在你的Shell配置文件（~/.bashrc 或 ~/.zshrc）中写入：

export DASHSCOPE_API_KEY="sk-sp-YOUR_ACTUAL_API_KEY"

更新终端配置使之生效：

source ~/.zshrc

然后将 models.json 里的 apiKey 改为引用模式：

{
  "providers": {
    "dashscope-coding": {
      "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
      "api": "openai-completions",
      "apiKey": "$DASHSCOPE_API_KEY",
      "models": [
        {
          "id": "qwen3.5-plus"
        }
      ]
    }
  }
}

启动与验证：如何唤醒并切换至新模型

配置文件落盘后，按照以下步骤在 Pi 客户端中完成模型加载。

Step 1: 启动 Pi 客户端

在终端中直接运行命令启动：

pi

Step 2: 调出模型选择面板

在 Pi 的对话交互框中输入斜杠命令：

/model

Step 3: 选择 dashscope-coding 节点

此时列表里不再只有默认的服务商，你会看到我们手动注入的 dashscope-coding 以及下属的模型项 qwen3.5-plus。利用上下方向键选中后，敲回车确认。

疑难排查与常见踩坑

配完了却连不上？绝大多数问题都集中在 API Key 权限、网络环境和社区扩展包冲突上。

1. 请求超时或返回 404/500 错误

阿里云 Coding 节点位于国内服务器空间，对代理非常敏感。如果你开启了本地代理，终端流量可能被强行路由到境外，再折返回来访问 coding.dashscope.aliyuncs.com 时就会被拦截或超时。

解决方案：

暂时关闭终端代理工具。
或在终端环境变量中将阿里云域名设为直连：

export NO_PROXY="coding.dashscope.aliyuncs.com,$NO_PROXY"
export no_proxy="coding.dashscope.aliyuncs.com,$no_proxy"

2. 模型无法响应或提示无权限

确认你填写的模型 id（如 qwen3.5-plus、qwen-max 或 deepseek-v3）是否确实在你购买的 Token Plan / Coding Plan 包含的配额范围内。如果模型 ID 填错，百炼网关会直接拒绝处理请求。

3. 进阶玩法：使用社区扩展包（pi-alibaba-models）

如果你不想手写 models.json，Pi 生态提供了一个名为 pi-alibaba-models 的社区扩展。

安装该扩展包后，Pi 会自动为你植入阿里云国内与国际节点的协议模板。届时再执行 /login 指令，菜单里就能自动识别并引导你输入 API Key，免去手动对齐 JSON 字段的麻烦。

实用摘要 / 操作清单

为了方便快速复核，你可以按这个清单一步步对账：

[ ] 检查并确保终端未拦截 coding.dashscope.aliyuncs.com 域名的直连请求。
[ ] 创建配置目录：mkdir -p ~/.pi/agent。
[ ] 创建文件 ~/.pi/agent/models.json，确保包含 baseUrl、api: "openai-completions" 和正确的 models 数组。
[ ] 配置环境变量 DASHSCOPE_API_KEY 或在 JSON 中填入实际 Key。
[ ] 运行 pi，输入 /model 确认能成功选中目标模型。

一页速览

┌────────────────────────────────────────────────────────┐
│                   配置流程概览                          │
└────────────────────────────────────────────────────────┘
                           │
                           ▼
  1. 准备阶段 ──► 设置环境变量 DASHSCOPE_API_KEY
                           │
                           ▼
  2. 写入文件 ──► ~/.pi/agent/models.json
                  ├─ baseUrl: https://coding.dashscope.aliyuncs.com/v1
                  ├─ api: openai-completions
                  └─ models: [ { "id": "qwen3.5-plus" } ]
                           │
                           ▼
  3. 启动应用 ──► 终端输入 pi
                           │
                           ▼
  4. 切换模型 ──► 输入 /model 选择 dashscope-coding / qwen3.5-plus

常规疑问解答 (FAQ)

1. 为什么在 Pi 的初始 /login 界面找不到自定义 Endpoint 选项？

Pi 的图形/交互菜单默认只展示原生预设项。自定义 Provider 需要先写入 ~/.pi/agent/models.json 文件，系统读取后才会将选项加载进交互菜单。

2. `api` 字段为什么必须写 `openai-completions`？

阿里云百炼 DashScope 的 Coding 节点采用了 OpenAI 兼容协议。指定 openai-completions 能让 Pi 使用 OpenAI 的标准数据格式与其进行 HTTP 通信。

3. `baseUrl` 后面需不需要加斜杠 `/`？

填 [https://coding.dashscope.aliyuncs.com/v1](https://coding.dashscope.aliyuncs.com/v1) 即可，末尾不需要额外加斜杠。

4. 配置完成后提示网络连接超时，该怎么排查？

这通常是终端代理（如 Clash 或系统 Proxy）干扰了国内域名的解析。请关闭代理，或者将 coding.dashscope.aliyuncs.com 加进环境变量 NO_PROXY 列表中。

5. `models.json` 里的 `id` 可以随意填吗？

不能。id 必须与你在阿里云百炼控制台中开通并授权给当前 Token Plan 的实际模型名称完全一致（例如 qwen3.5-plus）。

6. 社区扩展包 `pi-alibaba-models` 是用来做什么的？

这是一个专门针对阿里云百炼节点开发的 Pi 扩展。安装后能省去手动编辑 models.json 的步骤，直接在 /login 交互界面里识别和配置 DashScope 的 API Key。

Pi Agent 配置 DashScope 团队版 Token Plan 终极教程：从零到接入（附踩坑指南）