# OpenClaw 接入 [OpenClaw](https://openclaw.ai/) 是一个开源的自治 AI 智能体,带本地控制台、可接入多种消息渠道。把它的模型服务指向 Clomio,就能用 Clomio 的额度驱动它。 > 本页只解决一件事:**把 OpenClaw 的模型调用接到 Clomio 并验证可用**。渠道(如 WhatsApp/Telegram)配置请参考 OpenClaw 官方文档。 > **服务端边界:** Hermes/OpenClaw 的 `api_mode`、`api`、provider 枚举只是客户端侧选择。Clomio/sub2api 服务端不会识别“Hermes provider”或“OpenClaw enum”，只根据实际 HTTP path 与 API Key 绑定分组路由：Grok 对话走 `POST /v1/responses`，Claude 走 `POST /v1/messages`，OpenAI/Codex 走 Responses/Chat/Images/Embeddings 对应端点；Videos 只属于启用视频能力的 Grok 分组。 --- ## 一、准备 - 在控制台 [api.clomio.ai](https://api.clomio.ai) 创建一个 API 密钥(见 [创建 API 密钥](#/api-key)) - 知道你要调用的模型名(以控制台分组为准) - 环境:推荐 Node 较新版本;Windows 建议用 **WSL2 + Ubuntu** - 如需运行环境,见 [Node.js 环境](#/nodejs) --- ## 二、安装 macOS / Linux / WSL2: ```bash # 安装,--no-onboard 表示先不自动进向导 curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard ``` 验证: ```bash openclaw --help ``` --- ## 三、用向导接入 Clomio 启动接入向导: ```bash openclaw onboard ``` 到模型/鉴权步骤时,选 **Custom provider(自定义服务商)**,按下表填: | 字段 | 填写 | |------|------| | 兼容类型 / API | Clomio 常规只推荐 `openai-responses`、`openai-completions` 或 `anthropic-messages` | | 基础地址 | 见下方 `/v1` 规则 | | 模型名 | 控制台中该分组开放的模型,如 `claude-sonnet-4-6`、`gpt-5.4`、Grok 模型 | | Provider ID | `clomio` 或更细分的 `clomio-responses`、`clomio-anthropic` | | API Key | 你的 Clomio 密钥 | **基础地址按兼容类型填:** - `openai-responses` / `openai-completions` → `https://api.clomio.ai/v1`(**加** `/v1`) - `anthropic-messages` → `https://api.clomio.ai`(**不加** `/v1`) > 地址也可换成另外两条[线路](#/gateway-lines)。模型引用通常写成 **`provider/model`**,例如 `clomio/gpt-5.4`。 OpenClaw 官方模型引用以 `provider/model` 为核心:provider 负责鉴权、Base URL 和 API 形状,model 是该 provider 下声明的 `models[].id`。接 Clomio 时建议按协议拆 provider,而不是把 Claude、GPT、Grok 混进同一个 provider。 --- ## 四、配置文件方式:models.providers OpenClaw 的自定义服务商写在 `models.providers.`。核心字段: - `baseUrl`: 网关基础地址 - `apiKey`: API Key 或环境变量引用 - `api`: provider 的协议形状；接 Clomio 时优先用 `openai-responses`、`openai-completions`、`anthropic-messages` - `models`: 该 provider 下可用模型列表 `api` 字段不要把 OpenClaw 支持的所有枚举都当成 Clomio 推荐项。不同 OpenClaw 版本/内置 provider 报错里可能出现 `openai-completions`、`openai-responses`、`openai-codex-responses`、`openai-chatgpt-responses`、`anthropic-messages`、`google-generative-ai`、`github-copilot`、`bedrock-converse-stream`、`ollama`、`azure-openai-responses` 等值；接 Clomio custom provider 时按下面三类选即可: | Clomio 场景 | 推荐 `api` | `baseUrl` | |---|---|---| | Claude / Anthropic-compatible | `anthropic-messages` | `https://api.clomio.ai`，不加 `/v1` | | OpenAI Chat Completions | `openai-completions` | `https://api.clomio.ai/v1` | | Responses / Codex / Grok Responses | `openai-responses` | `https://api.clomio.ai/v1` | `openai-codex-responses`、`openai-chatgpt-responses`、`azure-openai-responses`、`google-generative-ai`、`ollama` 等只在对应 OpenClaw 版本或官方 provider 明确要求时使用，不作为 Clomio custom provider 的首选。 下面示例用环境变量保存密钥: ```bash export CLOMIO_API_KEY="你的密钥" ``` ### OpenAI Responses 示例 适合走 `/v1/responses` 的分组,例如 Responses/Codex/Grok Responses 类接口。 ```json { "models": { "providers": { "clomio-responses": { "baseUrl": "https://api.clomio.ai/v1", "apiKey": "${CLOMIO_API_KEY}", "api": "openai-responses", "models": [ { "id": "gpt-5.4", "name": "GPT 5.4 via Clomio Responses" } ] } } }, "agents": { "defaults": { "model": { "primary": "clomio-responses/gpt-5.4" } } } } ``` Grok 用 OpenAI-compatible Responses provider,模型引用形如 `clomio-grok/grok-4.3`;Grok 不要配置到 `anthropic-messages`,也不要用 `openai-completions`: ```json { "models": { "providers": { "clomio-grok": { "baseUrl": "https://api.clomio.ai/v1", "apiKey": "${CLOMIO_GROK_API_KEY}", "api": "openai-responses", "models": [ { "id": "grok-4.3", "name": "Grok 4.3 via Clomio", "input": ["text", "image"] } ] } } }, "agents": { "defaults": { "model": { "primary": "clomio-grok/grok-4.3" } } } } ``` 如果该模型要接收图片,在 OpenClaw 的模型元数据里声明 `input: ["text", "image"]`;否则 WebChat 或节点侧附件可能被当成纯文本媒体引用。 ### OpenAI Completions 示例 适合标准 OpenAI-compatible `/v1/chat/completions` 服务。 ```json { "models": { "providers": { "clomio-openai": { "baseUrl": "https://api.clomio.ai/v1", "apiKey": "${CLOMIO_API_KEY}", "api": "openai-completions", "models": [ { "id": "gpt-5.4", "name": "GPT 5.4 via Clomio Chat Completions" } ] } } }, "agents": { "defaults": { "model": { "primary": "clomio-openai/gpt-5.4" } } } } ``` ### Anthropic Messages 示例 适合 Claude / Anthropic Messages 形状的分组。注意 `baseUrl` **不带** `/v1`。 ```json { "models": { "providers": { "clomio-anthropic": { "baseUrl": "https://api.clomio.ai", "apiKey": "${CLOMIO_API_KEY}", "api": "anthropic-messages", "models": [ { "id": "claude-sonnet-4-6", "name": "Claude Sonnet via Clomio" } ] } } }, "agents": { "defaults": { "model": { "primary": "clomio-anthropic/claude-sonnet-4-6" } } } } ``` > 如果一个 Clomio 密钥只属于某个分组,请不要把不同协议的模型混在同一个 provider 里。建议按协议拆成 `clomio-responses`、`clomio-openai`、`clomio-anthropic`。 --- ## 五、验证 向导或配置完成后,先用 curl 证明 Clomio Key、模型和协议本身可用,再排 OpenClaw 配置。 OpenAI Responses / Grok Responses: ```bash curl https://api.clomio.ai/v1/responses -H "Authorization: Bearer $CLOMIO_API_KEY" -H "content-type: application/json" -d '{"model":"gpt-5.4","input":"ping","max_output_tokens":8}' ``` OpenAI Chat Completions(不要用于 Grok 分组): ```bash curl https://api.clomio.ai/v1/chat/completions -H "Authorization: Bearer $CLOMIO_API_KEY" -H "content-type: application/json" -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"ping"}],"max_tokens":8}' ``` Anthropic Messages: ```bash curl https://api.clomio.ai/v1/messages -H "Authorization: Bearer $CLOMIO_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"claude-sonnet-4-6","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}' ``` curl 通过后再运行: ```bash openclaw doctor # 检查配置格式、可修复项和密钥引用 openclaw models list # 查看 OpenClaw 实际加载到的 provider/model openclaw models get # 查看当前默认模型(如版本支持) openclaw status # 查看运行状态与默认模型 openclaw dashboard # 打开本地控制台,发一条消息测试 ``` 如果 `models get` 在你的版本里不可用,用 `openclaw models --help` 查看对应子命令。最终以 `openclaw models list` 能看到 `provider/model`、`openclaw status` 指向正确默认模型、dashboard 能收到模型回复为成功标准。 --- ## 六、脚本化接入(可选) 写进部署脚本时用非交互模式。OpenAI-compatible 示例: ```bash export CUSTOM_API_KEY="你的密钥" openclaw onboard --non-interactive \ --mode local \ --auth-choice custom-api-key \ --custom-base-url "https://api.clomio.ai/v1" \ --custom-model-id "gpt-5.4" \ --custom-provider-id "clomio-openai" \ --custom-compatibility openai \ --secret-input-mode ref \ --gateway-port 18789 \ --gateway-bind loopback ``` 手写配置时,默认模型要写成 **`服务商ID/模型名`** 格式(如 `clomio-openai/gpt-5.4`),只写模型名会报“模型不存在”。脚本里的 `--custom-compatibility openai` 在不同版本里可能默认落到 Chat Completions;如果目标是 Codex/Grok Responses,请确认该版本能显式选择 `openai-responses` 或在生成后的 `models.providers..api` 中改成 `openai-responses`,否则 Grok 会因为走 `/v1/chat/completions` 而失败。 --- ## 常见问题 **填了地址还连不上?** 先确认 `openai-responses` / `openai-completions` 的 `baseUrl` 带 `/v1`,而 `anthropic-messages` 的 `baseUrl` 不带 `/v1`,且没有多余斜杠。 **报模型不存在?** 模型名要与控制台分组一致;默认模型要写成 `provider/model`,例如 `clomio-responses/gpt-5.4`。只在 `agents.defaults.models` 里写 allowlist 不等于注册 provider,自定义模型还要在 `models.providers..models[]` 里声明。 **为什么 `provider/model` 有时会“少掉第一段”?** `provider/model` 的第一段主要给 OpenClaw 选择 provider。比如默认模型写 `clomio-responses/gpt-5.4`,真正发给 Clomio 的模型通常是 provider 下的 `models[].id`：`gpt-5.4`。如果真实上游模型 ID 本身带 slash,例如 `xai/grok-4.3`,就把 provider 下模型声明为 `"id": "xai/grok-4.3"`,默认模型写 `clomio-responses/xai/grok-4.3`;OpenClaw 去掉第一段 provider 后,发给 Clomio 的仍是 `xai/grok-4.3`。 **`openclaw models list` 看不到模型?** 检查配置文件层级是不是 `models.providers.`,字段名是不是 `baseUrl`、`apiKey`、`api`、`models`,而不是其他工具的 `base_url` 或 `key_env`。 **选错 `api` 会怎样?** `openai-completions` 会发 Chat Completions 形状请求;`openai-responses` 会发 Responses 形状请求;`anthropic-messages` 会发 Anthropic Messages 形状请求。协议和分组不匹配时常见 400、404、字段解析失败、工具调用异常。 **Anthropic-compatible 为什么配置不带 `/v1`?** OpenClaw 在 `anthropic-messages` 模式下按 Anthropic Messages 路径拼接请求。`baseUrl` 写成 `https://api.clomio.ai/v1` 容易导致路径重复或端点不匹配。 **一个 provider 能同时放 Claude、GPT、Grok 吗?** 不建议。不同协议对应不同 `api`,最好按协议拆 provider,再通过 `provider/model` 指定默认模型和 fallback。 **allowlist 写了但还是 `model not found`?** `agents.defaults.models["provider/model"]` 或可见性/别名配置只控制展示和默认选择,不等于注册运行时模型。自定义模型必须同时存在于 `models.providers..models[]`,且 `agents.defaults.model.primary` 要写完整的 `provider/model`。 **看到 `/v1/messages`、`/v1/responses` 或 `/v1/chat/completions` 与预期不一致?** 这是 `api` 选错的信号:`anthropic-messages` 会打 `/v1/messages`;`openai-responses` 会打 `/v1/responses`;`openai-completions` 会打 `/v1/chat/completions`。按错误里的路径反推当前 provider,再核对 Key 分组是否匹配。 **密钥环境变量没生效?** 先在同一个 shell 里运行 `echo ${CLOMIO_API_KEY:+set}`;如果用 systemd、桌面应用或守护进程启动 OpenClaw,要把环境变量写入对应启动环境。 **OpenAI 官方 provider 和 Clomio custom provider 怎么区分?** OpenClaw 官方 `openai/*` provider 面向 OpenAI/Codex 自身认证与运行时;Clomio 接入按 custom provider 写 `models.providers.` 更可控。不要把 `openai/gpt-*`、`clomio-responses/gpt-*` 和 `clomio-anthropic/claude-*` 混写成同一个默认模型。 --- ## 官方参考资料 - [OpenClaw Model providers](https://docs.openclaw.ai/concepts/model-providers):provider 负责认证与模型目录,默认模型使用 `provider/model`。 - [OpenClaw OpenAI provider](https://docs.openclaw.ai/providers/openai):官方 `openai/*` provider 的认证、Codex/OpenAI 运行时和模型路由说明。 - [OpenClaw Models CLI](https://docs.openclaw.ai/concepts/models):用 `openclaw models list/status/auth` 核对当前可用 provider、模型和认证状态。 这些资料里的外部经验落到 Clomio 时要做三件事:第一,不要直接复用官方 `openai/*` provider 的默认地址,应新建 `models.providers.` custom provider;第二,OpenAI-compatible provider 的 `baseUrl` 写到 `https://api.clomio.ai/v1`,Anthropic Messages provider 写到 `https://api.clomio.ai`;第三,把 Claude、GPT/Codex、Grok 拆成不同 provider,因为 sub2api 最终按真实 HTTP path 和 Key 分组门禁路由,不是按 OpenClaw 的模型展示名路由。 > 其余网络类问题见 [故障排查](#/troubleshooting)。