OpenClaw Gateway 配置完全指南：从入门到精通

装好OpenClaw只是第一步，真正决定使用体验的是配置。配置调得好，AI助手响应快、渠道稳定、安全可控；配置乱来，轻则功能异常，重则信息泄露。网上关于OpenClaw配置的教程要么太浅（只讲开关Telegram），要么太散（东一块西一块），今天这篇把它系统化讲清楚——从文件结构到每个关键参数，从入门操作到高级安全技巧，保证你看完能独立完成任意复杂度的配置。

配置文件的位置和格式

OpenClaw的配置文件位于~/.openclaw/openclaw.json。~在类Unix系统里代表用户目录，Windows上则对应C:\Users\你的用户名\。整个配置文件采用JSON5格式——这是JSON的超集，允许在文件里写注释、写尾逗号、单引号字符串等等。为什么要用JSON5而不是纯JSON？因为配置文件需要注释来解释每项配置的用途，纯JSON做不到这一点。

你可以用任意文本编辑器打开这个文件：VS Code、Sublime Text、vim、nano都可以。推荐用VS Code，因为它对JSON5有良好的语法高亮和自动补全支持。

首次安装完成后，这个文件会自动生成，包含一些基础配置项。随着你添加技能、连接频道，文件内容会越来越丰富。

三种配置编辑方式对比

OpenClaw提供了三种编辑配置文件的方式，各有适用场景。

方式一：交互式向导

适合第一次配置或者不熟悉命令行的人。运行：

openclaw onboard

这个向导会以问答形式引导你完成配置，每一步都有清晰的说明。你不需要知道JSON长什么样，只需要回答"要不要连接Telegram？““Bot Token是什么？“这类问题，向导会自动更新配置文件。

缺点是效率低——如果你已经明确知道自己要改什么参数，用向导就显得很绕。

方式二：CLI命令（最高效的方式）

OpenClaw提供了一套config子命令，专门用来读写配置项。这是最推荐的方式，尤其适合自动化脚本和CI/CD场景。

# 查看当前配置（全部或指定key）
openclaw config get
openclaw config get channels.telegram

# 设置配置项
openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.bot-token "123456:ABC-DEF"

# 删除配置项
openclaw config unset channels.telegram.bot-token

config get特别有用——不跟参数时输出完整配置树，跟了参数则输出对应子项。配置项用点号分隔层级，如channels.telegram.bot-token代表channels.telegram下面的bot-token。

方式三：直接编辑文件

适合批量修改、搜索替换、或者需要写注释说明的场景。直接用文本编辑器打开~/.openclaw/openclaw.json即可。编辑完成后，OpenClaw会自动检测文件变化并重新加载配置，无需手动重启网关。

但直接编辑有一点必须注意：Strict Validation。

Strict Validation：配置错了网关会拒绝启动

OpenClaw在启动时会验证配置文件的完整性。如果检测到无效值、缺失必填项或者格式错误，网关会拒绝启动，而不是带着错误配置勉强跑起来。这个设计看似严格，实际上是在保护你——想象一下，如果你配错了Telegram Bot Token但网关照样启动，你以为一切正常，结果Bot永远收不到消息，排错都不知道从哪下手。

Strict Validation会检查的内容包括但不限于：

-必填字段是否存在（如gateway.port）

字段类型是否正确（如布尔值不能写成字符串）
枚举值是否在允许范围内（如gateway.bind只能是loopback/lan/tailnet/auto）
引用完整性（如配置了Telegram频道但没填bot-token）

如果配置有误，openclaw gateway start会报错并列出具体问题。修复后再次启动即可。

这个机制的好处是：开发阶段可以大胆试错，生产环境又绝对不会带着病配置文件跑。建议在改配置前先openclaw gateway status看看当前状态，改完后再启动验证。

频道配置：Telegram、WhatsApp、Discord

频道配置是让OpenClaw接入聊天平台的核心部分。每个频道的配置都以channels.<平台名>为前缀。

Telegram配置示例

{
  "channels": {
    "telegram": {
      "enabled": true,
      "bot-token": "你的bot-token",
      "dmPolicy": "approved",
      "allowed-chats": ["你的chat-id"]
    }
  }
}

关键字段：

enabled：开关，不填或false则不启用
bot-token：在Telegram找@BotFather申请的机器人Token
dmPolicy：控制谁能私聊这个Bot
allowed-chats：白名单，只有这里列出的Chat ID能收到回复

WhatsApp配置

WhatsApp不走Bot Token，走QR码认证：

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "approved"
    }
  }
}

少了bot-token字段，因为WhatsApp没有官方Bot API。第一次启用时需要用openclaw channels whatsapp link命令生成QR码，然后用WhatsApp手机客户端扫描。

Discord配置

Discord使用Application和Bot机制：

{
  "channels": {
    "discord": {
      "enabled": true,
      "bot-token": "你的discord-bot-token",
      "guild-id": "服务器ID",
      "dmPolicy": "approved"
    }
  }
}

Discord的配置稍复杂，需要在Discord开发者平台创建Application、启用机器人、邀请机器人到服务器等步骤。这些步骤本身和OpenClaw无关，但缺少任何一环都会导致Bot无法正常工作。

模型配置：primary和fallbacks

OpenClaw不绑定特定AI模型，你可以同时配置多个模型，主模型出问题自动切换到备选。

{
  "models": {
    "primary": "claude-3-5-sonnet",
    "fallbacks": ["gpt-4o", "gpt-3.5-turbo"],
    "providers": {
      "claude": {
        "type": "anthropic",
        "api-key": "sk-ant-..."
      },
      "openai": {
        "type": "openai",
        "api-key": "sk-..."
      }
    }
  }
}

