本文基于 2026 年 8 月的 OpenClaw 配置方式整理。重点不是介绍 OpenClaw 是什么，而是解决一个更实际的问题：安装完成以后，怎样把国内外模型稳定地接进去，并且随时切换。

很多人第一次安装 OpenClaw，最容易卡住的不是 Node.js，也不是 Gateway，而是模型配置。

想用 GPT，需要准备一套 API Key；想试 Claude，又要注册另一个平台；切到 Gemini、DeepSeek、Qwen，还要继续管理不同的充值入口、接口地址和模型名称。

模型只接一个时感觉不到麻烦。一旦 OpenClaw 开始承担写代码、查资料、整理文件、定时执行任务等工作，问题马上就会出现：

  • 不同模型的 API 地址不一样；

  • 每个平台的 Key 分散在不同后台；

  • 模型名称填错一个字符就会返回 404；

  • 某条线路限流后，整个 Agent 直接停下来；

  • 为了换模型，不得不反复修改配置文件。

这篇文章提供两种方案：分别接入模型厂商官方 API，以及通过一个 OpenAI 兼容接口统一接入。你可以根据账号、网络和费用情况自行选择。

如果你只想先看结果，本文最终要实现的是：

OpenClaw
   └── genvis 统一 Provider
         ├── GPT
         ├── Claude
         ├── Gemini
         ├── DeepSeek
         └── Qwen

配置完成后，切换模型只需要执行：

openclaw models set genvis/模型ID

而不需要每换一次模型，就重新注册 Provider、修改 Base URL 和更换 API Key。

一、开始前先弄懂三个概念

OpenClaw 的模型配置看起来字段很多，真正需要先理解的只有三个。

1. Provider

Provider 是模型服务的来源。

例如，使用官方接口时，OpenAI、Anthropic、Google、DeepSeek 可以分别成为一个 Provider。使用统一的 OpenAI 兼容接口时，也可以把这个接口注册成一个自定义 Provider。

本文给统一接口取名为：

genvis

这个名字只是 OpenClaw 内部的标识，可以换成其他名称，但后面的模型引用必须保持一致。

2. Base URL

Base URL 是 OpenClaw 发送模型请求的目标地址。

本文统一配置使用：

https://genvis.xyz/v1

注意末尾的 /v1 不要遗漏，也不要写成控制台首页地址。

3. 模型引用

OpenClaw 现在使用下面的格式引用模型：

provider/model

例如：

genvis/gpt-5.6-sol

其中 genvis 是 Provider 名称，gpt-5.6-sol 才是提交给兼容接口的模型 ID。

很多 Model not found 或 Model is not allowed 报错，根源就是把 Provider 名称和模型 ID 混在了一起。

二、两种接入方式怎么选

接入方式 优点 不足 更适合谁
分别使用官方 API 原生能力完整，链路直接 多个平台、多个 Key，支付和网络环境不同 已经拥有各家官方账号的用户
使用统一兼容接口 一个 Key、一套地址，切换模型方便 需要关注兼容性、线路质量和计费规则 需要同时使用国内外模型的用户

如果你只使用 DeepSeek 或 Qwen，没有必要为了“统一”再增加一层。

如果你经常在 GPT、Claude、Gemini 和国产模型之间切换，统一 Provider 会明显省事。本文后面的完整配置就采用这种方式。

这里也提前说明：Genvis 不是 OpenClaw 的必选项。任何兼容 OpenAI 请求格式、能够返回对应模型的服务都可以采用相同方法；只需要替换 Base URL、API Key 和模型 ID。

三、检查 OpenClaw 环境

OpenClaw 当前推荐使用 Node.js 24，也支持符合要求的 Node.js 22 版本。先检查本机环境：

node -v
npm -v
openclaw --version

如果还没有安装 OpenClaw，可以执行：

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

然后检查 Gateway：

openclaw gateway status

只要 OpenClaw 能正常启动，就可以继续配置模型，不需要重新安装整个项目。

四、先查询接口实际支持的模型

不要直接从其他教程复制模型名称。

