第4章 Gateway 网关深入理解

一句话：Gateway 是 OpenClaw 的控制平面，所有消息的调度、配置的加载、Channel 的健康检查都从这里开始——搞不定 Gateway，后面全白搭。

---

4.1 Gateway 的角色

Gateway 是 OpenClaw 的核心进程，运行在 WebSocket 协议之上，默认监听端口 18789。它承担以下职责：

• 接收并路由来自各 Channel 的消息
• 管理 Agent 生命周期
• 加载和热更新配置
• 提供 Web UI 管理界面（Dashboard）
• Channel 健康检查与自动守护

启动后你可以通过浏览器访问 http://127.0.0.1:18789 进入管理面板。

---

4.2 配置文件详解

4.2.1 位置与格式

OpenClaw 的全局配置文件位于：

~/.openclaw/openclaw.json

虽然扩展名是 .json，但实际使用的是 JSON5 格式：

{
  // 这是注释，JSON5 支持
  gateway: {
    port: 18789,   // 行尾注释也可以
    bind: "loopback",
  },  // 尾逗号不会报错
}

严格模式警告：配置文件采用严格校验。写了一个 OpenClaw 不认识的 key，启动时会直接报错退出。唯一的例外是根级别的 $schema 字段：

{
  $schema: "https://openclaw.dev/schema/config.json",
  gateway: { port: 18789 },
}

4.2.2 三种编辑方式

方式一：CLI 命令行（推荐用于脚本和自动化）

openclaw config get gateway.port          # 读取
openclaw config set gateway.port 19000    # 设置
openclaw config unset gateway.reload.debounceMs  # 删除（恢复默认）

方式二：Web UI（推荐日常使用）

启动 Gateway 后浏览器访问 http://127.0.0.1:18789，切换到 Config 标签页在线编辑。

方式三：直接编辑文件

vim ~/.openclaw/openclaw.json

直接编辑后，如果 Gateway 正在运行，配置会根据热更新模式自动生效。

4.2.3 配置诊断

openclaw doctor        # 检查配置问题
openclaw doctor --fix  # 自动修复（删除未知 key、补默认值、修格式）

---

4.3 热更新四种模式

OpenClaw 支持配置文件的热更新，不需要每次改配置都重启：

{
  gateway: {
    reload: {
      mode: "hybrid",     // 热更新模式
      debounceMs: 300,    // 防抖延迟（毫秒）
    },
  },
}

四种模式对比

模式	行为	适用场景
"hybrid"	安全变更即时生效，关键变更触发进程重启	默认值，推荐
"hot"	仅热更新安全变更，需重启的变更只记日志	开发调试
"restart"	任何变更都完整重启	生产环境
"off"	关闭自动更新，需手动重启	完全手动控制

什么是”关键变更”？ 在 hybrid 模式下，以下变更会触发重启：

• gateway.port — 端口变更
• gateway.bind — 绑定地址变更
• gateway.auth — 认证模式变更

其他配置项（Channel 列表、Agent 参数等）都可以即时热更新。

debounceMs 防抖

当你在短时间内多次修改配置文件（比如编辑器连续保存），Gateway 不会每次都触发更新，而是等最后一次修改后 300ms（默认）才执行。如果编辑器有自动保存，建议调大：

{
  gateway: {
    reload: {
      mode: "hybrid",
      debounceMs: 1000,  // 1 秒防抖
    },
  },
}

---

4.4 核心配置项

{
  gateway: {
    port: 18789,                          // 监听端口
    bind: "loopback",                     // 绑定地址
    auth: { mode: "token" },              // 认证配置

    reload: {
      mode: "hybrid",
      debounceMs: 300,
    },
  },
}

绑定地址 (bind)

值	说明	使用场景
"loopback"	仅监听 127.0.0.1，外部无法访问	默认，单机使用
"lan"	监听 0.0.0.0，局域网可访问	局域网多设备共享
"tailnet"	监听 Tailscale 虚拟网络地址	Tailscale 远程访问

安全规则：非 loopback 绑定必须配置认证。 否则 Gateway 拒绝启动：

[FATAL] Non-loopback bind requires auth configuration.

认证模式 (auth.mode)

模式	说明	适合场景
"token"	共享 token 认证	API 调用、程序化访问
"password"	密码认证	Web UI 管理
"trusted-proxy"	信任上游代理的身份头	反向代理（如 Nginx）

Channel 自动守护

Gateway 会自动监控各 Channel 的连接状态。当 Channel 断线时，Gateway 会自动尝试重连。

排错提示：Channel 反复重启，先检查对应平台的 API Key 或 Bot Token 是否过期，这是最常见的原因。

---

4.5 Daemon 管理

# 前台启动（占用终端，适合调试）
openclaw gateway

# 安装为系统服务并启动
openclaw gateway install
openclaw gateway start

# 查看状态
openclaw gateway status

