🦞 OpenClaw — 个人 AI 助手

去角质！去角质！

OpenClaw 是一个在您自己的设备上运行的_个人 AI 助手_。 它可以在您已有的通讯渠道上回复您（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、BlueBubbles、IRC、Microsoft Teams、Matrix、飞书、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、Zalo 个人版、WebChat）。它可以在 macOS/iOS/Android 上语音对话，并可以渲染您可控制的实时画布。网关只是控制平面——产品本身是助手。

如果您想要一个个性化、单用户的助手，感觉本地化、快速且始终在线，这就是您需要的。

网站 · 文档 · 愿景 · DeepWiki · 入门指南 · 更新 · 展示 · 常见问题 · 向导 · Nix · Docker · Discord

推荐设置：在您的终端中运行引导向导（openclaw onboard）。 该向导会逐步引导您设置网关、工作区、渠道和技能。CLI 向导是推荐的安装路径，适用于 macOS、Linux 和 Windows（通过 WSL2；强烈推荐）。 支持 npm、pnpm 或 bun。 新安装？从这里开始：入门指南

OpenAI	Vercel	Blacksmith	Convex

订阅（OAuth）：

• OpenAI (ChatGPT/Codex)

模型说明：虽然支持许多提供商/模型，但为了获得最佳体验并降低提示注入风险，请使用您可用的最强大的最新一代模型。参见入门指南。

• 模型配置 + CLI：模型
• 认证配置文件轮换（OAuth vs API 密钥）+ 故障转移：模型故障转移

运行环境：Node ≥22。

npm install -g openclaw@latest
# 或：pnpm add -g openclaw@latest

openclaw onboard --install-daemon

该向导会安装网关守护进程（launchd/systemd 用户服务），使其保持运行。

运行环境：Node ≥22。

完整初学者指南（认证、配对、渠道）：入门指南

openclaw onboard --install-daemon

openclaw gateway --port 18789 --verbose

# 发送消息
openclaw message send --to +1234567890 --message "来自 OpenClaw 的问候"

# 与助手对话（可选择回复到任何已连接的渠道：WhatsApp/Telegram/Slack/Discord/Google Chat/Signal/iMessage/BlueBubbles/IRC/Microsoft Teams/Matrix/飞书/LINE/Mattermost/Nextcloud Talk/Nostr/Synology Chat/Tlon/Twitch/Zalo/Zalo 个人版/WebChat）
openclaw agent --message "发布清单" --thinking high

升级？更新指南（并运行 openclaw doctor）。

• stable：标记的发布版本（vYYYY.M.D 或 vYYYY.M.D-<patch>），npm 分发标签 latest。
• beta：预发布标签（vYYYY.M.D-beta.N），npm 分发标签 beta（macOS 应用可能缺失）。
• dev：main 分支的最新提交，npm 分发标签 dev（发布时）。

切换渠道（git + npm）：openclaw update --channel stable|beta|dev。 详情：开发渠道。

推荐使用 pnpm 从源码构建。Bun 可选，用于直接运行 TypeScript。

git clone https://github.com/openclaw/openclaw.git
cd openclaw

pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build

pnpm openclaw onboard --install-daemon

# 开发循环（TS 更改时自动重载）
pnpm gateway:watch

注意：pnpm openclaw ... 直接运行 TypeScript（通过 tsx）。pnpm build 生成 dist/ 用于通过 Node / 打包的 openclaw 二进制文件运行。

OpenClaw 连接到真实的消息界面。将入站私信视为不受信任的输入。

完整安全指南：安全

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

• 私信配对（dmPolicy="pairing" / channels.discord.dmPolicy="pairing" / channels.slack.dmPolicy="pairing"；旧版：channels.discord.dm.policy，channels.slack.dm.policy）：未知发送者会收到一个短配对码，机器人不会处理他们的消息。
• 使用以下命令批准：openclaw pairing approve <channel> <code>（然后发送者会被添加到本地允许列表存储中）。
• 公共入站私信需要显式选择加入：设置 dmPolicy="open" 并在频道允许列表中包含 "*"（allowFrom / channels.discord.allowFrom / channels.slack.allowFrom；旧版：channels.discord.dm.allowFrom，channels.slack.dm.allowFrom）。

运行 openclaw doctor 以显示有风险/配置错误的私信策略。

