RealRelay.ai
编码智能体

OpenClaw 接入指南

把 RealRelay.ai 作为 OpenAI 兼容的自定义提供商接入 OpenClaw：安装、添加 models.providers 条目、确认 Gateway 已识别并选择模型。

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

概览

OpenClaw 是一个自托管的助手。一个名为 Gateway 的后台进程运行在你自己的机器上，在本地保存记忆和会话，并通过仪表盘或你接入的聊天应用回复你。RealRelay.ai 不在它的内置提供商之列，所以需要把它添加为一个使用 OpenAI Chat Completions API（/v1/chat/completions）的自定义提供商。

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

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

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

本配置依据 OpenClaw 的文档编写，但尚未在 RealRelay.ai 上端到端跑通。正式使用前，请先完成“验证”一节中的检查。

安装

使用 OpenClaw 的安装程序。它会在缺少 Node.js 时安装 Node.js，然后安装 OpenClaw 并启动设置向导。你可以先用任意提供商完成向导，之后再切换到 RealRelay.ai；也可以直接关闭向导，按下一节操作。

macOS · Linux · WSL2
curl -fsSL https://openclaw.ai/install.sh | bash
Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

OpenClaw 还提供 Windows 桌面应用 Windows Hub。下载链接见安装页面。

npm (Node.js 24.16+)
npm install -g openclaw@latest --allow-scripts=openclawopenclaw onboard --install-daemon

npm 11.15 或更早版本请去掉 --allow-scripts=openclaw。

--install-daemon 会把 Gateway 安装为后台服务，关闭终端后它仍会继续运行。

配置

你可以自己编辑配置文件，从而完全掌控模型列表；也可以让设置向导来写。

  1. 1

    把密钥存到 Gateway 能读取的位置

    Gateway 作为后台服务运行，看不到你在终端里 export 的变量。请把密钥写进 OpenClaw 自己的环境文件。把 sk-*** 替换成你的密钥。

    ~/.openclaw/.env
    REALRELAY_API_KEY=sk-***
  2. 2

    添加提供商

    把下面的内容合并进 ~/.openclaw/openclaw.json。该文件是 JSON5 格式，允许注释和尾随逗号。保留向导写入的其他设置。

    ~/.openclaw/openclaw.json
    1{2  models: {3    mode: "merge",4    providers: {5      realrelay: {6        baseUrl: "https://www.realrelay.ai/v1",7        apiKey: "${REALRELAY_API_KEY}",8        api: "openai-completions",9        models: [10          {11            id: "z-ai/glm-5.2",12            name: "z-ai/glm-5.2",13            reasoning: false,14            input: ["text"],15            contextWindow: 200000,16            maxTokens: 32768,17          },18        ],19      },20    },21  },22  agents: {23    defaults: {24      model: { primary: "realrelay/z-ai/glm-5.2" },25    },26  },27}
  3. 3

    重启 Gateway

    Gateway 会监视配置文件，大多数改动会自动生效。但它只在启动时读取环境文件，所以添加密钥后需要重启一次。

    Terminal
    openclaw gateway restart

运行 openclaw onboard 并选择自定义提供商选项，或者一次性传入全部参数。使用 --secret-input-mode ref 时，向导保存的是对 CUSTOM_API_KEY 的引用，而不是密钥本身。

Terminal
1export CUSTOM_API_KEY="sk-***"2openclaw onboard --non-interactive --accept-risk \3  --auth-choice custom-api-key \4  --custom-base-url "https://www.realrelay.ai/v1" \5  --custom-model-id "z-ai/glm-5.2" \6  --custom-compatibility openai \7  --custom-text-input \8  --secret-input-mode ref

然后把同一个变量写进环境文件，让后台的 Gateway 能够解析它，再重启 Gateway。提供商名称由向导自行决定；openclaw models list 会显示它。

