OpenClaw 中文教程网

外观

第五章：网关配置与运维

约 2605 字大约 9 分钟

本章介绍 OpenClaw Gateway 的完整配置、远程访问、安全加固、Tailscale 集成，以及故障排查。

5.1 Gateway 快速启动

Gateway 是 OpenClaw 的核心守护进程，负责所有消息路由、渠道连接和智能体运行。

5 分钟本地启动

# 第一步：启动 Gateway
openclaw gateway --port 18789

# 调试模式（输出详细日志）
openclaw gateway --port 18789 --verbose

# 强制终止端口占用后启动
openclaw gateway --force

# 第二步：验证健康状态
openclaw gateway status
openclaw status
openclaw logs --follow

# 正常状态标志：
# Runtime: running
# RPC probe: ok

# 第三步：验证渠道连接
openclaw channels status --probe

Gateway 运行模式

配置说明
单端口多路复用WebSocket + HTTP API + 控制台 共用同一端口
默认绑定loopback（仅本机连接）
默认端口18789
默认认证需要 Token 或密码

端口和绑定优先级

设置解析顺序
Gateway 端口--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
绑定模式CLI → gateway.bind → loopback

操作员命令集

openclaw gateway status          # 状态检查
openclaw gateway status --deep   # 深度诊断
openclaw gateway status --json   # JSON 格式输出
openclaw gateway install         # 安装为系统服务
openclaw gateway restart         # 重启
openclaw gateway stop            # 停止
openclaw secrets reload          # 重载密钥
openclaw logs --follow           # 实时日志
openclaw doctor                  # 诊断修复

5.2 配置文件详解

OpenClaw 使用 JSON5 格式的配置文件，位于 ~/.openclaw/openclaw.json。

最小配置

{
  "agents": {
    "defaults": {"workspace": "~/.openclaw/workspace"}
  },
  "channels": {
    "whatsapp": {"allowFrom": ["+15555550123"]}
  }
}

编辑配置的方式

# 方式一：交互向导（推荐）
openclaw onboard
openclaw configure

# 方式二：命令行一次性设置
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey

# 方式三：Web 控制台（可视化）
openclaw dashboard   # 打开浏览器，使用 Config 标签页

# 方式四：直接编辑 JSON 文件
nano ~/.openclaw/openclaw.json

严格验证

OpenClaw 只接受完全符合 Schema 的配置。配置错误时 Gateway 拒绝启动：

# 查看配置问题
openclaw doctor

# 自动修复
openclaw doctor --fix

5.3 完整配置参考

模型配置

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-5",
        "fallbacks": ["openai/gpt-5.2"]
      },
      "models": {
        "anthropic/claude-sonnet-4-5": {"alias": "Sonnet"},
        "openai/gpt-5.2": {"alias": "GPT"}
      },
      "thinkingDefault": "high",
      "timeoutSeconds": 1800,
      "imageMaxDimensionPx": 1200
    }
  }
}

会话配置

{
  "session": {
    "dmScope": "per-channel-peer",
    "threadBindings": {
      "enabled": true,
      "ttlHours": 24
    },
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 120
    },
    "resetTriggers": ["/new", "/reset"]
  }
}
dmScope 值说明
main（默认）所有 DM 共享一个会话
per-peer每个发送者独立会话
per-channel-peer每个渠道+发送者独立会话（推荐）
per-account-channel-peer更细粒度的隔离

沙箱配置

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent"
      }
    }
  }
}
mode 值说明
off（默认）不使用沙箱
non-main非主会话使用沙箱
all所有会话使用沙箱
scope 值说明
session每个会话独立容器
agent每个智能体独立容器
shared所有智能体共享容器

Cron 定时任务配置

{
  "cron": {
    "enabled": true,
    "maxConcurrentRuns": 2,
    "sessionRetention": "24h",
    "runLog": {
      "maxBytes": "2mb",
      "keepLines": 2000
    }
  }
}

Webhook 钩子配置

{
  "hooks": {
    "enabled": true,
    "token": "shared-secret",
    "path": "/hooks",
    "defaultSessionKey": "hook:ingress",
    "mappings": [
      {
        "match": {"path": "gmail"},
        "action": "agent",
        "agentId": "main",
        "deliver": true
      }
    ]
  }
}

分文件配置（$include）

// ~/.openclaw/openclaw.json
{
  "gateway": {"port": 18789},
  "agents": {"$include": "./agents.json5"},
  "broadcast": {
    "$include": ["./clients/a.json5", "./clients/b.json5"]
  }
}

5.4 配置热重载

Gateway 会监视配置文件，大多数设置无需重启即可生效。

热重载模式

模式行为
hybrid（默认）安全更改立即生效，需重启的更改自动重启
hot仅热应用安全更改，需重启的更改记录警告
restart任何更改都重启
off禁用文件监视
{
  "gateway": {
    "reload": {"mode": "hybrid", "debounceMs": 300}
  }
}

