RealRelay.ai
编码智能体

OpenCode 接入指南

把 RealRelay.ai 作为 OpenAI 兼容的自定义提供商接入 OpenCode：安装、在 opencode.json 中添加提供商配置块、检查连接，并添加模型及其限制。

创建 API 密钥浏览目录
协议
OpenAI Chat Completions · OpenAI Responses
基础地址
https://www.realrelay.ai/v1
官方文档
opencode.ai
已对照工具官方文档核对
2026-10

概览

OpenCode 是一个运行在终端里的开源编码智能体。它会读取你的项目、编辑文件并运行命令。你把 RealRelay.ai 添加为它的自定义提供商后，它会把请求发到 Chat Completions 端点 /v1/chat/completions。

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

  • 末尾带 /v1 的基础地址。OpenCode 会在后面拼上 /chat/completions。

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

本页针对 OpenCode 1，即 opencode.ai/docs 文档所述的当前稳定版。OpenCode 2 预览版的提供商配置结构不同，下面的文件不适用于它。

安装

任选一种 OpenCode 官方文档中的安装方式。它们安装的都是同一个 opencode 命令。

macOS · Linux · WSL
curl -fsSL https://opencode.ai/install | bashopencode --version
Homebrew (macOS · Linux)
brew install anomalyco/tap/opencode

OpenCode 推荐使用它自己的 tap。普通的 brew install opencode 公式由 Homebrew 维护，更新没那么及时。

npm
npm install -g opencode-ai
Windows PowerShell
choco install opencode# orscoop install opencode

如果 opencode --version 输出了版本号，说明安装成功。OpenCode 文档推荐使用 WezTerm、Alacritty、Ghostty 或 Kitty 等现代终端。

配置

  1. 1

    把密钥存进环境变量

    配置文件从 REALRELAY_API_KEY 读取密钥，这样文件本身不含任何机密。

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"

    运行 source ~/.zshrc，或者新开一个终端。

    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")

    关闭并重新打开终端，让它读到新变量。

  2. 2

    把 RealRelay.ai 添加为提供商

    把下面的内容写进全局配置。如果只想在某个项目中使用，就把同样的内容写进项目根目录的 opencode.json。

    ~/.config/opencode/opencode.json
    1{2  "$schema": "https://opencode.ai/config.json",3  "provider": {4    "realrelay": {5      "npm": "@ai-sdk/openai-compatible",6      "name": "RealRelay.ai",7      "options": {8        "baseURL": "https://www.realrelay.ai/v1",9        "apiKey": "{env:REALRELAY_API_KEY}"10      },11      "models": {12        "z-ai/glm-5.2": {13          "name": "z-ai/glm-5.2",14          "limit": {15            "context": 200000,16            "output": 3200017          }18        }19      }20    }21  },22  "model": "realrelay/z-ai/glm-5.2"23}

  • realrelay 是提供商 ID。它可以取任意名称，但所有模型引用都以它开头，例如 realrelay/z-ai/glm-5.2。

  • npm 决定 OpenCode 加载哪个客户端。@ai-sdk/openai-compatible 发送 Chat Completions 请求。

  • OpenCode 启动时会把 {env:REALRELAY_API_KEY} 替换为该变量的值。如果变量未设置，密钥就是空的，请求会以 401 失败。

  • models 下的每个键都是发给 RealRelay.ai 的模型 ID。limit 告诉 OpenCode 上下文窗口和最大输出，因为 RealRelay.ai 的模型列表不包含这些信息。

  • model 设置新会话的默认模型。

你也可以用 OpenCode 的 /connect 命令保存密钥，而不用环境变量。选择 Other，输入与文件中相同的提供商 ID。然后删掉 apiKey 这一行。

OpenCode
1/connect2# Select provider → Other3# Enter provider id → realrelay4# Enter your API key → sk-***

验证

  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

    确认 OpenCode 识别到了提供商

    第一条命令应把你的模型列为 realrelay/…。第二条会发送一条消息并打印回复。

    Terminal
    opencode models realrelayopencode run -m "realrelay/z-ai/glm-5.2" "Reply with OK"
  3. 3

    在项目中启动会话

    运行 /models 并选择 RealRelay.ai 模型，然后发一条简短消息。该请求会出现在控制台的用量日志中。

    OpenCode
    cd /path/to/your/projectopencode/models

模型

OpenCode 只显示你在提供商下列出的模型。要添加模型，就再加一个条目，写上它的 ID 和限制，然后用 /models 选中它，或者用 opencode -m realrelay/<model-id> 启动。

~/.config/opencode/opencode.json → provider.realrelay.models
1"z-ai/glm-5.2": {2  "name": "z-ai/glm-5.2",3  "limit": { "context": 200000, "output": 32000 }4},5"<another-model-id>": {6  "name": "<another-model-id>",7  "limit": { "context": 128000, "output": 16000 }8}

这些示例中的限制是安全的起始值。请把 limit.context 和 limit.output 设为模型目录页上的真实数值，这样 OpenCode 才会在合适的时机压缩对话。

少数 OpenAI 模型在 Responses 端点 /v1/responses 上提供。OpenCode 通过 @ai-sdk/openai 客户端访问该端点。为这些模型再添加一个使用同一密钥的提供商，其余模型仍使用 Chat Completions 提供商：

~/.config/opencode/opencode.json → provider
1"realrelay-responses": {2  "npm": "@ai-sdk/openai",3  "name": "RealRelay.ai (Responses)",4  "options": {5    "baseURL": "https://www.realrelay.ai/v1",6    "apiKey": "{env:REALRELAY_API_KEY}"7  },8  "models": {9    "openai/gpt-5.3-codex": {10      "name": "openai/gpt-5.3-codex",11      "limit": { "context": 400000, "output": 128000 }12    }13  }14}

哪些模型适合智能体、哪些模型在 Responses 端点上提供，请见选择模型。

故障排查

  • /models 中没有该提供商或模型。JSON 没有加载成功，或者 models 映射为空。检查 OpenCode 实际解析到的是哪份配置；对于相同的键，项目中的 opencode.json 会覆盖全局文件。

    Terminal
    opencode auth listopencode debug config

  • 401。密钥为空或有误。确认启动 OpenCode 的终端里设置了 REALRELAY_API_KEY。如果你用的是 /connect，opencode auth list 应显示你的提供商 ID，而且它必须与文件中的 ID 一致。

  • 404。基础地址缺少 /v1，或者已经以 /chat/completions 结尾。请使用以 /v1 结尾的地址。

  • 找不到模型。models 下的键必须与 GET /v1/models 返回的 ID 完全一致，包括斜杠前面的部分。

  • 只支持 Responses 的模型报错，或你移到 Responses 提供商下的模型报错。只有“选择模型”中列出的模型在 /v1/responses 上提供。其他模型请留在 @ai-sdk/openai-compatible 提供商下。

  • 对话不断变长，直到请求被拒绝。limit.context 没有设置，或大于模型的真实窗口。按模型目录页设置它，然后运行 /compact。

  • 智能体只描述修改，却不实际执行。该模型没有调用工具。请选择支持工具调用的模型。