Gateway

OpenClaw.app 使用 SSH 隧道连接到远程 Gateway 网关。本指南向你展示如何设置。 概述 ┌─────────────────────────────────────────────────────────────┐ │ Client Machine │ │ │ │ OpenClaw.app ──► ws://127.0.0.1:18789 (local port) │ │ │ │ │ ▼ │ │ SSH Tunnel ────────────────────────────────────────────────│ │ │ │ └─────────────────────┼──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Remote Machine │ │ │ │ Gateway WebSocket ──► ws://127.0.0.1:18789 ──► │ │ │ └─────────────────────────────────────────────────────────────┘ 快速设置 步骤 1：添加 SSH 配置 编辑 ~/.ssh/config 并添加： Host remote-gateway HostName <REMOTE_IP> # e.g., 172.27.187.184 User <REMOTE_USER> # e.g., jefferson LocalForward 18789 127.0.0.1:18789 IdentityFile ~/.ssh/id_rsa 将 <REMOTE_IP> 和 <REMOTE_USER> 替换为你的值。 ...

验证渠道连接的简短指南，无需猜测。 快速检查 openclaw status — 本地摘要：Gateway 网关可达性/模式、更新提示、已链接渠道认证时长、会话 + 最近活动。 openclaw status --all — 完整本地诊断（只读、彩色、可安全粘贴用于调试）。 openclaw status --deep — 还会探测运行中的 Gateway 网关（支持时进行每渠道探测）。 openclaw health --json — 向运行中的 Gateway 网关请求完整健康快照（仅 WS；不直接访问 Baileys 套接字）。 在 WhatsApp/WebChat 中单独发送 /status 消息可获取状态回复，而不调用智能体。 日志：跟踪 /tmp/openclaw/openclaw-*.log 并过滤 web-heartbeat、web-reconnect、web-auto-reply、web-inbound。 深度诊断 磁盘上的凭证：ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json（mtime 应该是最近的）。 会话存储：ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json（路径可在配置中覆盖）。计数和最近收件人通过 status 显示。 重新链接流程：当日志中出现状态码 409–515 或 loggedOut 时，执行 openclaw channels logout && openclaw channels login --verbose。（注意：配对后状态 515 时 QR 登录流程会自动重启一次。） 当出现故障时 logged out 或状态 409–515 → 使用 openclaw channels logout 然后 openclaw channels login 重新链接。 Gateway 网关不可达 → 启动它：openclaw gateway --port 18789（如果端口被占用则使用 --force）。 没有入站消息 → 确认已链接的手机在线且发送者被允许（channels.whatsapp.allowFrom）；对于群聊，确保允许列表 + 提及规则匹配（channels.whatsapp.groups、agents.list[].groupChat.mentionPatterns）。 专用"health"命令 openclaw health --json 向运行中的 Gateway 网关请求其健康快照（CLI 不直接访问渠道套接字）。它报告已链接凭证/认证时长（如可用）、每渠道探测摘要、会话存储摘要和探测持续时间。如果 Gateway 网关不可达或探测失败/超时，它以非零退出。使用 --timeout <ms> 覆盖默认的 10 秒。

