OpenClaw的模型和渠道详解

下面把OpenClaw 的“模型”和“渠道”合起来讲。这里“渠道”可能有两层含义：一是模型提供商渠道，比如 OpenAI、Anthropic、Gemini、OpenRouter、Ollama；二是消息渠道，比如 WhatsApp、Telegram、Discord、Slack。OpenClaw 里这两套东西都经过 Gateway 协调。

1. 总体关系

可以先用这张图理解：

WhatsApp / Telegram / Slack / Discord / WebChat │ ▼ OpenClaw Gateway │ ┌───────┴────────┐ ▼ ▼ Agent 路由 会话 / 权限 / 工具 │ ▼ 模型选择器 │ ▼ OpenAI / Anthropic / Gemini / OpenRouter / Ollama / 其他 provider

消息渠道决定“用户从哪里进来、回复发回哪里”。
模型渠道 / 模型提供商决定“这次 Agent 用哪个大模型思考和调用工具”。

OpenClaw 官方文档中，聊天渠道是通过 Gateway 连接的，所有渠道都支持文本，但媒体和表情回应因渠道而异。([OpenClaw][1]) 模型则使用provider/model格式，例如openai/gpt-5.5、anthropic/claude-opus-4-6、google/gemini-3.1-pro-preview。([OpenClaw][2])

一、模型体系详解

2. 模型引用格式：provider/model

OpenClaw 的模型引用通常是：

provider/model

例如：

openai/gpt-5.5 anthropic/claude-opus-4-6 google/gemini-3.1-pro-preview zai/glm-5 openrouter/moonshotai/kimi-k2 opencode/claude-opus-4-6

官方说明模型引用使用provider/model格式；如果设置了agents.defaults.models，它会成为模型允许列表。([OpenClaw][2])

配置示例：

{agents:{defaults:{model:{primary:"openai/gpt-5.5",fallbacks:["anthropic/claude-opus-4-6","google/gemini-3.1-pro-preview"]}}}}

含义是：默认先用 OpenAI 的主模型；失败、限流或触发 fallback 逻辑后，再尝试 Anthropic、Gemini。

3. 模型选择顺序

OpenClaw 的模型选择大致按这个顺序：

1. agents.defaults.model.primary 2. agents.defaults.model.fallbacks 3. provider 内部认证/密钥故障转移 4. 会话级 /model 覆盖 5. Agent 级 model 覆盖 6. Cron 或任务级 model 覆盖

官方模型文档列出的核心顺序是：先用主模型agents.defaults.model.primary，再按agents.defaults.model.fallbacks使用回退模型，最后在单个 provider 内部做凭证故障转移；每个智能体也可以通过agents.list[].model覆盖默认模型。([OpenClaw][3])

典型配置：

{agents:{defaults:{model:{primary:"anthropic/claude-opus-4-6",fallbacks:["openai/gpt-5.5","google/gemini-3.1-pro-preview"]}},list:[{id:"coding",model:{primary:"openai/gpt-5.5",fallbacks:["anthropic/claude-opus-4-6"]}},{id:"chat",model:{primary:"google/gemini-3-flash-preview"}}]}}

这样：

coding agent → 用更强的代码模型 chat agent → 用更便宜/更快的聊天模型 默认 agent → 用全局默认模型

4. 常见模型提供商

OpenAI

常见模型引用：

openai/gpt-5.5 openai/gpt-5.4-mini

认证方式通常是：

exportOPENAI_API_KEY=...

或通过：

openclaw onboard --auth-choice openai-api-key

OpenAI provider 支持 WebSocket 优先、SSE 回退的auto传输，也可以按模型在agents.defaults.models["openai/<model>"].params.transport中覆盖为"sse"、"websocket"或"auto"。([OpenClaw][2])

Anthropic

常见模型引用：

anthropic/claude-opus-4-6

认证变量：

exportANTHROPIC_API_KEY=...

