OpenClaw

OpenClaw 托管实例与自建 Gateway 的补充说明

更新于 2026-10-18 · yunwu.cyou

简答：如果你使用的是控制台里的 OpenClaw 一键部署，应先创建实例并等待 Running，再按页面提示使用 Gateway Token；如果是在自己的电脑或服务器运行 OpenClaw，则应配置 OpenAI 兼容接口的 Base URL、API Key 和模型 ID。两条路径的凭证、配置文件和排查方式不同，本文按 2026-10-18 可查到的 OpenClaw 文档整理。

定义：OpenClaw 是运行在本机或服务器上的自托管 Gateway，用于连接聊天渠道、AI Agent 和模型接口；托管实例则是由部署平台代为准备运行环境，用户主要通过 Gateway Token 进入实例。

先判断你使用的是哪条 OpenClaw 路径

本文是关于 OpenClaw 的第三方指南与配置整理，不代表 YUNWU.CYOU（云雾 API）官方，也不提供其控制台或托管实例支持。

OpenClaw 官方文档将它定义为自托管 Gateway：用户在自己的电脑或服务器运行 Gateway，再连接聊天应用、Agent 和模型服务。官方文档还说明，默认配置文件位于 ~/.openclaw/openclaw.json，本地控制界面默认地址是 http://127.0.0.1:18789/。可查看 OpenClaw 官方概览与快速开始文档。

如果你是在目标站点看到“OpenClaw 一键部署”入口，优先按照该入口的页面流程操作：选择机房与规格、等待实例进入 Running、打开实例并按提示粘贴 Gateway Token。托管部署功能和字段名称以 YUNWU.CYOU 控制台实际显示为准。

托管实例应该怎么使用

1. 进入 OpenClaw 部署入口。确认你打开的是实例创建页面，而不是本地 Gateway 配置页面。
2. 选择机房和规格。CPU、内存、磁盘等选项只影响托管实例本身，不能替代模型接口的 API Key 或模型权限。
3. 等待状态变为 Running。在镜像、Gateway 或相关服务尚未就绪时，不要反复刷新或提前粘贴 Token。
4. 打开实例。如果页面要求 Gateway Token，应使用该实例对应的 Token，不要把模型服务 API Key 当成 Gateway Token。
5. 完成模型侧配置。若实例内仍要求填写模型服务的 Base URL、模型 ID 或 API Key，应按照页面字段填写；具体可用值以托管实例页面和对应接口文档为准。

托管实例和自建 Gateway 的关键差别是：Gateway Token 用于访问或连接 Gateway，模型 API Key 用于调用上游模型接口。两者用途不同，不能因为名称都包含“Token”就互换。

如果实例已经 Running 但无法打开，先记录页面显示的状态、请求时间和脱敏后的错误信息；不要在公开截图、工单或仓库中暴露完整 Gateway Token、API Key、Cookie 或请求头。

自建 Gateway 接入 OpenAI 兼容接口

自建方式适用于你已经在本机或服务器安装 OpenClaw，并准备把它连接到一个提供 OpenAI 兼容接口的模型服务。OpenClaw 官方文档使用 models.providers 注册自定义 provider，并要求在模型列表中至少配置与实际模型匹配的 id；模型引用格式是 provider/model。可查看 OpenClaw 官方 Model providers 文档 和 OpenClaw 官方 Models 文档。

1. 准备三个变量。BASE_URL 应填写接口的 OpenAI 兼容根地址，通常包含 /v1；KEY 是模型接口 API Key；MODEL_ID 是接口实际接受的模型 ID。不要直接照抄示例中的占位值。
2. 先脱离 OpenClaw 验证接口。先请求 /models，确认 Base URL、Key 和模型 ID 是否可用，再修改 OpenClaw 配置。
3. 写入环境变量。配置文件只引用环境变量，不把明文 Key 写入 JSON5，也不要将配置文件提交到公开仓库。
4. 注册自定义 provider。使用 api: "openai-completions"，并让 baseUrl 与接口实际路径保持一致。若接口已要求 /v1，不要在代码和配置中重复拼接。
5. 设置默认模型。OpenClaw 的默认模型使用 provider/model 形式，例如 yunwu/MODEL_ID；其中 yunwu 只是本地配置中的 provider ID，不代表本站或该接口的官方归属。
6. 重启或重新加载 Gateway。然后使用 openclaw models list、openclaw models status 检查模型是否被识别。

最小接口验证示例

依赖工具：支持环境变量的终端、curl，以及用于查看 JSON 的 jq。示例不写死域名，也不会重复拼接 /v1。

export BASE_URL="https://api.example.com/v1"
export KEY="从密钥管理器读取的 API Key"
export MODEL_ID="接口返回的模型 ID"

curl -fsS "${BASE_URL}/models" \
  -H "Authorization: Bearer ${KEY}" \
  -H "Accept: application/json" | jq '.data[] | {id}'

curl -fsS "${BASE_URL}/chat/completions" \
  -H "Authorization: Bearer ${KEY}" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg model "$MODEL_ID" '{model:$model,messages:[{role:"user",content:"Reply with OK"}],stream:false}')" \
  | jq '{id, model, content: .choices[0].message.content}'

预期成功响应通常应能看到请求 id、实际返回的 model，以及 choices[0].message.content。不同兼容接口的响应字段可能有差异；如果 .data 或 .choices[0].message.content 不存在，应先查看原始 JSON，不要直接假设模型 ID 或响应格式正确。

