OpenClaw 个人 AI 助手安装部署指南

安全默认设置（私信访问）

OpenClaw 会连接真实的即时通讯平台。请将所有入站私信视为不可信输入。

完整安全指南：安全

Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Google Chat/Slack 的默认行为：

• 私信配对（dmPolicy="pairing" / channels.discord.dm.policy="pairing" / channels.slack.dm.policy="pairing"）：未知发件人将收到一个简短的配对码，机器人不会处理其消息。
• 通过以下命令批准：openclaw pairing approve <channel> <code>（随后该发件人将被加入本地允许列表）。
• 公开接收私信需显式启用：设置 dmPolicy="open" 并在渠道允许列表中包含 "*"（allowFrom / channels.discord.dm.allowFrom / channels.slack.dm.allowFrom）。

运行 openclaw doctor 可检测存在风险或配置不当的私信策略。

工作原理（简述）

WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / BlueBubbles / Microsoft Teams / Matrix / Zalo / Zalo Personal / WebChat │ ▼ ┌───────────────────────────────┐ │ 网关 (Gateway) │ │ (控制平面) │ │ ws://127.0.0.1:18789 │ └──────────────┬────────────────┘ │ ├─ Pi 代理 (RPC) ├─ CLI (openclaw …) ├─ WebChat UI ├─ macOS 应用 └─ iOS / Android 节点 

关键子系统

• 网关 WebSocket 网络 —— 单一 WS 控制平面，用于客户端、工具和事件（以及运维：网关操作手册）。
• Tailscale 暴露 —— 通过 Serve/Funnel 提供网关仪表盘 + WS（远程访问：远程）。
• 浏览器控制 —— openclaw 管理的 Chrome/Chromium，支持 CDP 控制。
• 画布 + A2UI —— 代理驱动的可视化工作区（A2UI 主机：画布/A2UI）。
• 语音唤醒 + 对话模式 —— 始终在线的语音和持续对话。
• 节点 —— 画布、摄像头拍照/录像、屏幕录制、location.get、通知，以及 macOS 专属的 system.run/system.notify。

Tailscale 访问（网关仪表盘）

OpenClaw 可自动配置 Tailscale Serve（仅限 tailnet 内部）或 Funnel（公开），同时网关仍绑定到本地回环地址。配置 gateway.tailscale.mode：

• off：不启用 Tailscale 自动化（默认）。
• serve：通过 tailscale serve 提供仅限 tailnet 的 HTTPS（默认使用 Tailscale 身份头）。
• funnel：通过 tailscale funnel 提供公开 HTTPS（需共享密码认证）。

注意事项：

• 启用 Serve/Funnel 时，gateway.bind 必须保持为 loopback（OpenClaw 会强制执行）。
• 通过设置 gateway.auth.mode: "password" 或 gateway.auth.allowTailscale: false，可强制 Serve 要求密码。
• Funnel 除非设置了 gateway.auth.mode: "password"，否则拒绝启动。
• 可选：设置 gateway.tailscale.resetOnExit，在关闭时自动撤销 Serve/Funnel。

详情：Tailscale 指南 · Web 界面

远程网关（Linux 很棒）

在小型 Linux 实例上运行网关完全可行。客户端（macOS 应用、CLI、WebChat）可通过 Tailscale Serve/Funnel 或 SSH 隧道连接，并且仍可在需要时配对设备节点（macOS/iOS/Android）以执行设备本地操作。

• 网关主机 默认运行 exec 工具和渠道连接。
• 设备节点 通过 node.invoke 运行设备本地操作（system.run、摄像头、屏幕录制、通知）。
  简而言之：exec 在网关所在位置运行；设备操作在设备所在位置运行。

详情：远程访问 · 节点 · 安全

通过网关协议实现 macOS 权限

macOS 应用可运行在节点模式下，并通过网关 WebSocket（node.list / node.describe）广播其能力与权限映射。客户端随后可通过 node.invoke 执行本地操作：

• system.run 运行本地命令并返回 stdout/stderr/退出码；设置 needsScreenRecording: true 以要求屏幕录制权限（否则将返回 PERMISSION_MISSING）。
• system.notify 发送用户通知，若通知权限被拒绝则失败。
• canvas.*、camera.*、screen.record 和 location.get 也通过 node.invoke 路由，并遵循 TCC 权限状态。

提升权限的 bash（主机权限）与 macOS TCC 是分开的：

• 使用 /elevated on|off 在启用并加入允许列表后，按会话切换提升访问权限。
• 网关通过 sessions.patch（WS 方法）持久化每会话的切换状态，同时持久化 thinkingLevel、verboseLevel、model、sendPolicy 和 groupActivation。

详情：节点 · macOS 应用 · 网关协议

代理间通信（sessions_* 工具）

• 使用这些工具在会话间协调工作，无需在不同聊天界面间切换。
• sessions_list —— 发现活跃会话（代理）及其元数据。
• sessions_history —— 获取指定会话的对话记录。
• sessions_send —— 向另一个会话发送消息；可选回复 ping-pong 和公告步骤（REPLY_SKIP、ANNOUNCE_SKIP）。

详情：会话工具

技能注册表（ClawHub）

ClawHub 是一个极简的技能注册表。启用 ClawHub 后，代理可自动搜索技能并在需要时拉取新技能。

ClawHub

聊天命令