官方文档列出的 Anthropic provider ID 是anthropic，认证变量是ANTHROPIC_API_KEY，也支持多 key 轮换变量，例如ANTHROPIC_API_KEYS、ANTHROPIC_API_KEY_1、ANTHROPIC_API_KEY_2。([OpenClaw][2])

配置：

{agents:{defaults:{model:{primary:"anthropic/claude-opus-4-6"}}}}

OpenAI Codex OAuth

如果你走 OpenAI Codex / ChatGPT OAuth 路线，provider 是：

openai-codex

模型示例：

openai-codex/gpt-5.4

登录命令：

openclaw onboard --auth-choice openai-codex# 或openclaw models auth login--provideropenai-codex

官方说明 OpenAI Code / Codex provider 使用 OAuth，并且默认传输也是auto，即 WebSocket 优先、SSE 回退。([OpenClaw][2])

Google Gemini

常见模型引用：

google/gemini-3.1-pro-preview google/gemini-3-flash-preview

认证变量：

exportGEMINI_API_KEY=...

官方文档列出的 provider 是google，认证变量是GEMINI_API_KEY，也支持GEMINI_API_KEYS、GEMINI_API_KEY_1、GEMINI_API_KEY_2、GOOGLE_API_KEY等回退变量。([OpenClaw][2])

配置：

{agents:{defaults:{model:{primary:"google/gemini-3.1-pro-preview",fallbacks:["google/gemini-3-flash-preview"]}}}}

Z.AI / GLM

常见模型引用：

zai/glm-5

认证变量：

exportZAI_API_KEY=...