~/.openclaw/.env
CUSTOM_API_KEY=sk-***

  • realrelay 是提供商名称。你可以换一个名字，但它必须与 agents.defaults.model.primary 中的前缀一致。

  • mode: "merge" 会把 RealRelay.ai 添加到 OpenClaw 内置提供商旁边，而不是替换它们。

  • Gateway 加载配置时，会从环境中读取 "${REALRELAY_API_KEY}"，所以密钥永远不会出现在 openclaw.json 中。

  • api: "openai-completions" 发送 Chat Completions 请求。请保持不变：RealRelay.ai 上的大多数模型只在该端点上提供。

  • contextWindow 和 maxTokens 告诉 OpenClaw 该模型能接收多少、能返回多少。RealRelay.ai 不会报告这些信息，所以请按模型目录页设置。这里显示的值对 z-ai/glm-5.2 是安全的。

  • primary 模型必须出现在提供商的 models 列表中。只在 agents.defaults.models 下列出它并不能让它可用。

验证

  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

    检查 Gateway 和模型列表

    openclaw gateway status 应报告 Gateway 正在运行。openclaw models status 显示默认模型，它应以 realrelay/ 开头；openclaw models list 中应包含你的模型。openclaw dashboard 会在浏览器中打开仪表盘。

    Terminal
    1openclaw gateway status2openclaw models status3openclaw models list4openclaw dashboard
  3. 3

    发送一条消息

    在仪表盘的聊天中发一条简短消息。收到回复即说明整条链路畅通，该请求也会出现在控制台的用量日志中。

模型

在聊天中，用 /model 加模型引用即可切换当前会话的模型。要更改新会话的默认模型，请使用 openclaw models set。模型引用的格式是提供商名称、斜杠，再加完整的 RealRelay.ai 模型 ID，所以其中有两个斜杠。

OpenClaw chat
/model realrelay/z-ai/glm-5.2
Terminal
openclaw models set realrelay/z-ai/glm-5.2

OpenClaw 只提供你在提供商下列出的模型。每个要用的模型加一个条目，各自设置限制：

~/.openclaw/openclaw.json → models.providers.realrelay.models
{ id: "z-ai/glm-5.2", name: "z-ai/glm-5.2", contextWindow: 200000, maxTokens: 32768 },{ id: "deepseek/deepseek-v4-pro", name: "deepseek/deepseek-v4-pro", contextWindow: 200000, maxTokens: 32768 },

如果省略 contextWindow，OpenClaw 会假定为 200,000 token。如果省略 maxTokens，它不会发送输出上限，而是沿用模型的默认值。哪些模型适合智能体，请见选择模型。

故障排查

  • 401 或“Invalid token”。Gateway 看不到密钥。确认密钥写在 ~/.openclaw/.env 中，而不只是在终端里 export，然后重启 Gateway。工作目录下的 .env 文件不算数：OpenClaw 会忽略其中的提供商密钥。

  • 404。baseUrl 缺少 /v1，或者已经以 /chat/completions 结尾。它应以 /v1 结尾，后面不再有其他内容。

  • “Unknown model”，或默认模型没有生效。primary 的前缀与提供商名称不一致，或者该模型不在提供商的 models 列表中。模型 ID 区分大小写。

  • 更改默认模型后，会话仍在用旧模型。已有会话会继续使用它启动时的模型。在该会话中运行 /model default。

  • 400 并提到 reasoning_effort，发生在你标记了 reasoning: true 的模型上。为该模型关闭这个字段：

    ~/.openclaw/openclaw.json → models.providers.realrelay.models
    1{2  id: "z-ai/glm-5.2",3  reasoning: true,4  compat: { supportsReasoningEffort: false },5},

  • 长对话中出现上下文报错。contextWindow 大于模型的真实上限。把它调低到模型目录页上的数值。

  • 仪表盘里看不出明显问题。用 openclaw gateway stop 停止后台服务，然后在前台运行 Gateway 观察日志。排查完毕后，用 openclaw gateway start 重新启动服务。

    Terminal
    openclaw gateway --port 18789