CNB CodeBuddy 自定义模型踩坑：ACC 环境变量的隐形陷阱

背景

CNB（Cloud Native Build）是腾讯云的云原生构建平台，内置了 CodeBuddy——一个集成在云原生开发环境中的 AI 编程助手。每个用户有免费的 token credits 额度，额度用完后 CodeBuddy 就无法使用了。

一个自然的想法是：能不能换成自己的模型 API？ 答案是能，但过程比想象中曲折。

这个问题在 cnb/feedback#4040 中有详细讨论，本文整理其中的关键发现和最终可行方案。

问题现象

在 credit 耗尽之前，通过在云原生开发环境中创建 ~/.codebuddy/models.json，可以成功配置自定义模型（如 Mimo-V2.5-Pro）：

mkdir -p ~/.codebuddy
cat > ~/.codebuddy/models.json << 'EOF'
{
  "models": [
    {
      "id": "mimo-v2.5-pro",
      "name": "Mimo-V2.5-Pro",
      "vendor": "user",
      "url": "https://your-api-endpoint/v1",
      "apiKey": "your-api-key",
      "maxOutputTokens": 32000,
      "maxInputTokens": 128000,
      "maxAllowedSize": 128000,
      "supportsToolCall": true,
      "supportsImages": false,
      "supportsReasoning": true,
      "temperature": 1
    }
  ]
}
EOF

但 credit 用完之后，再次打开 CodeBuddy 对话框，会弹出：

Session expired. You have been automatically logged out.

无论怎么改 models.json，CodeBuddy 插件版都坚持要求重新登录，自定义模型完全不生效。

根因分析：ACC 环境变量

问题的根源在于 CNB 云原生开发环境预设了一组 ACC_ 开头的环境变量，其中 ACC_PRODUCT_CONFIG_V2 优先级最高，它包含了 CodeBuddy 的默认产品配置。

这些变量会强制覆盖你通过 ~/.codebuddy/models.json 或环境变量设置的自定义模型配置。这就是为什么：

Credit 充足时：默认配置正常工作，models.json 作为补充可以生效
Credit 耗尽后：默认配置指向已无额度的账户，ACC_ 变量的优先级压制了你的自定义配置

可以通过以下命令确认：

env | grep ^ACC

方案对比

方案一：CLI 版 unset ACC 变量（可行）

对于 CodeBuddy CLI 版本，可以直接 unset 掉这些环境变量：

# 查看有哪些 ACC 开头的变量
env | grep ^ACC

# unset 关键变量
unset ACC_PRODUCT_CONFIG_V2

然后配置 ~/.codebuddy/models.json 即可正常使用自定义模型。

局限：仅对 CLI 版本有效。VS Code 插件版无法通过这种方式清除环境变量（已知限制）。

方案二：ACC_PRODUCT_CONFIG_V3 覆盖（不完善）

讨论中有人尝试在 .cnb.yml 中设置 ACC_PRODUCT_CONFIG_V3（V3 优先级高于 V2），将自定义模型配置写入其中。模型列表能正常显示，但聊天时报 not found 10006 错误——说明模型配置被识别了，但实际的 API 调用链路仍有问题。

方案三：models.json 加标记字段（插件版可行）

最终发现的可行方案是在 models.json 中添加 configured 和 tag 字段：

mkdir -p ~/.codebuddy && echo '{
  "models": [
    {
      "id": "mimo-v2.5-pro",
      "name": "Mimo-V2.5-Pro",
      "vendor": "user",
      "url": "https://your-api-endpoint/v1",
      "apiKey": "your-api-key",
      "configured": true,
      "tag": ["custom"],
      "maxOutputTokens": 32000,
      "maxInputTokens": 128000,
      "maxAllowedSize": 128000,
      "supportsToolCall": true,
      "supportsImages": false,
      "supportsReasoning": true,
      "temperature": 1
    }
  ]
}' > ~/.codebuddy/models.json

相比之前的配置，关键多了两个字段：

"configured": true —— 标记该模型已完成配置
"tag": ["custom"] —— 标记为自定义模型

加上这两个字段后，CodeBuddy 插件版可以正常识别并使用自定义模型。

NPC 也能用自定义模型

除了云原生开发环境中的 CodeBuddy，CNB 的 NPC（AI 助手） 也可以配置使用自定义模型。NPC 运行在 Docker 容器中，底层是 CodeBuddy Code Agent。

配置方式是注入三个环境变量：

环境变量	说明
`CODEBUDDY_BASE_URL`	模型 API 端点（兼容 OpenAI 协议）
`CODEBUDDY_API_KEY`	API Key
`CODEBUDDY_MODEL`	模型名称

三个变量必须同时配置，任一缺失都会回退到默认模型。

推荐：通过 .cnb.yml 注入密钥

在 NPC 所属仓库的 .cnb.yml 中，通过流水线 env 注入：

$:
  issue.comment@npc:
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      env:
        CODEBUDDY_BASE_URL: ${CODEBUDDY_BASE_URL}
        CODEBUDDY_API_KEY: ${CODEBUDDY_API_KEY}
        CODEBUDDY_MODEL: ${CODEBUDDY_MODEL}
      stages:
        - name: npc go
          type: npc:go

实际的密钥值通过密钥仓库文件管理，避免明文写在代码中。

实践建议

优先用 CLI 版：如果只需要在终端中使用自定义模型，CLI 版是最简单可靠的路径——unset ACC_PRODUCT_CONFIG_V2 + 配置 models.json 即可
插件版加标记字段：如果需要 VS Code 插件版，确保 models.json 中包含 "configured": true 和 "tag": ["custom"]
NPC 用环境变量注入：想让 NPC 也用自定义模型，通过 .cnb.yml 的 env 配置三个 CODEBUDDY_ 变量
密钥不要硬编码：使用 CNB 的密钥仓库功能管理 API Key，不要写死在代码或配置文件中

背景