OpenClaw 通过 exec 工具运行 shell 命令，并将长时间运行的任务保存在内存中。process 工具管理这些后台会话。 exec 工具 关键参数： command（必填） yieldMs（默认 10000）：在此延迟后自动转为后台运行 background（布尔值）：立即转为后台运行 timeout（秒，默认 1800）：在此超时后终止进程 elevated（布尔值）：如果启用/允许提权模式，则在宿主机上运行 需要真实 TTY？设置 pty: true。 workdir、env 行为： 前台运行直接返回输出。 当转为后台运行（显式或超时）时，工具返回 status: "running" + sessionId 和一小段尾部输出。 输出保存在内存中，直到会话被轮询或清除。 如果 process 工具被禁用，exec 将同步运行并忽略 yieldMs/background。 子进程桥接 当在 exec/process 工具之外生成长时间运行的子进程时（例如 CLI 重新生成或 Gateway 网关辅助程序），请附加子进程桥接辅助程序，以便终止信号被转发，监听器在退出/错误时被分离。这可以避免在 systemd 上产生孤立进程，并保持跨平台的关闭行为一致。 环境变量覆盖： PI_BASH_YIELD_MS：默认 yield 时间（毫秒） PI_BASH_MAX_OUTPUT_CHARS：内存输出上限（字符） OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS：每个流的待处理 stdout/stderr 上限（字符） PI_BASH_JOB_TTL_MS：已完成会话的 TTL（毫秒，限制在 1 分钟至 3 小时之间） 配置（推荐）： tools.exec.backgroundMs（默认 10000） tools.exec.timeoutSec（默认 1800） tools.exec.cleanupMs（默认 1800000） tools.exec.notifyOnExit（默认 true）：当后台 exec 退出时，将系统事件加入队列并请求心跳。 process 工具 操作： ...

大多数设置应该使用单个 Gateway 网关，因为一个 Gateway 网关可以处理多个消息连接和智能体。如果你需要更强的隔离或冗余（例如，救援机器人），请使用隔离的配置文件/端口运行多个 Gateway 网关。 隔离检查清单（必需） OPENCLAW_CONFIG_PATH — 每个实例的配置文件 OPENCLAW_STATE_DIR — 每个实例的会话、凭证、缓存 agents.defaults.workspace — 每个实例的工作区根目录 gateway.port（或 --port）— 每个实例唯一 派生端口（浏览器/画布）不得重叠 如果这些是共享的，你将遇到配置竞争和端口冲突。 推荐：配置文件（--profile） 配置文件自动限定 OPENCLAW_STATE_DIR + OPENCLAW_CONFIG_PATH 范围并为服务名称添加后缀。 # main openclaw --profile main setup openclaw --profile main gateway --port 18789 # rescue openclaw --profile rescue setup openclaw --profile rescue gateway --port 19001 按配置文件的服务： openclaw --profile main gateway install openclaw --profile rescue gateway install 救援机器人指南 在同一主机上运行第二个 Gateway 网关，使用独立的： 配置文件/配置 状态目录 工作区 基础端口（加上派生端口） 这使救援机器人与主机器人隔离，以便在主机器人宕机时可以调试或应用配置更改。 ...