在 WhatsApp/Telegram/Slack/Google Chat/Microsoft Teams/WebChat 中发送以下命令（群组命令仅限所有者）：

• /status —— 简洁会话状态（模型 + 令牌数，如有则显示成本）
• /new 或 /reset —— 重置会话
• /compact —— 压缩会话上下文（摘要）
• /think <level> —— off|minimal|low|medium|high|xhigh（仅限 GPT-5.2 + Codex 模型）
• /verbose on|off
• /usage off|tokens|full —— 每次回复的用量页脚
• /restart —— 重启网关（群组中仅限所有者）
• /activation mention|always —— 切换群组激活模式（仅限群组）

应用（可选）

仅网关即可提供出色的体验。所有应用均为可选，用于添加额外功能。

如果您计划构建/运行配套应用，请遵循以下平台操作手册。

macOS（OpenClaw.app）（可选）

• 网关和健康状态的菜单栏控制。
• 语音唤醒 + 按键通话覆盖层。
• WebChat + 调试工具。
• 通过 SSH 控制远程网关。

注意：macOS 权限需签名构建才能在重建后保留（参见 docs/mac/permissions.md）。

iOS 节点（可选）

• 通过 Bridge 配对为节点。
• 语音触发转发 + 画布界面。
• 通过 openclaw nodes … 控制。

操作手册：iOS 连接。

Android 节点（可选）

• 通过与 iOS 相同的 Bridge 和配对流程配对。
• 提供画布、摄像头和屏幕捕获命令。
• 操作手册：Android 连接。

代理工作区 + 技能

• 工作区根目录：~/.openclaw/workspace（可通过 agents.defaults.workspace 配置）。
• 注入的提示文件：AGENTS.md、SOUL.md、TOOLS.md。
• 技能：~/.openclaw/workspace/skills/<skill>/SKILL.md。

配置

最小化的 ~/.openclaw/openclaw.json（模型 + 默认值）：

{
  agent: {
    model: "anthropic/claude-opus-4-5"
  }
}

完整配置参考（所有键 + 示例）

安全模型（重要）

• 默认：工具在主会话的主机上运行，因此当只有您自己使用时，代理拥有完全访问权限。
• 群组/渠道安全：设置 agents.defaults.sandbox.mode: "non-main"，使非主会话（群组/渠道）在每会话 Docker 沙箱中运行；此时 bash 在这些会话的 Docker 中运行。
• 沙箱默认：允许 bash、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn；禁止 browser、canvas、nodes、cron、discord、gateway。

详情：安全指南 · Docker + 沙箱 · 沙箱配置

WhatsApp

• 链接设备：pnpm openclaw channels login（凭据存储在 ~/.openclaw/credentials）。
• 通过 channels.whatsapp.allowFrom 设置允许与助手对话的用户。
• 若设置了 channels.whatsapp.groups，则成为群组允许列表；包含 "*" 以允许所有群组。

Telegram

• 设置 TELEGRAM_BOT_TOKEN 或 channels.telegram.botToken（环境变量优先）。
• 可选：设置 channels.telegram.groups（配合 channels.telegram.groups."*".requireMention）；设置后即为群组允许列表（包含 "*" 以允许所有群组）。也可根据需要设置 channels.telegram.allowFrom 或 channels.telegram.webhookUrl。

{ channels: { telegram: { botToken: "123456:ABCDEF" } } }

Slack

• 设置 SLACK_BOT_TOKEN + SLACK_APP_TOKEN（或 channels.slack.botToken + channels.slack.appToken）。

Discord

• 设置 DISCORD_BOT_TOKEN 或 channels.discord.token（环境变量优先）。
• 可选：设置 commands.native、commands.text 或 commands.useAccessGroups，以及根据需要设置 channels.discord.dm.allowFrom、channels.discord.guilds 或 channels.discord.mediaMaxMb。

{ channels: { discord: { token: "1234abcd" } } }

Signal

• 需要 signal-cli 和 channels.signal 配置段。

iMessage

• 仅限 macOS；需登录 Messages。
• 若设置了 channels.imessage.groups，则成为群组允许列表；包含 "*" 以允许所有群组。

Microsoft Teams

• 配置 Teams 应用 + Bot Framework，然后添加 msteams 配置段。
• 通过 msteams.allowFrom 设置允许对话的用户；通过 msteams.groupAllowFrom 或 msteams.groupPolicy: "open" 设置群组访问。

WebChat

• 使用网关 WebSocket；无需单独的 WebChat 端口/配置。

浏览器控制（可选）：

{ browser: { enabled: true, color: "#FF4500" } }

文档

完成初始化流程后，如需深入参考，请使用以下文档。

• 从文档索引开始导航和了解'内容分布'
• 阅读架构概述以了解网关 + 协议模型
• 需要所有键和示例时，使用完整配置参考
• 按照运维手册规范运行网关
• 了解控制 UI/Web 界面的工作原理及安全暴露方法
• 理解通过 SSH 隧道或 tailnet 的远程访问
• 遵循初始化向导流程进行引导式设置
• 通过 webhook 界面连接外部触发器
• 设置 Gmail Pub/Sub 触发器
• 了解 macOS 菜单栏配套应用的详细信息
• 平台指南：Windows（WSL2）、Linux、macOS、iOS、Android
• 通过故障排除指南调试常见问题
• 在暴露任何内容前，务必查阅安全指南