哪些更改需要重启

类别字段需要重启？
渠道channels.*❌ 不需要
智能体/模型agent、agents、models❌ 不需要
自动化hooks、cron、heartbeat❌ 不需要
会话/消息session、messages❌ 不需要
工具/媒体tools、browser、skills❌ 不需要
Gateway 服务器gateway.*（端口、绑定、认证、TLS）✅ 需要
基础设施discovery、canvasHost、plugins✅ 需要

5.5 环境变量

读取顺序

  1. 父进程环境变量
  2. 当前目录的 .env 文件
  3. ~/.openclaw/.env（全局回退）

在配置中内联环境变量

{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-...",
    "vars": {"GROQ_API_KEY": "gsk-..."},
    "shellEnv": {"enabled": true, "timeoutMs": 15000}
  }
}

配置值中引用环境变量

{
  "gateway": {"auth": {"token": "${OPENCLAW_GATEWAY_TOKEN}"}},
  "models": {"providers": {"custom": {"apiKey": "${CUSTOM_API_KEY}"}}}
}

常用环境变量

变量说明
OPENCLAW_GATEWAY_TOKENGateway 认证 Token
OPENCLAW_GATEWAY_PASSWORDGateway 认证密码
OPENCLAW_GATEWAY_PORTGateway 端口（默认 18789）
OPENCLAW_CONFIG_PATH配置文件路径
OPENCLAW_STATE_DIR状态目录（默认 ~/.openclaw）
TELEGRAM_BOT_TOKENTelegram Bot Token
DISCORD_BOT_TOKENDiscord Bot Token
BRAVE_API_KEYBrave 搜索 API Key

5.6 远程访问

推荐架构：Tailscale（见 5.7 节）

SSH 隧道（通用方案）

# 在本地机器上创建隧道
ssh -N -L 18789:127.0.0.1:18789 user@your-server

# 然后本地工具即可访问远程 Gateway
openclaw health
openclaw status --deep

持久化远程配置

{
  "gateway": {
    "mode": "remote",
    "remote": {
      "url": "ws://127.0.0.1:18789",
      "token": "your-token"
    }
  }
}

凭证解析优先级

  • 本地模式：--token → OPENCLAW_GATEWAY_TOKEN → gateway.auth.token → gateway.remote.token
  • 远程模式：gateway.remote.token → OPENCLAW_GATEWAY_TOKEN → gateway.auth.token

常见远程部署方案

场景推荐方案
VPS/家庭服务器（Always-on）Tailscale + loopback 绑定
家庭台式机 + 笔记本控制macOS 应用的 Remote over SSH 模式
笔记本运行 + 其他设备访问Tailscale Serve

5.7 Tailscale 集成

Tailscale 是 OpenClaw 推荐的远程访问方案，提供安全的 HTTPS 访问，无需复杂网络配置。

三种模式

模式说明
serve（推荐）Tailnet 内部 HTTPS，Gateway 保持 loopback
funnel公网 HTTPS，需要密码认证
off（默认）不使用 Tailscale 自动配置

Tailscale Serve 配置（推荐）

{
  "gateway": {
    "bind": "loopback",
    "tailscale": {"mode": "serve"},
    "auth": {"allowTailscale": true}
  }
}
# 命令行启动
openclaw gateway --tailscale serve

访问地址：https://<你的tailscale主机名>/

直接绑定到 Tailnet IP

{
  "gateway": {
    "bind": "tailnet",
    "auth": {"mode": "token", "token": "your-token"}
  }
}

Tailscale Funnel（公网访问）

{
  "gateway": {
    "bind": "loopback",
    "tailscale": {"mode": "funnel"},
    "auth": {"mode": "password", "password": "replace-me"}
  }
}

重要：Funnel 必须使用密码认证，推荐通过环境变量 OPENCLAW_GATEWAY_PASSWORD 设置密码。

Tailscale 前置条件

  • 需要安装并登录 tailscale CLI
  • Serve 模式：需要为 tailnet 启用 HTTPS
  • Funnel 模式：需要 Tailscale v1.38.3+，启用 MagicDNS 和 HTTPS，以及 funnel 节点属性

5.8 安全加固

重要提示：OpenClaw 设计为个人助手安全模型，即每个 Gateway 有一个可信的操作者边界。它不支持多个互不信任用户共用同一 Gateway 的场景。

60 秒加固基线

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": {"mode": "token", "token": "换成长随机Token"}
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+你的电话号码"],
      "groups": {"*": {"requireMention": true}}
    }
  },
  "tools": {
    "deny": ["gateway", "cron", "sessions_spawn", "sessions_send"]
  }
}

安全审计

# 运行安全审计
openclaw security audit

# 深度审计
openclaw security audit --deep

# 自动修复
openclaw security audit --fix

# JSON 格式输出
openclaw security audit --json