快速检查：openclaw security audit 另请参阅：形式化验证（安全模型） 定期运行此命令（尤其是在更改配置或暴露网络接口之后）： openclaw security audit openclaw security audit --deep openclaw security audit --fix 它会标记常见的安全隐患（Gateway 网关认证暴露、浏览器控制暴露、提权白名单、文件系统权限）。 --fix 会应用安全防护措施： 将常见渠道的 groupPolicy="open" 收紧为 groupPolicy="allowlist"（以及单账户变体）。 将 logging.redactSensitive="off" 恢复为 "tools"。 收紧本地权限（~/.openclaw → 700，配置文件 → 600，以及常见状态文件如 credentials/*.json、agents/*/agent/auth-profiles.json 和 agents/*/sessions/sessions.json）。 在你的机器上运行具有 shell 访问权限的 AI 智能体是……有风险的。以下是如何避免被攻击的方法。 OpenClaw 既是产品也是实验：你正在将前沿模型的行为连接到真实的消息平台和真实的工具。不存在"完美安全"的设置。 目标是有意识地考虑： 谁可以与你的机器人交谠 机器人被允许在哪里执行操作 机器人可以访问什么 从能正常工作的最小访问权限开始，然后随着信心增长再逐步扩大。 审计检查内容（高层概述） 入站访问（私信策略、群组策略、白名单）：陌生人能否触发机器人？ 工具影响范围（提权工具 + 开放房间）：提示词注入是否可能转化为 shell/文件/网络操作？ 网络暴露（Gateway 网关绑定/认证、Tailscale Serve/Funnel、弱/短认证令牌）。 浏览器控制暴露（远程节点、中继端口、远程 CDP 端点）。 本地磁盘卫生（权限、符号链接、配置包含、“同步文件夹"路径）。 插件（存在扩展但没有显式白名单）。 模型卫生（当配置的模型看起来是旧版时发出警告；不会硬性阻止）。 如果运行 --deep，OpenClaw 还会尝试尽力进行实时 Gateway 网关探测。 凭证存储映射 在审计访问权限或决定备份内容时使用： ...

OpenClaw 的 Gateway 网关暴露了一个简单的 HTTP 端点用于直接调用单个工具。它始终启用，但受 Gateway 网关认证和工具策略限制。 POST /tools/invoke 与 Gateway 网关相同的端口（WS + HTTP 多路复用）：http://<gateway-host>:<port>/tools/invoke 默认最大负载大小为 2 MB。 认证 使用 Gateway 网关认证配置。发送 bearer 令牌： Authorization: Bearer <token> 说明： 当 gateway.auth.mode="token" 时，使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。 当 gateway.auth.mode="password" 时，使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。 请求体 { "tool": "sessions_list", "action": "json", "args": {}, "sessionKey": "main", "dryRun": false } 字段： tool（string，必需）：要调用的工具名称。 action（string，可选）：如果工具 schema 支持 action 且 args 负载省略了它，则映射到 args。 args（object，可选）：工具特定的参数。 sessionKey（string，可选）：目标会话键。如果省略或为 "main"，Gateway 网关使用配置的主会话键（遵循 session.mainKey 和默认智能体，或在全局范围中使用 global）。 dryRun（boolean，可选）：保留供将来使用；当前忽略。 策略 + 路由行为 工具可用性通过 Gateway 网关智能体使用的相同策略链过滤： ...

心跳 vs Cron？ 参见 Cron vs 心跳 了解何时使用哪种方案。 心跳在主会话中运行周期性智能体轮次，使模型能够在不打扰你的情况下提醒需要关注的事项。 快速开始（新手） 保持心跳启用（默认 30m，Anthropic OAuth/setup-token 为 1h）或设置你自己的频率。 在智能体工作区创建一个简单的 HEARTBEAT.md 检查清单（可选但推荐）。 决定心跳消息发送到哪里（默认 target: "last"）。 可选：启用心跳推理内容发送以提高透明度。 可选：将心跳限制在活动时段（本地时间）。 配置示例： { agents: { defaults: { heartbeat: { every: "30m", target: "last", // activeHours: { start: "08:00", end: "24:00" }, // includeReasoning: true, // 可选：同时发送单独的 `Reasoning:` 消息 }, }, }, } 默认值 间隔：30m（当检测到的认证模式为 Anthropic OAuth/setup-token 时为 1h）。设置 agents.defaults.heartbeat.every 或单智能体 agents.list[].heartbeat.every；使用 0m 禁用。 提示内容（可通过 agents.defaults.heartbeat.prompt 配置）： Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. 心跳提示原样作为用户消息发送。系统提示包含"Heartbeat"部分，运行在内部被标记。 活动时段（heartbeat.activeHours）按配置的时区检查。在时段外，心跳会被跳过直到下一个时段内的时钟周期。 心跳提示的用途 默认提示故意设计得比较宽泛： ...

当 OpenClaw 出现异常时，以下是解决方法。 如果你只想快速分类问题，请先查看常见问题的最初的六十秒。本页深入介绍运行时故障和诊断。 特定提供商的快捷方式：/channels/troubleshooting 状态与诊断 快速分类命令（按顺序）： 命令 它告诉你什么 何时使用 openclaw status 本地摘要：操作系统 + 更新、Gateway 网关可达性/模式、服务、智能体/会话、提供商配置状态 首次检查，快速概览 openclaw status --all 完整本地诊断（只读、可粘贴、相对安全）包括日志尾部 当你需要分享调试报告时 openclaw status --deep 运行 Gateway 网关健康检查（包括提供商探测；需要可达的 Gateway 网关） 当"已配置"不意味着"正常工作"时 openclaw gateway probe Gateway 网关发现 + 可达性（本地 + 远程目标） 当你怀疑正在探测错误的 Gateway 网关时 openclaw channels status --probe 向运行中的 Gateway 网关查询渠道状态（并可选探测） 当 Gateway 网关可达但渠道异常时 openclaw gateway status 监管程序状态（launchd/systemd/schtasks）、运行时 PID/退出、最后的 Gateway 网关错误 当服务"看起来已加载"但没有运行时 openclaw logs --follow 实时日志（运行时问题的最佳信号） 当你需要实际的故障原因时 分享输出： 优先使用 openclaw status --all（它会隐藏令牌）。如果你粘贴 openclaw status，考虑先设置 OPENCLAW_SHOW_SECRETS=0（令牌预览）。 ...

面向用户的概览（CLI + Control UI + 配置），请参阅 /logging。 OpenClaw 有两个日志"界面"： 控制台输出（你在终端 / Debug UI 中看到的内容）。 文件日志（JSON 行）由 Gateway 网关日志记录器写入。 基于文件的日志记录器 默认滚动日志文件位于 /tmp/openclaw/ 下（每天一个文件）：openclaw-YYYY-MM-DD.log 日期使用 Gateway 网关主机的本地时区。 日志文件路径和级别可以通过 ~/.openclaw/openclaw.json 配置： logging.file logging.level 文件格式是每行一个 JSON 对象。 Control UI 的 Logs 标签页通过 Gateway 网关（logs.tail）尾随此文件。CLI 也可以这样做： openclaw logs --follow Verbose 与日志级别 文件日志完全由 logging.level 控制。 --verbose 仅影响控制台详细程度（和 WS 日志样式）；它不会提高文件日志级别。 要在文件日志中捕获仅 verbose 的详细信息，请将 logging.level 设置为 debug 或 trace。 控制台捕获 CLI 捕获 console.log/info/warn/error/debug/trace 并将它们写入文件日志，同时仍打印到 stdout/stderr。 你可以独立调整控制台详细程度： logging.consoleLevel（默认 info） logging.consoleStyle（pretty | compact | json） 工具摘要脱敏 详细工具摘要（例如 🛠️ Exec: ...）可以在进入控制台流之前屏蔽敏感令牌。这仅限工具，不会更改文件日志。 ...

大多数操作通过 Gateway 网关（openclaw gateway）进行，它是一个长期运行的单一进程，负责管理渠道连接和 WebSocket 控制平面。 核心规则 建议每台主机运行一个 Gateway 网关。它是唯一允许拥有 WhatsApp Web 会话的进程。对于救援机器人或严格隔离的场景，可以使用隔离的配置文件和端口运行多个 Gateway 网关。参见多 Gateway 网关。 优先使用回环地址：Gateway 网关的 WS 默认为 ws://127.0.0.1:18789。即使是回环连接，向导也会默认生成 gateway token。若需通过 tailnet 访问，请运行 openclaw gateway --bind tailnet --token ...，因为非回环绑定必须使用 token。 节点根据需要通过局域网、tailnet 或 SSH 连接到 Gateway 网关的 WS。旧版 TCP 桥接已弃用。 Canvas 主机是一个 HTTP 文件服务器，运行在 canvasHost.port（默认 18793）上，提供 /__openclaw__/canvas/ 路径供节点 WebView 使用。参见 Gateway 网关配置（canvasHost）。 远程使用通常通过 SSH 隧道或 Tailscale VPN。参见远程访问和设备发现。