# 重启（优雅关闭现有连接）
openclaw gateway restart

# 停止
openclaw gateway stop

# 查看日志
openclaw logs
openclaw logs --limit 100

排错提示：启动失败时，日志是第一个要看的地方。常见错误：端口被占用、配置格式错误、API Key 无效。

systemd 管理（Linux 服务器）

# 检查服务状态
systemctl --user status openclaw

# 启动 / 停止 / 重启
systemctl --user start openclaw
systemctl --user stop openclaw
systemctl --user restart openclaw

# 开机自启
systemctl --user enable openclaw

# 防止登出后服务被停掉
sudo loginctl enable-linger $USER

调优 systemd 配置：

systemctl --user edit openclaw

[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Restart=always
RestartSec=2
TimeoutStartSec=90

---

4.6 配置拆分 ($include)

当配置越来越复杂，$include 允许你拆分到多个文件：

// ~/.openclaw/openclaw.json — 主配置文件
{
  $schema: "https://openclaw.dev/schema/config.json",

  gateway: {
    port: 18789,
    bind: "loopback",
    reload: { mode: "hybrid", debounceMs: 300 },
  },

  // $include 在对象内部使用，替换该对象的内容
  agents: { $include: "./agents.json5" },
  channels: { $include: "./channels.json5" },
  env: { $include: "./env.json5" },
}

// ~/.openclaw/agents.json5 — 注意：不要再包 agents: {} 外层
{
  defaults: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "deepseek/deepseek-v3.2" },
  },
  list: [
    { id: "main", default: true },
  ],
}

// ~/.openclaw/channels.json5 — 注意：不要再包 channels: {} 外层
{
  telegram: {
    enabled: true,
    botToken: "${TELEGRAM_BOT_TOKEN}",
  },
  discord: {
    enabled: true,
    token: "${DISCORD_BOT_TOKEN}",
  },
}

$include 规则：

• $include 放在对象内部，替换该对象的内容（单个文件替换，数组则深度合并）
• 路径相对于引入文件所在目录，必须在配置根目录内
• 同级键（sibling keys）优先于被引入的值
• 支持嵌套引入（最多 10 层深度），但注意避免循环引用

推荐的文件拆分方案：

~/.openclaw/
  openclaw.json        # 主文件：gateway + $include
  agents.json5         # Agent 配置
  channels.json5       # Channel 配置
  env.json5            # 环境变量和密钥（加入 .gitignore）

---

4.7 环境变量管理 (env)

API Key 等敏感信息不应该硬编码到配置中。env 段集中管理环境变量：

{
  env: {
    // 直接定义
    DEEPSEEK_API_KEY: "sk-xxxxxxxx",

    // 从系统 Shell 环境继承
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },

    // 变量引用
    vars: {
      GROQ_API_KEY: "${CUSTOM_KEY}",
    },
  },
}

变量解析优先级（从高到低）

1. 系统进程环境变量（父 shell / daemon 已有的值，最高优先级）
2. 工作目录下的 .env 文件（不覆盖已有值）
3. ~/.openclaw/.env（全局 fallback，不覆盖已有值）
4. 配置文件 env 段中定义的值（仅在缺失时填充）
5. shellEnv 从登录 shell 导入的值（仅补充缺失的预期 key）

shellEnv 的工作原理

当 shellEnv.enabled 为 true 时，Gateway 启动时会启动一个临时 shell 子进程，加载你的 .bashrc / .zshrc，读取所有导出的环境变量。这意味着你在 shell 配置中 export 的变量，OpenClaw 也能自动获取：

~/.zshrc

export DEEPSEEK_API_KEY="sk-xxxxxxxx"

// openclaw.json — 不需要再写一遍 Key
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

排错提示：shellEnv 读取超时（默认 15 秒），通常是 shell 启动脚本太慢（如加载 nvm、conda 等）。增大 timeoutMs 或把关键 export 放到 .bashrc 最前面。

安全实践

openclaw.json

// 推荐：密钥拆分到独立文件
{
  env: { $include: "./env.json5" },
  gateway: { /* ... */ },
}

// env.json5（加入 .gitignore）— 不要再包 env: {} 外层
{
  DEEPSEEK_API_KEY: "sk-xxxxxxxx",
}

echo "env.json5" >> ~/.openclaw/.gitignore

---

4.8 小结

主题	要点
配置文件	~/.openclaw/openclaw.json，JSON5 格式，支持注释，对未知 key 严格报错
编辑方式	CLI（openclaw config）、Web UI、直接编辑文件
热更新	四种模式，hybrid 是最佳默认选择
安全规则	非 loopback 绑定必须配置认证
配置拆分	$include 把大配置切成多个文件
环境变量	env 段集中管理，支持 shell 继承和变量引用
诊断工具	openclaw doctor + --fix

下一章深入 Agent 智能体的配置——模型选择、System Prompt 编写和 Session 管理。