⌘K

OpenClaw

概述

OpenClaw 支持在 ~/.openclaw/openclaw.json 中配置自定义模型 provider。将 Vtrix 添加到 models.providers，使用 OpenAI 兼容请求适配器，并通过 vtrix/gpt-5.3-codex 这类 OpenClaw 模型引用选择 Vtrix 模型即可。

环境要求

  • Node.js 22.19+、23.11+ 或 24+
  • OpenClaw CLI
  • Vtrix API Key, 在 设置 中创建
可选：使用 Vtrix Doctor

也可以先使用 Vtrix Doctor 检查本机 Base URL、API Key 和模型配置。已支持的工具，包括 OpenClaw 和 Hermes，可在确认后一键写入配置。

配置步骤

1

安装 OpenClaw

• 使用安装脚本

curl -fsSL https://openclaw.ai/install.sh | bash

• 或使用 npm

npm install -g openclaw@latest
openclaw onboard --install-daemon

安装完成后运行：

openclaw --version
openclaw doctor
2

保存 Vtrix API Key

OpenClaw 会加载当前工作目录的 .env 和 ~/.openclaw/.env。创建或编辑全局文件：

mkdir -p ~/.openclaw
vim ~/.openclaw/.env

加入：

VTRIX_API_KEY=YOUR_VTRIX_API_KEY
3

将 Vtrix 添加为自定义 provider

创建或编辑 ~/.openclaw/openclaw.json：

vim ~/.openclaw/openclaw.json

加入或合并以下 JSON5 配置：

{
  agents: {
    defaults: {
      model: { primary: "vtrix/gpt-5.3-codex" },
      models: {
        "vtrix/gpt-5.3-codex": { alias: "GPT-5.3 Codex via Vtrix" },
        "vtrix/gpt-5.5": { alias: "GPT-5.5 via Vtrix" },
        "vtrix/qwen3.7-max": { alias: "Qwen3.7 Max via Vtrix" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      vtrix: {
        baseUrl: "https://cloud.vtrix.ai/llm",
        apiKey: "${VTRIX_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.3-codex", name: "GPT-5.3 Codex" },
          { id: "gpt-5.5", name: "GPT-5.5" },
          { id: "qwen3.7-max", name: "Qwen3.7 Max" },
        ],
      },
    },
  },
}
Base URL

Vtrix 的 OpenAI 兼容 Base URL 使用 https://cloud.vtrix.ai/llm. OpenClaw 的 openai-completions 适配器会在模型请求时拼接 chat completions 路由.

4

校验并启动 OpenClaw

校验配置：

openclaw config validate
openclaw models list

启动或重启 gateway：

openclaw gateway start

也可以先做一次本地快速校验：

openclaw infer "请用一句话总结当前项目。"

如果 OpenClaw 能正常回复, 说明请求已通过配置的 provider 路由到 Vtrix. 也可在 Vtrix 设置 中查看账单或用量.

故障排查

配置无效或 gateway 拒绝启动

原因： ~/.openclaw/openclaw.json 使用 JSON5，但仍必须符合 OpenClaw schema。未知字段或格式错误会导致 gateway 拒绝配置文件。

处理：

openclaw config validate
openclaw doctor --fix
报错：401 Unauthorized

原因： VTRIX_API_KEY 未设置、设置错误, 或 OpenClaw 未加载到该环境变量.

处理：

grep VTRIX_API_KEY ~/.openclaw/.env

确认密钥存在后, 重新启动 OpenClaw.

模型选择器没有显示 Vtrix 模型

原因： agents.defaults.models 没有包含 vtrix/... 模型引用, 或缺少 models.providers.vtrix.models 条目.

处理： 确认两个部分都存在：

agents: {
  defaults: {
    model: { primary: "vtrix/gpt-5.3-codex" },
    models: { "vtrix/gpt-5.3-codex": { alias: "GPT-5.3 Codex via Vtrix" } },
  },
}
报错：model not found

原因： models.providers.vtrix.models[].id 中的模型 ID 与 Vtrix 模型 ID 不一致.

处理： 前往 模型页面 复制正确的模型 ID, 然后同步更新 provider model 条目和 vtrix/... 引用.