官方说明 Z.AI provider ID 是zai，示例模型是zai/glm-5，并且z.ai/*、z-ai/*会标准化为zai/*。([OpenClaw][2])

Vercel AI Gateway

如果你希望通过 Vercel AI Gateway 聚合模型，可以使用：

vercel-ai-gateway/anthropic/claude-opus-4.6

认证变量：

exportAI_GATEWAY_API_KEY=...

官方文档列出的 provider 是vercel-ai-gateway，认证变量是AI_GATEWAY_API_KEY。([OpenClaw][2])

5. 模型 allowlist：限制可用模型

如果你设置了：

{agents:{defaults:{models:{"openai/gpt-5.5":{},"anthropic/claude-opus-4-6":{},"google/gemini-3-flash-preview":{}}}}}

那么这就变成允许列表。用户通过/model或 UI 切模型时，只能选这些模型。官方文档说明，如果设置了agents.defaults.models，它会成为/model和会话覆盖的允许列表；用户选择不在列表里的模型时，会返回Model "provider/model" is not allowed。([OpenClaw][3])

这在多用户、多渠道场景里很重要：

公开 Telegram bot → 只允许便宜模型 内部 Slack bot → 允许强模型 代码 Agent → 允许工具能力强的模型

6. 模型 CLI 常用命令

常用命令：

openclaw models status openclaw models list openclaw modelssetopenai/gpt-5.5 openclaw models scan

官方 CLI 文档说明，openclaw models status会显示默认模型、fallback 和认证概览；models set接受provider/model或别名；models list用于列出模型。([OpenClaw][4])

更多命令：

# 查看当前模型状态openclaw models status# 查看所有已配置模型openclaw models list# 查看完整模型目录openclaw models list--all# 只看某个 provideropenclaw models list--provideropenai# 设置默认模型openclaw modelssetanthropic/claude-opus-4-6# 查看 fallbackopenclaw models fallbacks list# 添加 fallbackopenclaw models fallbacksaddgoogle/gemini-3-flash-preview# 清空 fallbackopenclaw models fallbacksclear# 实时探测认证openclaw models status--probe

注意：--probe会发真实请求，可能消耗 token 或触发 rate limit；官方 CLI 文档也提醒探测是真实请求。([OpenClaw][4])

7. 不同媒体模型：文本、图片、视频、音乐

OpenClaw 不只区分聊天模型，还可以配置图片、PDF、视频、音乐等模型：

{agents:{defaults:{model:{primary:"openai/gpt-5.5"},imageGenerationModel:{primary:"openai/gpt-image-2",fallbacks:["google/gemini-3.1-flash-image-preview"]},videoGenerationModel:{primary:"some-provider/video-model"},musicGenerationModel:{primary:"some-provider/music-model"}}}}

官方模型文档列出的相关配置键包括agents.defaults.imageGenerationModel.primary、agents.defaults.videoGenerationModel.primary、agents.defaults.musicGenerationModel.primary，并说明如果省略，生成工具会尝试推断一个有凭证支持的 provider 默认值。([OpenClaw][3])

二、消息渠道 Channel 详解

8. 支持的消息渠道

OpenClaw 的消息渠道是用户和 Agent 对话的入口。官方列出的渠道包括：

BlueBubbles / Discord / Feishu / Google Chat / iMessage IRC / LINE / Matrix / Mattermost / Microsoft Teams Nextcloud Talk / Nostr / QQ Bot / Signal / Slack Synology Chat / Telegram / Twitch / WhatsApp / Zalo

官方聊天渠道页说明，每个渠道都通过 Gateway 连接，文本在所有渠道都支持；Discord 支持服务器、频道和私信，Slack 使用 Bolt SDK，Telegram 使用 grammY Bot API，WhatsApp 使用对应渠道插件/运行时。([OpenClaw][1])

常见选择：

9. 渠道配置的基本结构

一个典型配置：

{channels:{telegram:{botToken:"env:TELEGRAM_BOT_TOKEN",allowFrom:["123456789"]},whatsapp:{allowFrom:["+15555550123"]},slack:{botToken:"env:SLACK_BOT_TOKEN",appToken:"env:SLACK_APP_TOKEN",signingSecret:"env:SLACK_SIGNING_SECRET"}}}

安全上，通常要设置：

allowFrom 允许哪些用户 allowGroups 允许哪些群 dmPolicy 私信策略 groupPolicy 群组策略 mention 群里是否必须 @ 机器人 pairing 是否需要配对批准

10. 渠道路由：消息进来后给哪个 Agent

OpenClaw 不一定只有一个 Agent。你可以定义多个 Agent，然后用bindings把不同渠道、账号、群、线程路由到不同 Agent。

官方渠道路由文档说明关键术语包括：channel、accountId、AgentId、SessionKey；支持的渠道名包括telegram、whatsapp、discord、irc、googlechat、slack、signal、imessage、line以及扩展渠道。([OpenClaw][5])

示例：

{agents:{list:[{id:"personal",name:"Personal Assistant",workspace:"~/.openclaw/workspace-personal",model:{primary:"google/gemini-3-flash-preview"}},{id:"work",name:"Work Assistant",workspace:"~/.openclaw/workspace-work",model:{primary:"anthropic/claude-opus-4-6"}},{id:"support",name:"Support Bot",workspace:"~/.openclaw/workspace-support",model:{primary:"openai/gpt-5.4-mini"}}]},bindings:[{match:{channel:"telegram",peer:{kind:"user",id:"123456789"}},agentId:"personal"},{match:{channel:"slack",teamId:"T123"},agentId:"work"},{match:{channel:"discord",guildId:"987654321"},agentId:"support"}]}

含义：

Telegram 私聊 → personal agent → Gemini Slack 工作区 → work agent → Claude Discord 服务器 → support agent → OpenAI mini

这就是 OpenClaw “渠道 → Agent → 模型” 的典型路由链。

11. 会话 SessionKey：不同渠道怎么共享上下文

OpenClaw 会为不同来源生成不同 session key。官方文档说明，默认情况下私信可以折叠到智能体的 main 会话；群组和频道会按渠道保持隔离；Slack/Discord 线程会追加:thread:<threadId>，Telegram 论坛话题会嵌入:topic:<topicId>。([OpenClaw][5])

大致是：

私聊： agent:<agentId>:main Telegram 群： agent:<agentId>:telegram:group:<groupId> Discord 频道： agent:<agentId>:discord:channel:<channelId> Slack/Discord 线程： agent:<agentId>:discord:channel:<channelId>:thread:<threadId> Telegram 话题： agent:<agentId>:telegram:group:<groupId>:topic:<topicId>

这很重要，因为它决定：

上下文是否共享 工具权限如何派生 并发如何控制 回复应该发回哪里

12. 渠道默认账号 defaultAccount

多账号场景下，一个渠道可以有多个账号实例。例如多个 Telegram bot、多个 WhatsApp 账号、多个 Slack workspace。官方文档说明channels.<channel>.defaultAccount用于在出站路径没指定accountId时选择默认账号；如果一个渠道配置了两个或更多账号，建议显式设置默认值，否则回退路由可能选择第一个标准化后的账号 ID。([OpenClaw][5])

示例：

{channels:{telegram:{defaultAccount:"main-bot",accounts:{"main-bot":{botToken:"env:TELEGRAM_MAIN_BOT_TOKEN"},"support-bot":{botToken:"env:TELEGRAM_SUPPORT_BOT_TOKEN"}}}}}

13. 渠道模型覆盖：不同渠道用不同模型

OpenClaw 支持用渠道来影响模型选择。配置参考里提到，channels.modelByChannel可以把特定渠道 ID 固定到某个模型；值可以是provider/model或已配置模型别名；当某个会话尚未有模型覆盖时，会应用这个渠道映射。([OpenClaw][6])

示例：

{channels:{modelByChannel:{telegram:"google/gemini-3-flash-preview",slack:"anthropic/claude-opus-4-6",discord:"openai/gpt-5.4-mini",whatsapp:"openai/gpt-5.5"}}}

这适合做成本控制：

Telegram 日常聊天 → 便宜快速模型 Slack 工作任务 → 强模型 Discord 社群问答 → mini 模型 WhatsApp 私人助手 → 主力模型

不过更推荐的可维护方式通常是：用 bindings 路由到不同 agent，然后每个 agent 配自己的 model。这样不只模型不同，workspace、tools、skills、安全策略也可以不同。

三、模型渠道与消息渠道如何组合

14. 三层路由模型

OpenClaw 的完整路由可以理解成三层：

第一层：消息渠道路由 Telegram / Slack / WhatsApp / Discord ↓ 第二层：Agent 路由 personal / work / support / coding ↓ 第三层：模型路由 openai / anthropic / google / openrouter / local

配置示例：

{agents:{list:[{id:"personal",workspace:"~/.openclaw/personal",model:{primary:"google/gemini-3-flash-preview",fallbacks:["openai/gpt-5.4-mini"]},tools:{profile:"messaging"}},{id:"work",workspace:"~/.openclaw/work",model:{primary:"anthropic/claude-opus-4-6",fallbacks:["openai/gpt-5.5"]},tools:{profile:"coding"}}]},channels:{telegram:{botToken:"env:TELEGRAM_BOT_TOKEN",allowFrom:["123456789"]},slack:{botToken:"env:SLACK_BOT_TOKEN",appToken:"env:SLACK_APP_TOKEN",signingSecret:"env:SLACK_SIGNING_SECRET"}},bindings:[{match:{channel:"telegram"},agentId:"personal"},{match:{channel:"slack"},agentId:"work"}]}

这样比单纯channels.modelByChannel更强，因为它同时隔离了：

模型 工作区 会话 工具权限 skills 文件系统 上下文

15. 推荐部署模式

个人助理

{agents:{defaults:{model:{primary:"openai/gpt-5.5",fallbacks:["google/gemini-3-flash-preview"]}}},channels:{whatsapp:{allowFrom:["+15555550123"]},telegram:{botToken:"env:TELEGRAM_BOT_TOKEN",allowFrom:["123456789"]}}}

适合：

WhatsApp / Telegram 里随时问自己的私人 Agent

团队工作机器人

{agents:{list:[{id:"team",workspace:"~/.openclaw/team",model:{primary:"anthropic/claude-opus-4-6",fallbacks:["openai/gpt-5.5"]},tools:{profile:"coding",deny:["exec"]}}]},channels:{slack:{botToken:"env:SLACK_BOT_TOKEN",appToken:"env:SLACK_APP_TOKEN",signingSecret:"env:SLACK_SIGNING_SECRET"}},bindings:[{match:{channel:"slack",teamId:"T123"},agentId:"team"}]}

适合：

Slack 内部问答、代码解释、文档搜索、轻量任务自动化

成本分层

{agents:{list:[{id:"cheap-chat",model:{primary:"google/gemini-3-flash-preview"}},{id:"hard-work",model:{primary:"anthropic/claude-opus-4-6",fallbacks:["openai/gpt-5.5"]}}]},bindings:[{match:{channel:"telegram"},agentId:"cheap-chat"},{match:{channel:"slack"},agentId:"hard-work"}]}

适合：

低风险渠道用便宜模型 高价值工作渠道用强模型

16. 常见问题

Q1：模型会自己决定回复到哪个渠道吗？

不会。模型不负责选择渠道。渠道路由由 Gateway 和配置决定。官方渠道路由文档说明，OpenClaw 会把回复路由回消息来源，路由是确定性的，由主机配置控制。([OpenClaw][7])

Q2：同一个 WhatsApp 可以用不同模型吗？

可以。推荐做法是把不同联系人、群组或账号用bindings路由到不同 agent；每个 agent 配不同模型。也可以用channels.modelByChannel做渠道级模型覆盖。

Q3：用户能临时切模型吗？

可以，通过/model。官方文档说明/model会持久化新的会话选择；如果 agent 空闲，下一次运行会使用新模型；如果当前运行已开始，则可能排队到干净重试点或下一轮。([OpenClaw][3])

Q4：为什么设置了模型但没有回复？

常见原因：

1. 模型不在 agents.defaults.models 允许列表里 2. provider 没有配置 API key / OAuth 3. 模型 ID 写错 4. 当前会话固定了一个不可用模型 5. fallback 也不可用 6. 渠道 allowlist / pairing 拦截了消息

可以先跑：

openclaw models status openclaw models status--probeopenclaw models list openclaw channels status--probeopenclaw logs--follow

models status会显示默认模型、fallback 和认证概览；加--probe可以做实时认证探测。([OpenClaw][4])

17. 总结

OpenClaw 的模型和渠道可以这样理解：

消息渠道 Channel = 用户在哪里跟 Agent 说话 = WhatsApp / Telegram / Slack / Discord / WebChat 模型提供商 Provider = Agent 用哪个大模型思考 = OpenAI / Anthropic / Gemini / Z.AI / OpenRouter / Ollama Agent = 中间的“人格 + 工作区 + 工具 + skills + 模型配置” Gateway = 把渠道、Agent、模型、工具、会话全部串起来的中枢

最推荐的设计方式是：

不要只按渠道硬切模型； 而是按渠道/账号/群组 → 路由到不同 Agent → 每个 Agent 配自己的模型、工具和 skills。

这样结构更清晰，也更安全。

参考链接：
[1]: https://docs.openclaw.ai/zh-CN/channels “聊天渠道 - OpenClaw”
[2]: https://docs.openclaw.ai/zh-CN/concepts/model-providers “模型提供商 - OpenClaw”
[3]: https://docs.openclaw.ai/zh-CN/concepts/models “模型 CLI - OpenClaw”
[4]: https://docs.openclaw.ai/zh-CN/cli/models “models - OpenClaw”
[5]: https://docs.openclaw.ai/zh-CN/channels/channel-routing “渠道路由 - OpenClaw”
[6]: https://docs.openclaw.ai/zh-CN/gateway/configuration-reference?utm_source=chatgpt.com “配置参考 - OpenClaw”
[7]: https://docs.openclaw.ai/zh-CN/channels/channel-routing?utm_source=chatgpt.com “渠道路由 - OpenClaw”