OpenClaw 最小 JSON5 配置示例

OpenClaw 官方概览文档给出的主配置文件是 ~/.openclaw/openclaw.json；自定义 provider 的模型数据也可能写入默认 Agent 目录下的 models.json。实际生成位置以你的 OpenClaw 版本和 Agent 配置为准。下面只保留注册 provider 和选择默认模型所需的字段，不填写未经核实的上下文窗口、最大输出或价格数据。

// ~/.openclaw/openclaw.json
{
  models: {
    providers: {
      yunwu: {
        baseUrl: "${BASE_URL}",
        apiKey: "${KEY}",
        api: "openai-completions",
        models: [
          {
            id: "${MODEL_ID}",
            name: "Configured model"
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "yunwu/${MODEL_ID}"
      }
    }
  }
}

上面的配置表达的是 OpenAI 兼容调用路径，不是对某个具体服务可用性的保证。若你的 OpenClaw 版本不支持在模型 ID 字段中展开环境变量，可先把实际模型 ID 写入受保护的本地配置，再通过密钥管理或 SecretRef 管理 API Key；不要把完整 Key 写入截图、文章、Issue 或 Git 仓库。OpenClaw 官方文档还说明，使用自定义 provider 时，模型行至少要有匹配的 id，而 agents.defaults.models 主要用于模型可见性、别名和元数据，并不能单独注册新的运行时模型。

模型 ID、Base URL 和 Gateway Token 怎么区分

最稳妥的顺序是先用 curl 验证 /models，再验证一次非流式 /chat/completions，最后才把同一组 Base URL、Key 和模型 ID 写入 OpenClaw。这样可以把问题分成三类：接口本身不可用、凭证或模型不匹配、OpenClaw 配置格式错误。

如果模型能在 /models 中列出，但 OpenClaw 仍提示模型不存在，检查默认模型是否写成了完整的 provider/model 格式，以及 models.providers.<provider>.models[].id 是否与接口返回值完全一致。官方文档指出，模型引用使用 provider/model 形式，且显式配置的模型行需要与 provider 下的模型 ID 匹配。

如果你需要排查流式输出中断、include_usage 或 [DONE]，请参阅本站教程：OpenAI API 流式输出中断怎么解决；这属于另一个具体问题，不建议和首次接入配置混在一起排查。

接入前后的安全检查清单

• 不要把 Gateway Token、模型 API Key 或完整 Authorization 请求头放进公开截图。
• 配置文件使用环境变量、文件权限或 SecretRef 管理凭证，避免明文进入 Git。
• 先验证 /models，再验证非流式聊天请求，最后启动 OpenClaw 会话。
• 不要把服务商展示名称当作模型 ID；以接口返回的 data[].id 为准。
• 不要把托管实例的 Gateway Token 填入模型 provider 的 apiKey 字段。
• 不要自行补写上下文窗口、最大输出、价格或能力字段；只有在对应接口文档明确给出时再配置。
• 如需在图形化工具中复用同一套 OpenAI 兼容参数，可先阅读本站教程：LobeChat 配置 OpenAI API，重点核对 Key、Base URL 与模型设置。

常见问题

OpenClaw 一键部署和自建 Gateway 是同一种方式吗？

不是。控制台一键部署通常由平台准备运行环境，用户按页面提示创建实例、等待 Running 并使用 Gateway Token；自建 Gateway 则由用户在自己的电脑或服务器安装 OpenClaw，再配置模型 provider、Base URL、API Key 和模型 ID。

Gateway Token 可以直接当作模型 API Key 使用吗？

通常不能。Gateway Token 用于访问或连接 OpenClaw Gateway，模型 API Key 用于调用上游模型接口。两者的用途和配置位置不同，托管实例应按页面提示使用 Gateway Token，自建 provider 则应使用对应模型接口的 API Key。

OpenClaw 的配置文件在哪里？

OpenClaw 官方概览文档说明，主配置文件默认位于 <code>~/.openclaw/openclaw.json</code>。自定义 provider 的模型数据还可能写入默认 Agent 目录下的 <code>~/.openclaw/agents/<agentId>/agent/models.json</code>；具体以当前版本、Agent 设置和实际生成结果为准。

为什么 /models 能返回模型，但 OpenClaw 仍提示模型不存在？

先确认配置中的 provider ID、模型 ID 和默认模型引用是否一致。OpenClaw 的模型引用使用 <code>provider/model</code>，例如 <code>yunwu/MODEL_ID</code>；同时检查 <code>models.providers.<provider>.models[].id</code> 是否与接口返回的 <code>data[].id</code> 完全一致。

配置文件里的 API Key 应该怎么写？

不要把真实 Key 直接写入配置文件。将 Key 放入环境变量或密钥管理器，再让配置通过环境变量引用；同时避免把配置文件提交到仓库或把包含凭证的终端输出、截图发送给他人。

相关阅读

• 本站教程：OpenAI API 流式输出中断排查
• 本站教程：LobeChat 配置 OpenAI API
• 本站教程更新列表

参考资料

1. OpenClaw 官方概览与快速开始文档
2. OpenClaw 官方 Model providers 文档
3. OpenClaw 官方 Models 文档
4. OpenClaw 官方 Gateway 配置文档