• 本地优先网关 —— 会话、渠道、工具和事件的单一控制平面。
• 多渠道收件箱 —— WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、BlueBubbles（iMessage）、iMessage（旧版）、IRC、Microsoft Teams、Matrix、飞书、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、Zalo 个人版、WebChat、macOS、iOS/Android。
• 多代理路由 —— 将入站渠道/账户/对等方路由到隔离的代理（工作区 + 每代理会话）。
• 语音唤醒 + 对话模式 —— macOS/iOS 上的唤醒词和 Android 上的连续语音（ElevenLabs + 系统 TTS 回退）。
• 实时画布 —— 代理驱动的可视化工作区，支持 A2UI。
• 一流工具 —— 浏览器、画布、节点、cron、会话和 Discord/Slack 操作。
• 配套应用 —— macOS 菜单栏应用 + iOS/Android 节点。
• 引导 + 技能 —— 向导驱动的设置，包含捆绑/管理/工作区技能。

• 网关 WS 控制平面，包含会话、在线状态、配置、cron、webhooks、控制 UI 和 画布主机。
• CLI 界面：网关、代理、发送、向导 和 医生。
• Pi 代理运行时，支持 RPC 模式，包含工具流和块流。
• 会话模型：main 用于直接聊天，群组隔离，激活模式，队列模式，回复返回。群组规则：群组。
• 媒体管道：图片/音频/视频、转录钩子、大小限制、临时文件生命周期。音频详情：音频。

• 渠道：WhatsApp（Baileys）、Telegram（grammY）、Slack（Bolt）、Discord（discord.js）、Google Chat（Chat API）、Signal（signal-cli）、BlueBubbles（iMessage，推荐）、iMessage（旧版 imsg）、IRC、Microsoft Teams、Matrix、飞书、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、Zalo 个人版、WebChat。
• 群组路由：提及门控、回复标签、每渠道分块和路由。渠道规则：渠道。

• macOS 应用：菜单栏控制平面，语音唤醒/PTT，对话模式覆盖层，WebChat，调试工具，远程网关控制。
• iOS 节点：画布，语音唤醒，对话模式，相机，屏幕录制，Bonjour + 设备配对。
• Android 节点：连接标签页（设置码/手动），聊天会话，语音标签页，画布，相机/屏幕录制，以及 Android 设备命令（通知/位置/SMS/照片/联系人/日历/运动/应用更新）。
• macOS 节点模式：system.run/notify + 画布/相机暴露。

• 浏览器控制：专用的 openclaw Chrome/Chromium，快照，操作，上传，配置文件。
• 画布：A2UI 推送/重置，eval，快照。
• 节点：相机快照/剪辑，屏幕录制，location.get，通知。
• Cron + 唤醒；webhooks；Gmail Pub/Sub。
• 技能平台：捆绑、管理和工作区技能，包含安装门控 + UI。

• 渠道路由，重试策略，和流式/分块。
• 在线状态，输入指示器，和使用跟踪。
• 模型，模型故障转移，和会话修剪。
• 安全和故障排除。

• 控制 UI + WebChat 直接从网关提供。
• Tailscale Serve/Funnel 或 SSH 隧道，支持令牌/密码认证。
• Nix 模式用于声明式配置；基于 Docker 的安装。
• 医生迁移，日志。

WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / BlueBubbles / IRC / Microsoft Teams / Matrix / 飞书 / LINE / Mattermost / Nextcloud Talk / Nostr / Synology Chat / Tlon / Twitch / Zalo / Zalo 个人版 / WebChat
               │
               ▼
┌───────────────────────────────┐
│            网关               │
│         （控制平面）          │
│      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）。
• 语音唤醒 + 对话模式 —— macOS/iOS 上的唤醒词以及 Android 上的连续语音。
• 节点 —— 画布、相机快照/剪辑、屏幕录制、location.get、通知，以及仅限 macOS 的 system.run/system.notify。

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 要求密码。
• 除非设置了 gateway.auth.mode: "password"，否则 Funnel 拒绝启动。
• 可选：gateway.tailscale.resetOnExit 用于在关闭时撤销 Serve/Funnel。

详情：Tailscale 指南 · Web 界面

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

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

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

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 方法）持久化每会话切换， alongside thinkingLevel、verboseLevel、model、sendPolicy 和 groupActivation。

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

• 使用这些工具在不跳转聊天界面的情况下协调跨会话的工作。
• sessions_list —— 发现活动会话（代理）及其元数据。
• sessions_history —— 获取会话的转录日志。
• sessions_send —— 向另一个会话发送消息；可选的回复回传乒乓 + 宣布步骤（REPLY_SKIP、ANNOUNCE_SKIP）。

