参考资料

1. Channel（消息渠道）是 OpenClaw 与外部世界交互的适配器层
2. OpenClaw 安装中最容易踩坑的环节，核心是两件事：准备好兼容的 Node.js LTS 运行时，以及能正确使用基础命令行终端
3. 验证链路：WebChat / Telegram 发送消息 → Gateway 接收 → LLM 回复 → 调用 Skill
4. 启用官方内置 Skill（搜索、文件读取），测试工具调用
5. 掌握 OpenClaw 的 CLI 诊断命令，核心是熟悉一套标准排查流程。
6. 在OpenClaw的扩展体系中，Tools（工具）、Skills（技能） 和Plugins（插件） 是三个分工明确、协同工作的核心概念
7. openclaw.json 是 OpenClaw 的核心配置文件，所有渠道、模型、Agent 行为都通过它来定义
8. Agent 的会话循环（Agent Loop）是 OpenClaw 的执行核心

Gateway 的设计核心是 “多入口 + 单内核” 架构

Gateway（网关）是 OpenClaw 的控制平面（Control Plane），也是整个系统唯一长期运行的核心进程。它像一个总机与调度中心，所有外部消息、内部执行和客户端指令都必须经过它来协调。

🧠 核心定位：系统的“中枢神经”

Gateway 的设计核心是 “多入口 + 单内核” 架构。它不直接进行模型推理或执行工具，而是负责路由、调度和状态管理，将来自不同渠道的请求，分发给正确的 Agent 去处理，再将结果返回给对应的渠道。

📋 核心职责

作为控制平面，Gateway 承担着以下几项关键任务：

• 统一接入与连接管理：Gateway 是唯一与所有消息渠道（如 WhatsApp、Telegram、Discord、Slack、WebChat 等）建立并维护连接的地方。每台主机上只有一个 Gateway，它垄断了与这些外部平台的会话，例如 WhatsApp 的登录会话只能由它开启。

• API 服务与事件广播：它对外暴露统一的 WebSocket (WS) 和 HTTP API。所有客户端（CLI、Web UI、macOS 应用）都通过这个 API 与系统交互。同时，Gateway 会向订阅的客户端广播系统事件，如 agent、chat、health、heartbeat、cron 等。

• 统一鉴权：所有对 Gateway 的访问都需经过鉴权。默认采用 Token 或密码模式，也支持 Tailscale 身份验证或受信任代理模式。鉴权边界统一在 Gateway 层面，确保了访问安全。

• 会话与并发管理：Gateway 负责将入站消息路由到正确的会话（Session）。它通过 sessionKey 将消息“分桶”，确保同一会话的消息串行处理，不同会话则并行执行，避免消息“串线”。

⚙️ 关键配置项

Gateway 的行为主要通过 openclaw.json 中的 gateway 字段进行控制。

配置项	说明	默认值
port	Gateway 监听的端口，WebSocket 与 HTTP 复用此端口。	18789
bind	绑定的网络接口模式。	loopback（仅本机）
auth.mode	鉴权模式。	必须设置（如 token 或 password）
auth.token	鉴权用的共享密钥。	无，默认强制要求
reload.mode	配置文件热重载策略。hybrid 表示安全变更热应用，关键变更则重启。	hybrid

端口的优先级顺序为：命令行 --port > 环境变量 OPENCLAW_GATEWAY_PORT > 配置文件 gateway.port > 默认 18789。

🔗 在系统中的位置

理解 Gateway 的最佳方式，是看它在一次完整请求中的位置。以用户在 Telegram 发消息为例，数据流向如下：

用户 → Channel（Telegram）→ Gateway（路由与鉴权）→ Agent（执行任务）→ Gateway（结果回传）→ Channel → 用户

从系统分层角度看，Gateway 处于控制平面层，它上承入口层（Channels），下启执行平面（Agent），是整个架构的枢纽。

🚀 启动与运维

Gateway 支持两种运行模式：

• 前台运行：openclaw gateway run，用于调试和观察实时日志。

• 后台服务：openclaw gateway install，将其注册为系统服务（macOS 的 LaunchAgent 或 Linux 的 systemd 服务），实现 7×24 小时常驻。

日常运维可通过 openclaw gateway status 检查健康状态，正常应显示 Runtime: running 和 RPC probe: ok。