同一个模型在不同平台上可能使用不同 ID。例如，页面上显示的是产品名称，API 请求需要的却是另一个字符串。最稳妥的方法，是先调用兼容接口的模型列表。

把下面的 sk-你的API密钥 换成自己创建的 Key：

curl https://genvis.xyz/v1/models \
  -H "Authorization: Bearer sk-你的API密钥"

Windows PowerShell 可以使用：

$headers = @{ Authorization = "Bearer sk-你的API密钥" }
Invoke-RestMethod -Uri "https://genvis.xyz/v1/models" -Headers $headers

返回结果里每一项的 id，才是后面应该填写的模型 ID。

例如可能看到：

{
  "data": [
    { "id": "gpt-5.6-sol" },
    { "id": "claude-fable-5" },
    { "id": "gemini-3.1-pro-preview" },
    { "id": "deepseek-v4-flash" },
    { "id": "qwen3.5-plus" }
  ]
}

以上名称仅用于演示配置结构。实际使用时，以你请求 /v1/models 获得的结果为准，不存在的模型不要写入配置。

五、安全保存 API Key

不建议把真实 Key 直接写进公开截图、文章或代码仓库。

OpenClaw 会读取全局环境文件：

~/.openclaw/.env

Windows 对应用户目录下的：

%USERPROFILE%\.openclaw\.env

在文件中加入：

GENVIS_API_KEY=sk-替换成你自己的密钥

后面的配置通过 ${GENVIS_API_KEY} 引用它。这样分享 openclaw.json 时，不会顺手把密钥也发出去。

建议为 OpenClaw 单独创建一个 Key，并设置合理的额度或使用限制。即使密钥意外泄露，也能控制损失范围。

六、注册统一模型 Provider

下面是本文的核心步骤。

先执行 --dry-run，只校验，不写入配置：

openclaw config set models.providers.genvis '{
  "baseUrl": "https://genvis.xyz/v1",
  "apiKey": "${GENVIS_API_KEY}",
  "api": "openai-completions",
  "models": [
    {
      "id": "gpt-5.6-sol",
      "name": "GPT 5.6 Sol",
      "input": ["text"],
      "contextWindow": 200000,
      "maxTokens": 8192
    },
    {
      "id": "claude-fable-5",
      "name": "Claude Fable 5",
      "input": ["text"],
      "contextWindow": 200000,
      "maxTokens": 8192
    },
    {
      "id": "gemini-3.1-pro-preview",
      "name": "Gemini 3.1 Pro",
      "input": ["text"],
      "contextWindow": 200000,
      "maxTokens": 8192
    },
    {
      "id": "deepseek-v4-flash",
      "name": "DeepSeek V4 Flash",
      "input": ["text"],
      "contextWindow": 128000,
      "maxTokens": 8192
    },
    {
      "id": "qwen3.5-plus",
      "name": "Qwen 3.5 Plus",
      "input": ["text"],
      "contextWindow": 128000,
      "maxTokens": 8192
    }
  ]
}' --strict-json --dry-run

看到校验通过后，删除最后的 --dry-run 再执行一次，正式写入：

openclaw config set models.providers.genvis '{
  "baseUrl": "https://genvis.xyz/v1",
  "apiKey": "${GENVIS_API_KEY}",
  "api": "openai-completions",
  "models": [
    { "id": "gpt-5.6-sol", "name": "GPT 5.6 Sol", "input": ["text"], "contextWindow": 200000, "maxTokens": 8192 },
    { "id": "claude-fable-5", "name": "Claude Fable 5", "input": ["text"], "contextWindow": 200000, "maxTokens": 8192 },
    { "id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro", "input": ["text"], "contextWindow": 200000, "maxTokens": 8192 },
    { "id": "deepseek-v4-flash", "name": "DeepSeek V4 Flash", "input": ["text"], "contextWindow": 128000, "maxTokens": 8192 },
    { "id": "qwen3.5-plus", "name": "Qwen 3.5 Plus", "input": ["text"], "contextWindow": 128000, "maxTokens": 8192 }
  ]
}' --strict-json

