状态：生产就绪，支持机器人私聊和群组。使用 WebSocket 长连接模式接收消息。 内置插件 当前版本的 OpenClaw 已内置 Feishu 插件，因此通常不需要单独安装。 如果你使用的是较旧版本，或是没有内置 Feishu 的自定义安装，可手动安装： openclaw plugins install @openclaw/feishu 快速开始 添加飞书渠道有两种方式： 方式一：通过安装向导添加（推荐） 如果您刚安装完 OpenClaw，可以直接运行向导，根据提示添加飞书： openclaw onboard 向导会引导您完成： 创建飞书应用并获取凭证 配置应用凭证 启动网关 ✅ 完成配置后，您可以使用以下命令检查网关状态： openclaw gateway status - 查看网关运行状态 openclaw logs --follow - 查看实时日志 方式二：通过命令行添加 如果您已经完成了初始安装，可以用以下命令添加飞书渠道： openclaw channels add 然后根据交互式提示选择 Feishu，输入 App ID 和 App Secret 即可。 ✅ 完成配置后，您可以使用以下命令管理网关： openclaw gateway status - 查看网关运行状态 openclaw gateway restart - 重启网关以应用新配置 openclaw logs --follow - 查看实时日志 第一步：创建飞书应用 1. 打开飞书开放平台 访问 飞书开放平台，使用飞书账号登录。 ...

