集成

OpenClaw

以 Markdown 格式查看

OpenClaw logo

将 OpenModels 作为 OpenClaw 的上游模型供应商。OpenClaw 保留对本地网关、会话、频道、工具和控制台的控制，同时模型请求通过 OpenModels 兼容 OpenAI 的 API 发送。

本指南聚焦 OpenClaw 调用 OpenModels。如果你希望其他应用调用 OpenClaw 自己的 /v1 端点，请参见下方“将 OpenClaw 用作 OpenAI 兼容端点”。

适用场景

当你希望实现以下目标时，请使用此配置：

  • 将 OpenClaw 用作聊天应用、智能体和本地工具的自托管助手网关。
  • 将 OpenModels 用作上游模型市场。
  • 使用一个带有积分计费的 OpenModels API 密钥，并从模型页面获取模型 ID。
  • 无需更改 OpenClaw 源代码即可使用兼容 OpenAI 的聊天补全。

前置条件

  • 在运行网关的主机上安装 OpenClaw。
  • Node.js 24，或 Node.js 22.19 及以上版本。
  • 一个 ale-... 格式的 OpenModels API 密钥。
  • 您的 OpenModels 账户中有可用积分。
  • 一个受支持的 OpenModels 聊天模型 ID，例如 qwen3.5-flash 或 kimi-k2.7-code。

1. 安装并启动 OpenClaw

在 macOS 或 Linux 上：

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

本地 OpenClaw 控制台通常运行在：

http://127.0.0.1:18789/

2. 准备 OpenModels 密钥

在 OpenModels 控制台中创建 API 密钥，并将其保留在版本控制之外：

export OM_API_KEY="ale-your-api-key"

对于长期运行的 OpenClaw 守护进程，请将密钥放在守护进程可读取的位置。OpenClaw 支持守护进程环境文件，因此简单本地配置可使用：

mkdir -p ~/.openclaw
printf 'OM_API_KEY=ale-your-api-key\n' >> ~/.openclaw/.env

不要将真实的 ale-... 密钥提交到应用仓库。

3. 将 OpenModels 添加为供应商

OpenClaw 模型引用使用此结构：

provider/model

使用 openmodels 作为供应商 ID，并把 OpenModels 模型 ID 放在斜杠后。

编辑 ~/.openclaw/openclaw.json：

{
  models: {
    mode: "merge",
    providers: {
      openmodels: {
        baseUrl: "https://api.getopenmodels.com/v1",
        api: "openai-completions",
        apiKey: "ale-your-api-key",
        models: [
          {
            id: "qwen3.5-flash",
            name: "qwen3.5-flash",
            input: ["text"],
            contextWindow: 1000000,
            maxTokens: 8192
          },
          {
            id: "kimi-k2.7-code",
            name: "kimi-k2.7-code",
            input: ["text"],
            contextWindow: 256000,
            maxTokens: 8192
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "openmodels/qwen3.5-flash",
        fallbacks: ["openmodels/kimi-k2.7-code"]
      },
      models: {
        "openmodels/qwen3.5-flash": { alias: "Qwen Flash" },
        "openmodels/kimi-k2.7-code": { alias: "Kimi Code" }
      }
    }
  }
}

如果你已有 models 或 agents 配置，请合并上述键，而不是替换整个文件。示例中的 apiKey 值是占位符。生产环境优先使用 OpenClaw 的密钥或环境变量机制。如果直接将密钥写入 openclaw.json，请确保该文件仅本地用户可读。

OpenClaw 会严格验证配置。如果编辑后网关未启动，请运行：

openclaw doctor
openclaw doctor --fix

4. 重启并验证

重启网关：

openclaw gateway restart

检查供应商和模型是否可见：

openclaw models list --provider openmodels
openclaw models set openmodels/qwen3.5-flash
openclaw models status

然后在控制台或已连接的聊天频道中发送消息。OpenClaw 应使用所选由 OpenModels 支持的模型。

5. 在会话中切换模型

切换到另一个 OpenModels 模型：

/model openmodels/kimi-k2.7-code

返回已配置的默认值：

/model default

如果 OpenClaw 报告模型不被允许，请将匹配的 openmodels/<model-id> 条目添加到 agents.defaults.models，或移除允许列表。

将 OpenClaw 用作 OpenAI 兼容端点

这是反向调用：另一个应用调用 OpenClaw，然后 OpenClaw 运行其已配置的智能体。

启用后，OpenClaw 网关可以暴露兼容 OpenAI 的端点：

http://127.0.0.1:18789/v1

对于 Open WebUI 或其他受信任本地应用：

字段值
基础 URLhttp://127.0.0.1:18789/v1
API 密钥OpenClaw 网关 bearer token
模型openclaw/default

请区分这些 URLs：

  • 当应用直接调用 OpenModels 时，使用 https://api.getopenmodels.com/v1。
  • 当应用调用你的本地 OpenClaw 网关时，使用 http://127.0.0.1:18789/v1。
  • 在 OpenClaw 的 /v1 端点中，OpenAI model 字段选择的是 openclaw/default 这样的 OpenClaw 智能体目标。后端供应商或模型覆盖项应放在 OpenClaw 配置或 x-openclaw-model 请求头中。

不要将 OpenClaw 的 /v1 端点直接暴露到公网。有效网关令牌是该网关的操作员级凭证。

故障排查

症状检查项
OpenModels 返回 401 或密钥无效确认 apiKey 是有效的 ale-... 密钥，并且密钥仍存在
余额或计费失败发送请求前向 OpenModels 账号添加积分
Model is not allowed将 openmodels/<model-id> 添加到 agents.defaults.models，或清空允许列表
网关未启动运行 openclaw doctor 并检查严格配置校验错误
会话一直使用旧模型运行 /model default，或启动没有固定模型的新会话
OpenClaw /v1/models 只显示 openclaw/default该端点返回 OpenClaw 智能体目标，而不是原始 OpenModels 模型 ID

参考资料