RealRelay.ai
编码智能体

CodeBuddy Code 接入指南

把 RealRelay.ai 作为自定义模型接入腾讯的 CodeBuddy Code：安装、在 models.json 中以完整的 Chat Completions URL 添加模型、检查连接并切换模型。

创建 API 密钥浏览目录
协议
OpenAI Chat Completions
基础地址
https://www.realrelay.ai/v1
官方文档
www.codebuddy.ai
已对照工具官方文档核对
2026-10
实验性. 尚未在 RealRelay.ai 上端到端跑通。步骤依据该工具的官方文档；如果某一步失败，请带上错误信息联系支持。

概览

CodeBuddy Code 是腾讯推出的终端编码智能体。它会读取你的项目、编辑文件并运行命令。你在名为 models.json 的文件中把 RealRelay.ai 的模型添加为自定义模型。自定义模型使用 OpenAI Chat Completions 格式，所以请求会发往 /v1/chat/completions。

  • 一个从控制台的 API 密钥页面获取的 API 密钥。

  • 以 /v1/chat/completions 结尾的完整端点 URL。与大多数工具不同，CodeBuddy Code 不会替你补上路径。

  • 一个与 GET /v1/models 列出的完全一致的模型 ID，例如 z-ai/glm-5.2。请选择支持工具调用的模型。

本配置依据 CodeBuddy 的文档编写，但尚未在 RealRelay.ai 上端到端跑通。CodeBuddy Code 首次启动时会要求登录 CodeBuddy 账户，其文档没有说明不登录能否使用自定义模型。本页只涵盖终端智能体，不涉及 CodeBuddy IDE 插件或 WorkBuddy。

安装

可以用 npm 安装（需要 Node.js 18.20 或更高版本），也可以用腾讯的 Homebrew tap 安装（不需要 Node.js）。

npm (Node.js 18.20+)
npm install -g @tencent-ai/codebuddy-codecodebuddy --version
Homebrew (macOS · Linux)
brew install Tencent-CodeBuddy/tap/codebuddy-codecodebuddy --version

如果 codebuddy --version 输出了版本号，说明安装成功。如果提示找不到命令，请新开一个终端，让它加载更新后的 PATH。

首次运行 codebuddy 时会显示登录界面。中国境外的用户请选择 International Site（国际站）。

配置

  1. 1

    把密钥存进环境变量

    这样密钥就不会出现在配置文件里。完成后请新开一个终端。

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"
    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")
  2. 2

    把模型添加到 models.json

    如果文件不存在，就新建一个。Windows 上的路径是 %USERPROFILE%\.codebuddy\models.json。CodeBuddy Code 大约一秒内就会察觉改动，无需重启。

    ~/.codebuddy/models.json
    1{2  "models": [3    {4      "id": "z-ai/glm-5.2",5      "name": "z-ai/glm-5.2 (RealRelay.ai)",6      "vendor": "RealRelay.ai",7      "url": "https://www.realrelay.ai/v1/chat/completions",8      "apiKey": "${REALRELAY_API_KEY}",9      "maxInputTokens": 200000,10      "maxOutputTokens": 32000,11      "supportsToolCall": true,12      "supportsImages": false13    }14  ]15}

  • id 是发给 RealRelay.ai 的模型 ID。name 只是模型列表中显示的标签。

  • url 必须是完整路径。只写到 /v1 的 URL 在这里不起作用。

  • CodeBuddy Code 启动时，apiKey 会从 REALRELAY_API_KEY 读取密钥。如果该变量未设置，占位符会被原样发送，请求随之失败。

  • 本示例中的 maxInputTokens 和 maxOutputTokens 是安全的下限值。请替换为模型目录页上的限制。

  • supportsToolCall 必须为 true，智能体才能编辑文件、运行命令。只有支持图片的模型才把 supportsImages 设为 true。

  • 项目内的 .codebuddy/models.json 会覆盖主目录中的那一份。不要把密钥写进会提交的文件。

验证

  1. 1

    直接调用端点

    用你的密钥运行这条命令。如果返回的 JSON 包含 choices 数组，说明地址、密钥和模型都没问题。

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/chat/completions" \2  -H "Authorization: Bearer sk-***" \3  -H "content-type: application/json" \4  -d '{"model": "z-ai/glm-5.2", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'
  2. 2

    选定模型启动 CodeBuddy Code

    在项目中选定该模型启动它，然后列出它识别到的模型。

    CodeBuddy Code
    cd /path/to/your/projectcodebuddy --model z-ai/glm-5.2/model list
  3. 3

    检查列表并发送消息

    你的模型应出现在列表中，并带有 custom 标记。发一条简短消息；收到回复即说明整条链路畅通，该请求也会出现在控制台的用量日志中。

模型

每个要使用的 RealRelay.ai 模型都在 models 列表中加一个条目，各自设置限制。然后在会话中用 /model 加 ID 切换，或者用 codebuddy --model 启动。任务运行期间无法切换。

CodeBuddy Code
/model z-ai/glm-5.2

如果只想在列表中显示部分模型，可以添加一个 availableModels 数组，写上它们的 ID。设置之后，所有不在其中的模型都会被隐藏，包括内置模型。

CodeBuddy Code 还会用一个更轻量的模型处理后台任务，用一个推理模型处理较难的步骤。自定义模型如果没有为这两者单独设置，就会两者都用自己，所以一开始一个条目就够了。适合编码智能体的模型列在选择模型中。

故障排查

  • /model list 中没有该模型。JSON 不合法、文件没有保存在 ~/.codebuddy/ 中，或者 availableModels 数组里漏了这个 ID。项目级的 availableModels 会完全取代主目录中的那一份。

  • 401。启动 CodeBuddy Code 的终端里没有设置 REALRELAY_API_KEY。新开一个终端，用 echo $REALRELAY_API_KEY 检查，然后重新启动。

  • 404。url 只写到了 /v1。请补上 /chat/completions。

  • 找不到模型。id 与 GET /v1/models 不完全一致。请保留斜杠前面的前缀。

  • 回复被截断。maxOutputTokens 对当前任务来说太低。把它调高，最多到模型的上限。

  • 长任务中出现上下文报错。maxInputTokens 高于模型的真实窗口。把它设为模型的上限。

  • 修改文件后没有效果。改动没有保存到磁盘，或者项目级的 models.json 定义了相同的 id 并优先生效。