primary：默认使用的模型标识符
fallbacks：按顺序尝试的备用模型列表，主模型不可用时自动降级
providers：各模型供应商的凭证配置

fallbacks机制很实用。比如你主力用Claude，但Claude接口临时故障时，OpenClaw会自动切到GPT-4o，对用户来说感知不到中断，只是回复的"味道"略有不同。

访问权限控制：dmPolicy详解

dmPolicy（Direct Message Policy）是控制谁可以向AI发送消息的策略，这是最重要的安全配置之一。

三种模式：

open：完全开放，任何人给Bot发消息都会被处理。适合公开群组或服务型Bot。但极度不推荐个人使用——一旦Bot公开在网上，会收到大量垃圾消息，消耗你的API配额。

approved：只有白名单用户可以发消息。白名单通过allowed-chats或allowed-users配置。这个模式是个人使用的最佳选择——只有你自己（或你信任的几个人）能调用AI。

closed：完全关闭私聊响应。无论谁来消息，Bot都不会回复。可以用于群组场景，只在特定群聊里响应。

{
  "channels": {
    "telegram": {
      "dmPolicy": "approved",
      "allowed-chats": ["12345678"]
    }
  }
}

这里有个常见误区：有些用户以为设置了dmPolicy: "closed"就完全安全了——不对，closed只是关闭私聊，在群组里@Bot说话仍然会被处理。如果想在群里也限制响应范围，需要额外配置allowed-chats白名单。

gateway.bind模式：你的AI网关监听在哪里

gateway.bind决定OpenClaw网关监听哪个网络接口。这个参数看似简单，但选错了会导致功能完全不可用。

loopback（默认）：只监听本机回环地址（127.0.0.1或localhost）。其他设备无法访问，只有本机可以使用控制台和API。这个模式最安全，适用于单机使用场景。

lan：监听局域网网卡IP地址。同一Wi-Fi下的其他设备可以通过http://你的机器IP:端口访问OpenClaw。适合家里或办公室内网多设备共用一个AI助手。

tailnet：监听Tailscale网络接口。如果你使用Tailscale组网，这个模式可以让异地设备通过Tailscale的VPN地址访问OpenClaw。适合远程访问场景。

auto：由OpenClaw自动选择最合适的绑定模式。一般会优先loopback，如果没有可用的回环接口才降级到其他模式。

{
  "gateway": {
    "bind": "lan",
    "port": 18789
  }
}

选lan或tailnet时要注意：这意味着你的OpenClaw网关可以被局域网/Tailsneau内的其他设备访问。如果你的API Key有额度限制，建议同时配置访问认证，避免被人蹭用。

openclaw config命令的更多用法

前面已经介绍了get/set/unset，这里补充几个进阶用法：

# 导出完整配置（不含敏感信息）
openclaw config export > backup.json

# 从备份文件导入配置
openclaw config import backup.json

# 重置所有配置到默认状态
openclaw config reset

# 查看配置文件中所有带注释的原始内容
openclaw config edit

openclaw config export导出的文件会脱敏处理（API Key等敏感字段用星号替代），可以直接分享给别人参考结构，不用担心泄露凭证。

实际配置流程演示

假设我要配置一个完整的OpenClaw环境，步骤如下：

第一步：初始化

openclaw onboard --install-daemon

按向导输入API Key，选择默认模型。

第二步：连接Telegram

openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.bot-token "777:AAA"
openclaw config set channels.telegram.dmPolicy "approved"
openclaw config set channels.telegram.allowed-chats '["我的chat-id"]'

第三步：配置模型降级

openclaw config set models.primary "claude-3-5-sonnet-20241022"
openclaw config set models.fallbacks '["gpt-4o"]'

第四步：调整网关绑定模式（假设要在局域网访问）

openclaw config set gateway.bind "lan"

第五步：验证并重启

openclaw gateway restart
openclaw gateway status

整个过程不需要编辑任何文件，全靠CLI命令完成。熟练后改配置就是几秒钟的事。

常见配置错误及处理

配置了Telegram但Bot没反应

检查Bot Token是否正确（前后不能有空格）
确认dmPolicy不是closed
确认Bot已经被你自己在Telegram里发起过对话（ Telegram要求先有过互动才能发消息给用户）

网关启动报JSON格式错误

大概率是手动编辑时引号用了中文引号，或者缺少逗号
用openclaw config edit打开文件，编辑器会标出错误位置

模型配置正确但AI不回复

检查API Key是否有效、额度是否充足
确认models.providers里对应的key类型正确（如Claude要用type: "anthropic"）

安全最佳实践

永远不要把真实API Key明文写在文档或代码里。用环境变量或config set命令录入，OpenClaw内部会加密存储。
个人使用务必用dmPolicy: approved，open模式只适合不需要认证的公共服务Bot。
绑定lan或tailnet时启用访问认证。否则同一个网络的人都能调用你的AI，额度很快会被耗尽。
定期检查配置文件，~/.openclaw/openclaw.json权限设置应为600（只有你自己可读写），避免被其他用户读取。

总结

OpenClaw的配置体系设计得相当优雅：统一的JSON5文件、三种编辑方式、CLI工具顺手好记、Strict Validation兜底安全。搞清楚dmPolicy、bind模式、channels.*和models.*这几个核心概念，你就已经能驾驭OpenClaw的绝大多数使用场景了。剩下的，就是根据自己需求不断微调——配置这条路，没有终点，只有越来越顺手。