Gateway 暴露操作手册

​

选择暴露模式

​

预检清单

• Gateway 主机、OS 用户和状态目录（默认 ~/.openclaw）。
• Gateway URL 和 bind 模式（gateway.bind；默认端口 18789）。
• Auth 模式、token/password 来源，或受信任代理身份来源。
• 每个已启用的 channel，以及它是否接受 DM、group 或 webhook。
• 可从非本地发送者访问的 agent。
• 每个可访问 agent 的 tool profile、sandbox 模式和 elevated tool policy。
• 这些 agent 可用的外部凭证。
• ~/.openclaw/openclaw.json 和凭证的备份位置。

​

基线检查

openclaw doctor
openclaw security audit
openclaw security audit --deep
openclaw health

openclaw gateway probe --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

​

最小安全基线

{
  gateway: {
    bind: "loopback",
    auth: {
      mode: "token",
      token: "replace-with-a-long-random-token",
    },
  },
  session: {
    dmScope: "per-channel-peer",
  },
  agents: {
    defaults: {
      sandbox: { mode: "non-main" },
    },
  },
  tools: {
    profile: "messaging",
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
}

​

DM 和群组暴露

• 优先使用 dmPolicy: "pairing" 或严格的 allowFrom 列表，而不是 dmPolicy: "open"。
• 不要将 "*" 允许列表与广泛的工具访问权限结合使用。
• 在群组中要求提及，除非房间被严格控制。
• 当多人可以向 bot 发送 DM 时，设置 session.dmScope: "per-channel-peer"（对于多账号通道则使用 "per-account-channel-peer"），这样 DM 会话就不会共享上下文。
• 将共享通道路由给只具备最少工具且不持有个人凭据的 agent。

​

反向代理检查

• 代理在转发到 Gateway 之前必须先对用户进行身份验证。
• 防火墙或网络策略必须阻止对 Gateway 端口的直接访问。
• gateway.trustedProxies 必须只列出代理源 IP。
• 代理必须清除或覆盖客户端提供的身份和转发 标头。
• 当代理服务于多个 受众时，设置 gateway.auth.trustedProxy.allowUsers。
• 仅对同主机代理使用 gateway.auth.trustedProxy.allowLoopback，前提是本地进程是受信任的，并且该代理拥有身份标头。

​

工具与沙箱审查

• 确认哪些会话运行在主机上，哪些运行在沙箱中。
• 拒绝主机执行，或要求审批后才能执行。
• 除非某个特定且可信的发送者确实需要，否则保持高权限工具禁用。
• 对于开放或半开放的消息交互场景，避免使用浏览器、画布、节点、cron、网关和会话生成工具。
• 保持绑定挂载范围尽可能窄；避免使用凭据、主目录、Docker 套接字和系统路径。
• 对于实质上不同的信任边界，使用不同的网关、操作系统用户或主机。

​

变更后的验证

1. 重新运行 openclaw security audit --deep。
2. 确认成功的授权连接可以正常成功。
3. 确认未经授权的发送方或浏览器会话被拒绝。
4. 确认日志会对密钥进行脱敏。
5. 确认 DM/群组路由仅到达预期的代理。
6. 确认高影响工具会请求批准或被拒绝。
7. 记录已接受的残余警告。

​

回滚计划

{
  gateway: {
    bind: "loopback",
  },
  channels: {
    whatsapp: { dmPolicy: "disabled" },
    telegram: { dmPolicy: "disabled" },
    discord: { dmPolicy: "disabled" },
    slack: { dmPolicy: "disabled" },
  },
  tools: {
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
}

1. 停止公网转发、Tailscale Funnel 或反向代理路由。
2. 轮换 Gateway tokens/passwords 和受影响的集成凭据。
3. 从白名单中移除 "*" 和意外的发送者。
4. 审查最近的审计日志、运行历史、tool 调用和配置变更。
5. 重新运行 openclaw security audit --deep。
6. 使用满足工作流的最窄模式重新启用访问。

​

审查清单

• Gateway 仍保持仅限 loopback，除非有记录在案的理由。
• 非 loopback 访问具备认证、防火墙控制且没有公网直连路径。
• Trusted-proxy 部署具有严格的代理 IP 和标头控制。
• DMs 使用配对或 allowlist，而不是默认开放访问。
• Groups 需要 mention 或显式 allowlist。
• 共享 channels 不应接触个人凭据。
• 非主会话在 sandbox 模式中运行。
• 主机 exec 和 elevated tools 被拒绝或受审批门控。
• 日志对 secrets 脱敏。
• 关键审计发现已解决。
• 回滚步骤已测试并记录。