OpenClaw的模型和渠道详解

code_pgf

539人浏览 · 2026-05-09 15:27:51

code_pgf · 2026-05-09 15:27:51 发布

下面把 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

认证方式通常是：

export OPENAI_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

认证变量：

export ANTHROPIC_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 --provider openai-codex

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

Google Gemini

常见模型引用：

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

认证变量：

export GEMINI_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

认证变量：

export ZAI_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

认证变量：

export AI_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 models set openai/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

# 只看某个 provider
openclaw models list --provider openai

# 设置默认模型
openclaw models set anthropic/claude-opus-4-6

# 查看 fallback
openclaw models fallbacks list

# 添加 fallback
openclaw models fallbacks add google/gemini-3-flash-preview

# 清空 fallback
openclaw models fallbacks clear

# 实时探测认证
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])

常见选择：

渠道	适合场景
Telegram	最快上手，Bot Token 即可
WhatsApp	日常个人助理，移动端体验好
Slack	团队/工作区机器人
Discord	社群、频道、线程
iMessage / BlueBubbles	Apple 生态
Matrix / Mattermost / Nextcloud Talk	自托管聊天
Signal	隐私取向
WebChat	Gateway 自带 Web UI 聊天入口

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 --probe
openclaw models list
openclaw channels status --probe
openclaw 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”

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

AI Coding 个人知识库工具深度对比分析

本文对比分析了三款AI知识管理工具：Claude-Obsidian、CodeGraph和Understand-Anything。Claude-Obsidian是基于Obsidian的知识管理Wiki引擎，通过LLM提取实体概念并构建知识库；CodeGraph是为AI Agent设计的代码语义索引图，采用SQLite数据库存储代码知识图谱；Understand-Anything则是多Agent协作的