CodeBuddy API Key 配置教程：4 种方式与报错排查

CodeBuddy API Key 配置分三步：先按你的版本（国际版/中国版/iOA 版）拿到 Key，再从环境变量、CloudBase CLI、VS Code 插件、models.json 四种方式里选一种接好，最后跑一句生成做验证。跟着本文操作，10 分钟内能跑通。

前置准备：先分清你用的是哪个版本

CodeBuddy 是腾讯推出的 AI 编程助手，常见形态是 CodeBuddy Code（命令行）和 VS Code 插件。配置 Key 前先确认版本，因为三个版本的 Key 入口和环境变量写法不同：

国内个人用户默认选中国版；公司在用 iOA 环境的选 iOA 版。选错版本的表现通常是"网络连接失败"或"Key 无效"，下文排查表能对号入座。

第一步：拿到对应平台的 API Key

不同版本入口不同，务必选对：

1. 国际版：登录 CodeBuddy 国际版开放平台，在 API Key 管理里创建并复制，Key 通常以 sk- 开头
2. 中国版：在中国版平台完成实名认证后创建 Key
3. iOA 版：用企业内网账号登录获取，仅内网可用

如果要接 OpenAI、Gemini、Groq 这类第三方模型，Key 要去对应平台申请：OpenAI 在 platform.openai.com/api-keys，Gemini 在 aistudio.google.com/app/apikey，Groq 在 console.groq.com/keys。

复制 Key 时注意别带前后空格，这是最常见的"配置了但没生效"原因。

第二步：四种配置方式任选其一

方式一：环境变量（推荐，CLI 场景最稳）

终端里执行：

export CODEBUDDY_API_KEY="sk-你的key"

中国版和 iOA 版必须同时设置 CODEBUDDY_INTERNET_ENVIRONMENT：

# 中国版
export CODEBUDDY_INTERNET_ENVIRONMENT=internal
# iOA 版
export CODEBUDDY_INTERNET_ENVIRONMENT=ioa

国际版不需要这个变量（或显式设为 public）。建议把这两行写进 ~/.zshrc（macOS）或 ~/.bashrc（Linux/WSL），再执行 source ~/.zshrc 生效，免得每次开终端重输。

方式二：CloudBase AI CLI 配置向导

装了腾讯云 CloudBase AI CLI 的话，直接跑配置向导：

tcb ai --setup

依次选择 CodeBuddy Code、配置方式（CodeBuddy 账号登录或 API Key），按提示登录或填入 Key，最后可选默认助手。之后用 tcb ai -a codebuddy 启动。CLI 会自动做三项验证：API Key 格式验证、网络连通性测试、MCP 服务器配置检查。

方式三：VS Code 插件里填第三方模型 Key

用插件调 GPT、Gemini、Groq 走的是插件自己的设置，与终端环境变量独立：

1. 打开 VS Code，扩展市场搜 CodeBuddy 并安装
2. 点左侧 CodeBuddy 图标，点右上角齿轮进入 Extension Settings
3. 展开 CodeBuddy: Model Providers，分别填 OpenAI Key（sk- 开头）、Gemini Key（AIzaSy 开头）、Groq Key（gsk_ 开头）
4. 点磁盘图标保存，从顶部 Model 下拉框选对应模型

方式四：CLI 的 models.json（自定义模型列表）

命令行启动的 CodeBuddy Code 支持手动编辑模型列表。配置文件路径：

• macOS / Linux：~/.codebuddy/models.json
• Windows：C:\Users\你的用户名.codebuddy\models.json

把 换成你的 Key，写入：

{"models": [{"id": "tc-code-latest", "name": "Auto", "vendor": "Tencent Cloud", "apiKey": "<USER_API_KEY>", "url": "https://api.lkeap.cloud.tencent.com/coding/v3"}]}

保存后运行 codebuddy 启动，首次会提示选登录方式，国内用户选 Log in via Chinese Site。

验证是否配置成功

配置完做一次最小验证：在 CLI 或插件里输入"写一个冒泡排序"，能正常返回代码就说明 Key 已生效。CLI 下想看详细日志排查，加 verbose 参数：

tcb ai -a codebuddy -- --verbose

验证成功的标志有三个：CLI 返回完整可运行的代码、插件界面显示已连接对应模型、日志里没有 authentication 或 401 报错。跑通一次之后，后续使用就不用再碰配置。

进阶：MCP 服务器透传

CodeBuddy Code 支持通过参数透传管理 MCP 服务器：

tcb ai -a codebuddy -- --mcp-server "你的-mcp-配置"

MCP 配置错误的典型表现是启动时验证失败，检查三项：配置格式是否正确、服务器地址是否可达、认证信息是否齐全。

国内用户网络注意

1. 中国版与 iOA 版走腾讯云国内节点，直连即可，不需要额外网络配置
2. 国际版和第三方模型（OpenAI/Gemini/Groq）的端点都在海外，国内直连会超时，需要合规的网络环境
3. 排查顺序固定为：先确认版本与环境变量，再查网络连通，最后看 Key 权限与账户状态

CodeBuddy Code 的完整接入说明见腾讯云 TokenHub 官方文档，配置细节以官方文档为准。

配置多个模型怎么切换

想同时用腾讯云模型和第三方模型，不用反复改环境变量：

1. models.json 里加多个条目，每条 id 唯一
2. CloudBase 配置向导最后一步可以选默认要使用的 AI 编程助手
3. 插件场景从顶部 Model 下拉框随时切换模型
4. 环境变量方式一次只生效一个 Key，多模型场景优先用 models.json

常见报错速查表

配置 CodeBuddy 如果遇到用量超限，可参考站内的 CodeBuddy 429 报错排查；想系统了解功能与用法，看 CodeBuddy 使用教程；刚接触这个产品，先读 CodeBuddy 是什么。