这里有四个关键字段：

  • baseUrl：统一接口地址，末尾保留 /v1；

  • apiKey：从环境变量读取，不把密钥明文写入配置；

  • api：OpenAI 兼容聊天接口使用 openai-completions；

  • models：把接口实际开放的模型注册进 OpenClaw。

如果你的返回列表没有某个示例模型，请先从 models 数组中删除它。模型 ID 必须完全一致，大小写、连字符和版本后缀都不能想当然地修改。

七、验证配置并设置默认模型

先验证配置文件结构：

openclaw config validate

然后重启 Gateway：

openclaw gateway restart

查看 OpenClaw 已识别的 Genvis 模型：

openclaw models list --provider genvis

设置默认模型：

openclaw models set genvis/gpt-5.6-sol

查看当前状态：

openclaw models status

如果要进行真实连通性测试，可以先停止 Gateway，再执行探测：

openclaw gateway stop
openclaw models status --probe --probe-provider genvis
openclaw gateway start

--probe 会真实调用模型，可能消耗少量 Token，也可能触发频率限制。它不是单纯读取本地配置，因此不建议无意义地连续执行。

八、在 GPT、Claude、Gemini 与国产模型之间切换

配置完成后，换模型不再需要修改 Base URL 和 Key，只修改默认模型即可。

切换到 Claude：

openclaw models set genvis/claude-fable-5

切换到 Gemini：

openclaw models set genvis/gemini-3.1-pro-preview

切换到 DeepSeek：

openclaw models set genvis/deepseek-v4-flash

切换到 Qwen：

openclaw models set genvis/qwen3.5-plus

再次强调：上面的模型 ID 必须替换成接口实际返回的 ID。

一个比较实用的分工方式是：

任务 模型选择思路
复杂规划、代码重构 优先选择能力更强的 GPT 或 Claude
长文档理解、多模态任务 根据实测选择 Gemini 或支持图像输入的模型
高频整理、批量摘要 使用成本更低、响应更快的模型
中文写作、信息抽取 可以优先测试 DeepSeek、Qwen、GLM、Kimi
定时心跳、简单分类 不要默认使用最贵的旗舰模型

模型越贵并不代表所有任务都更合适。对于持续运行的 Agent，合理分工通常比“一律使用最强模型”更重要。

九、五个最常见的报错

1. 401 Unauthorized 或 Invalid API Key

优先检查：

openclaw config validate
openclaw models status

常见原因：

  • .env 文件路径放错；

  • 环境变量名称不是 GENVIS_API_KEY；

  • Key 前后带了空格；

  • Gateway 在写入环境变量前已经启动，需要重启；

  • Key 已被删除、禁用或没有可用额度。

2. 404 Model Not Found

通常不是 OpenClaw 坏了，而是模型 ID 不匹配。

重新请求：

curl https://genvis.xyz/v1/models \
  -H "Authorization: Bearer sk-你的API密钥"

把返回的 id 原样写入 models。不要把网页展示名称当成 API 模型 ID。

3. Model is not allowed

先确认模型是否真的注册：

openclaw models list --provider genvis

如果你另外配置了模型允许列表，还要检查该模型是否被限制。模型引用必须包含 Provider 前缀：

genvis/模型ID

4. 配置成功，但修改没有生效

依次执行：

openclaw config validate
openclaw gateway restart
openclaw models status

不要同时修改多个配置文件。可以通过下面的命令确认 OpenClaw 当前实际读取的是哪一个文件：

openclaw config file

5. 对话正常，但工具调用失败

“兼容 OpenAI 对话格式”不等于所有高级能力都百分之百一致。

不同模型在线路转换后，可能在工具调用、流式输出、思考内容、多模态输入或 Prompt Cache 上存在差异。排查时建议：

  1. 先用一句普通对话验证基础连接；

  2. 再测试一个参数简单的工具；

  3. 最后测试浏览器、文件和多步工作流；

  4. 如果仅某个模型失败，换另一个模型对比；

  5. 不要在基础对话都没跑通时，同时排查 Skills 和 Gateway。

十、怎样配置更稳、更省 Token

1. 给 OpenClaw 使用独立 Key

不要让个人脚本、测试项目和长期运行的 Agent 共用一个 Key。独立 Key 更方便统计、限额和停用。