详情：会话工具

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 —— 群组激活切换（仅限群组）

仅网关就能提供出色的体验。所有应用都是可选的，并添加额外功能。

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

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

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

• 通过网关 WebSocket 作为节点配对（设备配对）。
• 语音触发转发 + 画布界面。
• 通过 openclaw nodes … 控制。

运行手册：iOS 连接。

• 通过设备配对（openclaw devices ...）作为 WS 节点配对。
• 公开连接/聊天/语音标签页以及画布、相机、屏幕捕获和 Android 设备命令族。
• 运行手册：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-6",
  },
}

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

• **默认：**工具在主机上为 main 会话运行，因此当只有您使用时，代理拥有完全访问权限。
• 群组/渠道安全：设置 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 + 沙箱 · 沙箱配置

• 链接设备：pnpm openclaw channels login（将凭证存储在 ~/.openclaw/credentials 中）。
• 通过 channels.whatsapp.allowFrom 允许列表谁可以与助手对话。
• 如果设置了 channels.whatsapp.groups，它将成为群组允许列表；包含 "*" 以允许所有。

• 设置 TELEGRAM_BOT_TOKEN 或 channels.telegram.botToken（环境变量优先）。
• 可选：设置 channels.telegram.groups（使用 channels.telegram.groups."*".requireMention）；设置后，它是群组允许列表（包含 "*" 以允许所有）。还有 channels.telegram.allowFrom 或 channels.telegram.webhookUrl + channels.telegram.webhookSecret 根据需要。

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

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

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

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

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

• 推荐的 iMessage 集成。
• 配置 channels.bluebubbles.serverUrl + channels.bluebubbles.password 和 webhook（channels.bluebubbles.webhookPath）。
• BlueBubbles 服务器在 macOS 上运行；网关可以在 macOS 或其他地方运行。

• 通过 imsg 的仅限 macOS 的旧版集成（必须登录 Messages）。
• 如果设置了 channels.imessage.groups，它将成为群组允许列表；包含 "*" 以允许所有。

• 配置 Teams 应用 + Bot Framework，然后添加 msteams 配置部分。
• 通过 msteams.allowFrom 允许列表谁可以对话；通过 msteams.groupAllowFrom 或 msteams.groupPolicy: "open" 进行群组访问。

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

浏览器控制（可选）：

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

当您完成引导流程并需要更深入的参考时，使用这些文档。

• 从文档索引开始，了解导航和"内容在哪里"。
• 阅读架构概述，了解网关 + 协议模型。
• 使用完整配置参考，当您需要每个键和示例时。
• 按照操作运行手册运行网关。
• 了解控制 UI/Web 界面的工作原理以及如何安全地暴露它们。
• 了解通过 SSH 隧道或 tailnet 的远程访问。
• 按照引导向导流程进行引导设置。
• 通过 webhook 界面连接外部触发器。
• 设置 Gmail Pub/Sub 触发器。
• 了解 macOS 菜单栏配套应用的详细信息。
• 平台指南：Windows（WSL2）、Linux、macOS、iOS、Android
• 使用故障排除指南调试常见故障。
• 在暴露任何内容之前查看安全指南。

• 发现 + 传输
• Bonjour/mDNS
• 网关配对
• 远程网关 README
• 控制 UI
• 仪表板

• 健康检查
• 网关锁定
• 后台进程
• 浏览器故障排除（Linux）
• 日志

• 代理循环
• 在线状态
• TypeBox 模式
• RPC 适配器
• 队列

• 技能配置
• 默认 AGENTS
• 模板：AGENTS
• 模板：BOOTSTRAP
• 模板：IDENTITY
• 模板：SOUL
• 模板：TOOLS
• 模板：USER

• macOS 开发设置
• macOS 菜单栏
• macOS 语音唤醒
• iOS 节点
• Android 节点
• Windows（WSL2）
• Linux 应用

• docs.openclaw.ai/gmail-pubsub

OpenClaw 是为 Molty 构建的，一个太空龙虾 AI 助手。🦞 由 Peter Steinberger 和社区创建。

• openclaw.ai
• soul.md
• steipete.me
• @openclaw

参见 CONTRIBUTING.md 了解指南、维护者和如何提交 PR。 欢迎 AI/vibe-coded PR！🤖

特别感谢 Mario Zechner 的支持和 pi-mono。 Special thanks to Adam Doppelt for lobster.bot.