已支持的功能 媒体理解（音频）：如果音频理解已启用（或自动检测），OpenClaw 会： 找到第一个音频附件（本地路径或 URL），如有需要则下载。 在发送给每个模型条目之前执行 maxBytes 限制。 按顺序运行第一个符合条件的模型条目（提供商或 CLI）。 如果失败或跳过（大小/超时），则尝试下一个条目。 成功后，将 Body 替换为 [Audio] 块并设置 {{Transcript}}。 命令解析：转录成功时，CommandBody/RawBody 会设置为转录文本，因此斜杠命令仍然有效。 详细日志：在 --verbose 模式下，我们会在转录运行和替换正文时记录日志。 自动检测（默认） 如果你未配置模型且 tools.media.audio.enabled 未设置为 false，OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项时停止： 本地 CLI（如已安装） sherpa-onnx-offline（需要 SHERPA_ONNX_MODEL_DIR 包含 encoder/decoder/joiner/tokens） whisper-cli（来自 whisper-cpp；使用 WHISPER_CPP_MODEL 或内置的 tiny 模型） whisper（Python CLI；自动下载模型） Gemini CLI（gemini）使用 read_many_files 提供商密钥（OpenAI → Groq → Deepgram → Google） 要禁用自动检测，请设置 tools.media.audio.enabled: false。 要自定义，请设置 tools.media.audio.models。 注意：二进制检测在 macOS/Linux/Windows 上采用尽力而为的方式；请确保 CLI 在 PATH 中（我们会展开 ~），或通过完整命令路径设置显式 CLI 模型。 配置示例 提供商 + CLI 回退（OpenAI + Whisper CLI） { tools: { media: { audio: { enabled: true, maxBytes: 20971520, models: [ { provider: "openai", model: "gpt-4o-mini-transcribe" }, { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"], timeoutSeconds: 45, }, ], }, }, }, } 仅提供商 + 作用域控制 { tools: { media: { audio: { enabled: true, scope: { default: "allow", rules: [{ action: "deny", match: { chatType: "group" } }], }, models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }], }, }, }, } 仅提供商（Deepgram） { tools: { media: { audio: { enabled: true, models: [{ provider: "deepgram", model: "nova-3" }], }, }, }, } 注意事项与限制 提供商认证遵循标准的模型认证顺序（认证配置文件、环境变量、models.providers.*.apiKey）。 当使用 provider: "deepgram" 时，Deepgram 会读取 DEEPGRAM_API_KEY。 Deepgram 设置详情：Deepgram（音频转录）。 音频提供商可以通过 tools.media.audio 覆盖 baseUrl、headers 和 providerOptions。 默认大小限制为 20MB（tools.media.audio.maxBytes）。超大音频会跳过该模型并尝试下一个条目。 音频的默认 maxChars 未设置（完整转录文本）。设置 tools.media.audio.maxChars 或每个条目的 maxChars 来裁剪输出。 OpenAI 自动检测默认使用 gpt-4o-mini-transcribe；设置 model: "gpt-4o-transcribe" 可获得更高准确度。 使用 tools.media.audio.attachments 处理多条语音消息（mode: "all" + maxAttachments）。 转录文本可在模板中通过 {{Transcript}} 使用。 CLI 标准输出有上限（5MB）；请保持 CLI 输出简洁。 常见陷阱 作用域规则采用首次匹配优先。chatType 会被规范化为 direct、group 或 room。 确保你的 CLI 以退出码 0 退出并输出纯文本；JSON 格式需要通过 jq -r .text 进行转换。 保持合理的超时时间（timeoutSeconds，默认 60 秒），以避免阻塞回复队列。

目标 按 HTTP 请求重试，而非按多步骤流程重试。 通过仅重试当前步骤来保持顺序。 避免重复执行非幂等操作。 默认值 尝试次数：3 最大延迟上限：30000 毫秒 抖动：0.1（10%） 提供商默认值： Telegram 最小延迟：400 毫秒 Discord 最小延迟：500 毫秒 行为 Discord 仅在速率限制错误（HTTP 429）时重试。 可用时使用 Discord retry_after，否则使用指数退避。 Telegram 在瞬态错误时重试（429、超时、连接/重置/关闭、暂时不可用）。 可用时使用 retry_after，否则使用指数退避。 Markdown 解析错误不会重试；会回退为纯文本。 配置 在 ~/.openclaw/openclaw.json 中按提供商设置重试策略： { channels: { telegram: { retry: { attempts: 3, minDelayMs: 400, maxDelayMs: 30000, jitter: 0.1, }, }, discord: { retry: { attempts: 3, minDelayMs: 500, maxDelayMs: 30000, jitter: 0.1, }, }, }, } 注意事项 重试按请求应用（消息发送、媒体上传、表情回应、投票、贴纸）。 组合流程不会重试已完成的步骤。

以下示例与当前配置模式一致。有关详尽的参考和每个字段的说明，请参阅配置。 快速开始 绝对最小配置 { agent: { workspace: "~/.openclaw/workspace" }, channels: { whatsapp: { allowFrom: ["+15555550123"] } }, } 保存到 ~/.openclaw/openclaw.json，你就可以从该号码私信机器人了。 推荐的入门配置 { identity: { name: "Clawd", theme: "helpful assistant", emoji: "🦞", }, agent: { workspace: "~/.openclaw/workspace", model: { primary: "anthropic/claude-sonnet-4-5" }, }, channels: { whatsapp: { allowFrom: ["+15555550123"], groups: { "*": { requireMention: true } }, }, }, } 扩展示例（主要选项） JSON5 允许你使用注释和尾随逗号。普通 JSON 也可以使用。 { // 环境 + shell env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-...", }, shellEnv: { enabled: true, timeoutMs: 15000, }, }, // 认证配置文件元数据（密钥存储在 auth-profiles.json 中） auth: { profiles: { "anthropic:[email protected]": { provider: "anthropic", mode: "oauth", email: "[email protected]" }, "anthropic:work": { provider: "anthropic", mode: "api_key" }, "openai:default": { provider: "openai", mode: "api_key" }, "openai-codex:default": { provider: "openai-codex", mode: "oauth" }, }, order: { anthropic: ["anthropic:[email protected]", "anthropic:work"], openai: ["openai:default"], "openai-codex": ["openai-codex:default"], }, }, // 身份 identity: { name: "Samantha", theme: "helpful sloth", emoji: "🦥", }, // 日志 logging: { level: "info", file: "/tmp/openclaw/openclaw.log", consoleLevel: "info", consoleStyle: "pretty", redactSensitive: "tools", }, // 消息格式 messages: { messagePrefix: "[openclaw]", responsePrefix: ">", ackReaction: "👀", ackReactionScope: "group-mentions", }, // 路由 + 队列 routing: { groupChat: { mentionPatterns: ["@openclaw", "openclaw"], historyLimit: 50, }, queue: { mode: "collect", debounceMs: 1000, cap: 20, drop: "summarize", byChannel: { whatsapp: "collect", telegram: "collect", discord: "collect", slack: "collect", signal: "collect", imessage: "collect", webchat: "collect", }, }, }, // 工具 tools: { media: { audio: { enabled: true, maxBytes: 20971520, models: [ { provider: "openai", model: "gpt-4o-mini-transcribe" }, // 可选的 CLI 回退（Whisper 二进制）： // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] } ], timeoutSeconds: 120, }, video: { enabled: true, maxBytes: 52428800, models: [{ provider: "google", model: "gemini-3-flash-preview" }], }, }, }, // 会话行为 session: { scope: "per-sender", reset: { mode: "daily", atHour: 4, idleMinutes: 60, }, resetByChannel: { discord: { mode: "idle", idleMinutes: 10080 }, }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/default/sessions/sessions.json", typingIntervalSeconds: 5, sendPolicy: { default: "allow", rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], }, }, // 渠道 channels: { whatsapp: { dmPolicy: "pairing", allowFrom: ["+15555550123"], groupPolicy: "allowlist", groupAllowFrom: ["+15555550123"], groups: { "*": { requireMention: true } }, }, telegram: { enabled: true, botToken: "YOUR_TELEGRAM_BOT_TOKEN", allowFrom: ["123456789"], groupPolicy: "allowlist", groupAllowFrom: ["123456789"], groups: { "*": { requireMention: true } }, }, discord: { enabled: true, token: "YOUR_DISCORD_BOT_TOKEN", dm: { enabled: true, allowFrom: ["steipete"] }, guilds: { "123456789012345678": { slug: "friends-of-openclaw", requireMention: false, channels: { general: { allow: true }, help: { allow: true, requireMention: true }, }, }, }, }, slack: { enabled: true, botToken: "xoxb-REPLACE_ME", appToken: "xapp-REPLACE_ME", channels: { "#general": { allow: true, requireMention: true }, }, dm: { enabled: true, allowFrom: ["U123"] }, slashCommand: { enabled: true, name: "openclaw", sessionPrefix: "slack:slash", ephemeral: true, }, }, }, // 智能体运行时 agents: { defaults: { workspace: "~/.openclaw/workspace", userTimezone: "America/Chicago", model: { primary: "anthropic/claude-sonnet-4-5", fallbacks: ["anthropic/claude-opus-4-5", "openai/gpt-5.2"], }, imageModel: { primary: "openrouter/anthropic/claude-sonnet-4-5", }, models: { "anthropic/claude-opus-4-5": { alias: "opus" }, "anthropic/claude-sonnet-4-5": { alias: "sonnet" }, "openai/gpt-5.2": { alias: "gpt" }, }, thinkingDefault: "low", verboseDefault: "off", elevatedDefault: "on", blockStreamingDefault: "off", blockStreamingBreak: "text_end", blockStreamingChunk: { minChars: 800, maxChars: 1200, breakPreference: "paragraph", }, blockStreamingCoalesce: { idleMs: 1000, }, humanDelay: { mode: "natural", }, timeoutSeconds: 600, mediaMaxMb: 5, typingIntervalSeconds: 5, maxConcurrent: 3, heartbeat: { every: "30m", model: "anthropic/claude-sonnet-4-5", target: "last", to: "+15555550123", prompt: "HEARTBEAT", ackMaxChars: 300, }, memorySearch: { provider: "gemini", model: "gemini-embedding-001", remote: { apiKey: "${GEMINI_API_KEY}", }, extraPaths: ["../team-docs", "/srv/shared-notes"], }, sandbox: { mode: "non-main", perSession: true, workspaceRoot: "~/.openclaw/sandboxes", docker: { image: "openclaw-sandbox:bookworm-slim", workdir: "/workspace", readOnlyRoot: true, tmpfs: ["/tmp", "/var/tmp", "/run"], network: "none", user: "1000:1000", }, browser: { enabled: false, }, }, }, }, tools: { allow: ["exec", "process", "read", "write", "edit", "apply_patch"], deny: ["browser", "canvas"], exec: { backgroundMs: 10000, timeoutSec: 1800, cleanupMs: 1800000, }, elevated: { enabled: true, allowFrom: { whatsapp: ["+15555550123"], telegram: ["123456789"], discord: ["steipete"], slack: ["U123"], signal: ["+15555550123"], imessage: ["[email protected]"], webchat: ["session:demo"], }, }, }, // 自定义模型提供商 models: { mode: "merge", providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", apiKey: "LITELLM_KEY", api: "openai-responses", authHeader: true, headers: { "X-Proxy-Region": "us-west" }, models: [ { id: "llama-3.1-8b", name: "Llama 3.1 8B", api: "openai-responses", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 128000, maxTokens: 32000, }, ], }, }, }, // Cron 作业 cron: { enabled: true, store: "~/.openclaw/cron/cron.json", maxConcurrentRuns: 2, }, // Webhooks hooks: { enabled: true, path: "/hooks", token: "shared-secret", presets: ["gmail"], transformsDir: "~/.openclaw/hooks", mappings: [ { id: "gmail-hook", match: { path: "gmail" }, action: "agent", wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}", textTemplate: "{{messages[0].snippet}}", deliver: true, channel: "last", to: "+15555550123", thinking: "low", timeoutSeconds: 300, transform: { module: "./transforms/gmail.js", export: "transformGmail" }, }, ], gmail: { account: "[email protected]", label: "INBOX", topic: "projects/<project-id>/topics/gog-gmail-watch", subscription: "gog-gmail-watch-push", pushToken: "shared-push-token", hookUrl: "http://127.0.0.1:18789/hooks/gmail", includeBody: true, maxBytes: 20000, renewEveryMinutes: 720, serve: { bind: "127.0.0.1", port: 8788, path: "/" }, tailscale: { mode: "funnel", path: "/gmail-pubsub" }, }, }, // Gateway 网关 + 网络 gateway: { mode: "local", port: 18789, bind: "loopback", controlUi: { enabled: true, basePath: "/openclaw" }, auth: { mode: "token", token: "gateway-token", allowTailscale: true, }, tailscale: { mode: "serve", resetOnExit: false }, remote: { url: "ws://gateway.tailnet:18789", token: "remote-token" }, reload: { mode: "hybrid", debounceMs: 300 }, }, skills: { allowBundled: ["gemini", "peekaboo"], load: { extraDirs: ["~/Projects/agent-scripts/skills"], }, install: { preferBrew: true, nodeManager: "npm", }, entries: { "nano-banana-pro": { enabled: true, apiKey: "GEMINI_KEY_HERE", env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, }, }, } 常见模式 多平台设置 { agent: { workspace: "~/.openclaw/workspace" }, channels: { whatsapp: { allowFrom: ["+15555550123"] }, telegram: { enabled: true, botToken: "YOUR_TOKEN", allowFrom: ["123456789"], }, discord: { enabled: true, token: "YOUR_TOKEN", dm: { allowFrom: ["yourname"] }, }, }, } OAuth 带 API 密钥回退 { auth: { profiles: { "anthropic:subscription": { provider: "anthropic", mode: "oauth", email: "[email protected]", }, "anthropic:api": { provider: "anthropic", mode: "api_key", }, }, order: { anthropic: ["anthropic:subscription", "anthropic:api"], }, }, agent: { workspace: "~/.openclaw/workspace", model: { primary: "anthropic/claude-sonnet-4-5", fallbacks: ["anthropic/claude-opus-4-5"], }, }, } Anthropic 订阅 + API 密钥，MiniMax 回退 { auth: { profiles: { "anthropic:subscription": { provider: "anthropic", mode: "oauth", email: "[email protected]", }, "anthropic:api": { provider: "anthropic", mode: "api_key", }, }, order: { anthropic: ["anthropic:subscription", "anthropic:api"], }, }, models: { providers: { minimax: { baseUrl: "https://api.minimax.io/anthropic", api: "anthropic-messages", apiKey: "${MINIMAX_API_KEY}", }, }, }, agent: { workspace: "~/.openclaw/workspace", model: { primary: "anthropic/claude-opus-4-5", fallbacks: ["minimax/MiniMax-M2.1"], }, }, } 工作机器人（受限访问） { identity: { name: "WorkBot", theme: "professional assistant", }, agent: { workspace: "~/work-openclaw", elevated: { enabled: false }, }, channels: { slack: { enabled: true, botToken: "xoxb-...", channels: { "#engineering": { allow: true, requireMention: true }, "#general": { allow: true, requireMention: true }, }, }, }, } 仅本地模型 { agent: { workspace: "~/.openclaw/workspace", model: { primary: "lmstudio/minimax-m2.1-gs32" }, }, models: { mode: "merge", providers: { lmstudio: { baseUrl: "http://127.0.0.1:1234/v1", apiKey: "lmstudio", api: "openai-responses", models: [ { id: "minimax-m2.1-gs32", name: "MiniMax M2.1 GS32", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 196608, maxTokens: 8192, }, ], }, }, }, } 提示 如果你设置 dmPolicy: "open"，匹配的 allowFrom 列表必须包含 "*"。 提供商 ID 各不相同（电话号码、用户 ID、频道 ID）。使用提供商文档确认格式。 稍后添加的可选部分：web、browser、ui、discovery、canvasHost、talk、signal、imessage。 参阅提供商和故障排除了解更深入的设置说明。

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 JSON5 配置（支持注释和尾逗号）。 如果文件不存在，OpenClaw 使用安全的默认值（内置 Pi 智能体 + 按发送者分会话 + 工作区 ~/.openclaw/workspace）。通常只在以下情况需要配置： 限制谁可以触发机器人（channels.whatsapp.allowFrom、channels.telegram.allowFrom 等） 控制群组白名单 + 提及行为（channels.whatsapp.groups、channels.telegram.groups、channels.discord.guilds、agents.list[].groupChat） 自定义消息前缀（messages） 设置智能体工作区（agents.defaults.workspace 或 agents.list[].workspace） 调整内置智能体默认值（agents.defaults）和会话行为（session） 设置每个智能体的身份标识（agents.list[].identity） 初次接触配置？ 请查阅配置示例指南，获取带有详细说明的完整示例！ 严格配置验证 OpenClaw 只接受完全匹配 schema 的配置。 未知键、类型错误或无效值会导致 Gateway 网关 拒绝启动以确保安全。 验证失败时： Gateway 网关不会启动。 只允许诊断命令（例如：openclaw doctor、openclaw logs、openclaw health、openclaw status、openclaw service、openclaw help）。 运行 openclaw doctor 查看具体问题。 运行 openclaw doctor --fix（或 --yes）应用迁移/修复。 Doctor 不会写入任何更改，除非你明确选择了 --fix/--yes。 Schema + UI 提示 Gateway 网关通过 config.schema 暴露配置的 JSON Schema 表示，供 UI 编辑器使用。 控制台 UI 根据此 schema 渲染表单，并提供 Raw JSON 编辑器作为应急手段。 ...

“配对"是 OpenClaw 的显式所有者批准步骤。它用于两个地方： 私信配对（谁被允许与机器人对话） 节点配对（哪些设备/节点被允许加入 Gateway 网关网络） 安全上下文：安全 1）私信配对（入站聊天访问） 当渠道配置为私信策略 pairing 时，未知发送者会收到一个短代码，他们的消息不会被处理，直到你批准。 默认私信策略记录在：安全 配对代码： 8 个字符，大写，无歧义字符（0O1I）。 1 小时后过期。机器人仅在创建新请求时发送配对消息（大约每个发送者每小时一次）。 待处理的私信配对请求默认上限为每个渠道 3 个；在一个过期或被批准之前，额外的请求将被忽略。 批准发送者 openclaw pairing list telegram openclaw pairing approve telegram <CODE> 支持的渠道：telegram、whatsapp、signal、imessage、discord、slack。 状态存储位置 存储在 ~/.openclaw/credentials/ 下： 待处理请求：<channel>-pairing.json 已批准允许列表存储：<channel>-allowFrom.json 将这些视为敏感信息（它们控制对你助手的访问）。 2）节点设备配对（iOS/Android/macOS/无头节点） 节点作为 role: node 的设备连接到 Gateway 网关。Gateway 网关创建一个必须被批准的设备配对请求。 批准节点设备 openclaw devices list openclaw devices approve <requestId> openclaw devices reject <requestId> 状态存储位置 存储在 ~/.openclaw/devices/ 下： pending.json（短期；待处理请求会过期） paired.json（已配对设备 + 令牌） 说明 旧版 node.pair.* API（CLI：openclaw nodes pending/approve）是一个单独的 Gateway 网关拥有的配对存储。WS 节点仍然需要设备配对。 相关文档 安全模型 + 提示注入：安全 安全更新（运行 doctor）：更新 渠道配置： Telegram：Telegram WhatsApp：WhatsApp Signal：Signal iMessage：iMessage Discord：Discord Slack：Slack

本仓库通过在专用主机（桌面/服务器）上运行单个 Gateway 网关（主节点）并让客户端连接到它来支持"SSH 远程"。 对于操作员（你/macOS 应用）：SSH 隧道是通用的回退方案。 对于节点（iOS/Android 和未来的设备）：连接到 Gateway WebSocket（LAN/tailnet 或根据需要通过 SSH 隧道）。 核心理念 Gateway WebSocket 绑定到你配置端口的 loopback（默认为 18789）。 对于远程使用，你通过 SSH 转发该 loopback 端口（或使用 tailnet/VPN 减少隧道需求）。 常见的 VPN/tailnet 设置（智能体所在位置） 将 Gateway 网关主机视为"智能体所在的位置"。它拥有会话、身份验证配置文件、渠道和状态。 你的笔记本电脑/桌面（和节点）连接到该主机。 1) tailnet 中始终在线的 Gateway 网关（VPS 或家庭服务器） 在持久主机上运行 Gateway 网关，并通过 Tailscale 或 SSH 访问它。 最佳用户体验： 保持 gateway.bind: "loopback" 并使用 Tailscale Serve 作为控制 UI。 回退方案： 保持 loopback + 从任何需要访问的机器建立 SSH 隧道。 示例： exe.dev（简易 VM）或 Hetzner（生产 VPS）。 当你的笔记本电脑经常休眠但你希望智能体始终在线时，这是理想的选择。 2) 家庭桌面运行 Gateway 网关，笔记本电脑作为远程控制 笔记本电脑不运行智能体。它远程连接： ...

此流程让 macOS 应用作为运行在另一台主机（桌面/服务器）上的 OpenClaw Gateway 网关的完整远程控制。这是应用的 Remote over SSH（远程运行）功能。所有功能——健康检查、语音唤醒转发和 Web Chat——都重用来自 Settings → General 的相同远程 SSH 配置。 模式 Local (this Mac)：一切都在笔记本电脑上运行。不涉及 SSH。 Remote over SSH（默认）：OpenClaw 命令在远程主机上执行。mac 应用使用 -o BatchMode 加上你选择的身份/密钥打开 SSH 连接，并进行本地端口转发。 Remote direct (ws/wss)：无 SSH 隧道。mac 应用直接连接到 Gateway 网关 URL（例如，通过 Tailscale Serve 或公共 HTTPS 反向代理）。 远程传输 远程模式支持两种传输方式： SSH 隧道（默认）：使用 ssh -N -L ... 将 Gateway 网关端口转发到 localhost。Gateway 网关会将节点的 IP 视为 127.0.0.1，因为隧道是 loopback。 Direct (ws/wss)：直接连接到 Gateway 网关 URL。Gateway 网关看到真实的客户端 IP。 远程主机上的先决条件 安装 Node + pnpm 并构建/安装 OpenClaw CLI（pnpm install && pnpm build && pnpm link --global）。 确保 openclaw 在非交互式 shell 的 PATH 中（如需要，请符号链接到 /usr/local/bin 或 /opt/homebrew/bin）。 使用密钥认证打开 SSH。我们推荐使用 Tailscale IP 以实现离开局域网时的稳定可达性。 macOS 应用设置 打开 Settings → General。 在 OpenClaw runs 下，选择 Remote over SSH 并设置： Transport：SSH tunnel 或 Direct (ws/wss)。 SSH target：user@host（可选 :port）。 如果 Gateway 网关在同一局域网上并广播 Bonjour，从发现列表中选择它以自动填充此字段。 Gateway URL（仅 Direct）：wss://gateway.example.ts.net（或本地/局域网使用 ws://...）。 Identity file（高级）：你的密钥路径。 Project root（高级）：用于命令的远程 checkout 路径。 CLI path（高级）：可运行的 openclaw 入口点/二进制文件的可选路径（广播时自动填充）。 点击 Test remote。成功表示远程 openclaw status --json 正确运行。失败通常意味着 PATH/CLI 问题；退出码 127 表示远程找不到 CLI。 健康检查和 Web Chat 现在将自动通过此 SSH 隧道运行。 Web Chat SSH 隧道：Web Chat 通过转发的 WebSocket 控制端口（默认 18789）连接到 Gateway 网关。 Direct (ws/wss)：Web Chat 直接连接到配置的 Gateway 网关 URL。 不再有单独的 WebChat HTTP 服务器。 权限 远程主机需要与本地相同的 TCC 批准（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在该机器上运行新手引导以一次性授予它们。 节点通过 node.list / node.describe 广播其权限状态，以便智能体知道哪些可用。 安全注意事项 优先在远程主机上使用 loopback 绑定，并通过 SSH 或 Tailscale 连接。 如果你将 Gateway 网关绑定到非 loopback 接口，请要求令牌/密码认证。 参见安全和 Tailscale。 WhatsApp 登录流程（远程） 在远程主机上运行 openclaw channels login --verbose。用手机上的 WhatsApp 扫描二维码。 如果认证过期，在该主机上重新运行登录。健康检查会显示关联问题。 故障排除 exit 127 / not found：openclaw 不在非登录 shell 的 PATH 中。将其添加到 /etc/paths、你的 shell rc，或符号链接到 /usr/local/bin//opt/homebrew/bin。 Health probe failed：检查 SSH 可达性、PATH，以及 Baileys 是否已登录（openclaw status --json）。 Web Chat 卡住：确认 Gateway 网关正在远程主机上运行，转发的端口与 Gateway 网关 WS 端口匹配；UI 需要健康的 WS 连接。 节点 IP 显示 127.0.0.1：使用 SSH 隧道时是预期的。如果你想让 Gateway 网关看到真实的客户端 IP，请将 Transport 切换到 Direct (ws/wss)。 Voice Wake：触发短语在远程模式下自动转发；不需要单独的转发器。 通知声音 通过带有 openclaw 和 node.invoke 的脚本为每个通知选择声音，例如： ...

在运行活跃期间，输入指示器会发送到聊天渠道。使用 agents.defaults.typingMode 控制输入指示器何时开始显示，使用 typingIntervalSeconds 控制刷新频率。 默认行为 当 agents.defaults.typingMode 未设置时，OpenClaw 保持旧版行为： 私聊：模型循环开始后立即显示输入指示器。 群聊中被提及：立即显示输入指示器。 群聊中未被提及：仅在消息文本开始流式传输时显示输入指示器。 心跳运行：输入指示器禁用。 模式 将 agents.defaults.typingMode 设置为以下值之一： never — 永远不显示输入指示器。 instant — 模型循环开始后立即显示输入指示器，即使运行最终只返回静默回复令牌。 thinking — 在第一个推理增量时开始显示输入指示器（需要运行时设置 reasoningLevel: "stream"）。 message — 在第一个非静默文本增量时开始显示输入指示器（忽略 NO_REPLY 静默令牌）。 触发时机从晚到早的顺序： never → message → thinking → instant 配置 { agent: { typingMode: "thinking", typingIntervalSeconds: 6, }, } 可以按会话覆盖模式或刷新频率： { session: { typingMode: "message", typingIntervalSeconds: 4, }, } 注意事项 message 模式不会为纯静默回复显示输入指示器（例如用于抑制输出的 NO_REPLY 令牌）。 thinking 仅在运行流式传输推理时触发（reasoningLevel: "stream"）。 如果模型未产生推理增量，则不会显示输入指示器。 无论使用何种模式，心跳运行都不会显示输入指示器。 typingIntervalSeconds 控制的是刷新频率，而非开始时间。 默认值为 6 秒。

本页介绍用于流式输出的调试辅助工具，特别是当提供商将推理混入正常文本时。 运行时调试覆盖 在聊天中使用 /debug 设置仅运行时配置覆盖（内存中，不写入磁盘）。 /debug 默认禁用；通过 commands.debug: true 启用。 当你需要切换不常用的设置而不编辑 openclaw.json 时，这非常方便。 示例： /debug show /debug set messages.responsePrefix="[openclaw]" /debug unset messages.responsePrefix /debug reset /debug reset 清除所有覆盖并返回到磁盘上的配置。 Gateway 网关监视模式 为了快速迭代，在文件监视器下运行 Gateway 网关： pnpm gateway:watch --force 这映射到： tsx watch src/entry.ts gateway --force 在 gateway:watch 后添加任何 Gateway 网关 CLI 标志，它们将在每次重启时传递。 Dev 配置文件 + dev Gateway 网关（–dev） 使用 dev 配置文件来隔离状态，并启动一个安全、可丢弃的调试设置。有两个 --dev 标志： 全局 --dev（配置文件）： 将状态隔离到 ~/.openclaw-dev 下，并将 Gateway 网关端口默认为 19001（派生端口随之移动）。 gateway --dev：告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区（并跳过 BOOTSTRAP.md）。 推荐流程（dev 配置文件 + dev 引导）： ...