2. 先用小任务验证

第一次接入时，先测试普通对话、简单文件读取和一次工具调用。不要一开始就运行长时间定时任务。

3. 简单任务使用经济模型

定时检查、分类、格式转换、标题生成等任务，没有必要一直调用旗舰模型。

4. 控制会话长度

OpenClaw 会在持续任务中携带上下文。会话越长，每轮重复发送的输入 Token 可能越多。任务已经结束时，应及时开启新会话，而不是无限累积历史记录。

5. 不要只看模型数量

选择兼容接口时，真正值得关注的是：

  • 目标模型是否真实可用；

  • 晚高峰的请求成功率；

  • 首字响应时间和长输出稳定性；

  • 工具调用是否兼容；

  • 计费记录是否透明；

  • 出现问题后是否能快速定位。

“支持几百个模型”听起来很热闹，但日常真正会用到的通常只有几个。

十一、完整自检清单

配置完成后，可以逐项确认：

  • Node.js 和 OpenClaw 版本符合要求；

  • Gateway 可以正常启动；

  • Base URL 以 /v1 结尾；

  • API Key 存放在全局 .env，没有提交到代码仓库；

  • /v1/models 能返回模型列表；

  • 配置中的模型 ID 与返回值完全一致；

  • openclaw config validate 通过；

  • openclaw models list --provider genvis 能看到模型；

  • 默认模型使用 genvis/模型ID 格式；

  • 普通对话和工具调用分别测试成功；

  • 已给 Key 设置合理额度，并能查看使用记录。

总结

OpenClaw 本身并不限制你只能使用某一家模型。真正决定接入体验的，是 Provider、Base URL、API Key 和模型 ID 是否配置正确。

如果已经拥有各家官方账号，分别使用官方 API 能获得更直接的原生能力；如果需要频繁切换 GPT、Claude、Gemini、DeepSeek 和 Qwen，可以把 OpenAI 兼容接口注册成统一 Provider。

本文使用的核心配置只有两项：

Provider：genvis
Base URL：https://genvis.xyz/v1

完成一次注册以后，后续换模型只需要：

openclaw models set genvis/模型ID

建议第一次只创建小额、独立的 API Key，按照“查询模型列表 → 校验配置 → 普通对话 → 工具调用”的顺序逐步测试。能稳定完成真实任务，比单纯把模型名称堆满配置文件更重要。

# linux # 运维 # 服务器 # 人工智能
Logo
智能体开发者社区

中国智能体开发者社区，聚焦智能体与大模型开发，提供前沿资讯、实用工具链、开源项目及行业案例。通过技术沙龙、开发者大赛等活动，促进经验交流与协作，助力开发者快速构建创新智能应用。

更多推荐

MCP协议开发实战：从零搭建AI Agent工具链

创建静态资源（如项目 README 文件）。创建动态资源（如实时系统状态）。在 Client 中请求并利用资源上下文。回顾 MCP 协议如何降低 AI Agent 开发门槛。当前生态的局限与未来的演进方向。鼓励读者基于此大纲进行实践，并参与开源贡献。

avatar 智能体开发者社区

AI Agent可观测性：破解多步推理黑盒

随着AI Agent在复杂任务中承担越来越多的决策角色，其内部的多步推理过程往往如同一个“黑盒”，难以理解、调试和信任。本文旨在探讨AI Agent可观测性（Observability）的核心概念、技术挑战与实践方案，为开发者提供一套系统的方法论和工具链，以“照亮”Agent的推理黑盒，实现对其行为、决策逻辑与内部状态的全面洞察。构建AI Agent的可观测性体系不再是“锦上添花”，而是保障其在大

avatar 智能体开发者社区

MCP协议开发实战：从零搭建AI Agent工具链

回顾：我们从协议概念到动手搭建了一个可用的MCP工具链。MCP的生态现状：官方与社区提供的Server示例（GitHub, Jira, Notion等）。未来方向：更复杂的工具编排、多模型协作、可视化工具开发平台。鼓励动手：鼓励读者基于此框架，开发解决自己实际问题的工具。

avatar 智能体开发者社区