威胁模型

你的 AI 助手能做到：

  • 执行任意 Shell 命令
  • 读写文件
  • 访问网络服务
  • 向任何人发送消息（如果给了它 WhatsApp 权限）

消息你的人可能会：

  • 通过提示词注入（Prompt Injection）操控 AI
  • 社会工程学获取数据
  • 探测基础设施信息

安全原则（重要性排序）

  1. 身份优先：控制谁能与机器人通话（DM 配对/allowlist/明确的 open）
  2. 范围其次：控制机器人可以在哪里操作（群组 allowlist + 提及门控、工具、沙箱、设备权限）
  3. 模型最后：假设模型可被操控，设计时要让操控的爆炸半径最小

DM 访问控制模型

策略安全级别说明
pairing（默认）中新用户需配对码审批
allowlist高仅白名单用户
open低任何人都能访问
disabled最高完全禁用 DM

提示词注入防护

即使只有你能发消息，提示词注入也可能通过 AI 读取的内容发生（网页搜索结果、浏览器页面、邮件、文档）。

防护措施：

  • 锁定 DM 访问（配对/allowlist）
  • 群组中使用 @提及门控
  • 将链接、附件、粘贴的内容视为潜在危险
  • 在沙箱中运行敏感工具执行
  • 限制高风险工具（exec、browser、web_fetch）
  • 使用最新的高性能模型（推荐 Claude Opus 4.6）

文件权限

# 保护配置和状态目录
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/

网络暴露原则

  • 默认：loopback + SSH/Tailscale Serve（最安全）
  • 非 loopback 绑定（lan/tailnet/custom）必须使用 Token 认证
  • 永不在 0.0.0.0 上未认证暴露 Gateway

危险工具（不可信内容处理时应禁用）

{
  "tools": {
    "deny": ["gateway", "cron", "sessions_spawn", "sessions_send"]
  }
}

5.9 系统服务（开机自启）

macOS（launchd）

openclaw gateway install
openclaw gateway status
openclaw gateway restart

服务标签：ai.openclaw.gateway（或 ai.openclaw.<profile>）

Linux（systemd 用户服务）

openclaw gateway install
systemctl --user enable --now openclaw-gateway.service
openclaw gateway status

# 注销后持久运行
sudo loginctl enable-linger <用户名>

Linux（系统服务，多用户）

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway.service

5.10 多 Gateway 实例

大多数情况下只应运行一个 Gateway。仅在需要严格隔离/冗余时才使用多实例。

每个实例需要唯一配置：

# 实例 A
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

# 实例 B
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json \
OPENCLAW_STATE_DIR=~/.openclaw-b \
openclaw gateway --port 19002

检查清单：

  • 唯一 gateway.port
  • 唯一 OPENCLAW_CONFIG_PATH
  • 唯一 OPENCLAW_STATE_DIR
  • 唯一 agents.defaults.workspace

5.11 故障排查

诊断命令顺序

按此顺序依次运行：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

健康状态标志：

  • openclaw gateway status 显示 Runtime: running 和 RPC probe: ok
  • openclaw doctor 无阻塞问题
  • openclaw channels status --probe 显示渠道已连接

常见问题速查

错误信息可能原因解决方案
refusing to bind gateway ... without auth非 loopback 绑定但未设置认证添加 Token 或密码
EADDRINUSE / another gateway instance is already listening端口被占用检查是否已有 Gateway 运行，或换端口
Gateway start blocked: set gateway.mode=local配置为远程模式修改 gateway.mode 为 local
unauthorized during connect客户端认证 Token 不匹配检查 Token 配置
渠道无回复消息未路由到智能体检查 allowlist 和绑定配置

无回复排查流程

# 检查状态
openclaw status
openclaw channels status --probe

# 实时跟踪日志
openclaw logs --follow

# 检查配对/allowlist
openclaw pairing list <渠道>

常见原因：

  1. allowFrom 未包含你的号码/ID
  2. dmPolicy 设置导致消息被拒绝
  3. 群组 requireMention 未按要求 @提及
  4. Gateway 未运行或崩溃

Gateway 启动失败

# 查看详细错误
openclaw doctor
openclaw logs --tail 50

# 常见问题：
# - 配置格式错误（JSON5 语法）
# - 端口被占用（换用 --port 选项）
# - 认证配置不完整

Tailscale 访问问题

# 检查 Tailscale 状态
tailscale status

# 验证 Serve 配置
tailscale serve status

# 重启 Gateway 并重新配置 Serve
openclaw gateway restart --tailscale serve

5.12 开发模式

# 隔离的开发环境（不影响生产配置）
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

开发模式特点：

  • 状态存储在 ~/.openclaw-dev/
  • 默认端口 19001
  • 配置隔离，不影响生产

5.13 下一步

内容整理来自OpenClaw官网及自有笔记
Copyright © 2026 OpenClaw 中文教程网