模型（选择+认证）

Config + CLI 模型： 模型

认证配置文件轮换（OAuth 与 API 密钥）+ 回退： 模型故障切换

安装（推荐）

运行时间： 节点≥22。

npm install -g openclaw@latest

# or: pnpm add -g openclaw@latest

openclaw onboard --install-daemon

向导安装了 Gateway daemon（launchd/systemd 用户服务），使其保持运行。

快速入门（简而言之;DR）

运行时间： 节点≥22。

完整入门指南（认证、配对、频道）： 入门指南

openclaw onboard --install-daemon

openclaw gateway --port 18789 --verbose

# Send a message

openclaw message send --to +1234567890 --message "Hello from OpenClaw"

# Talk to the assistant (optionally deliver back to any connected channel: WhatsApp/Telegram/Slack/Discord/Google Chat/Signal/iMessage/BlueBubbles/IRC/Microsoft Teams/Matrix/Feishu/LINE/Mattermost/Nextcloud Talk/Nostr/Synology Chat/Tlon/Twitch/Zalo/Zalo Personal/WebChat)

openclaw agent --message "Ship checklist" --thinking high

开发渠道

稳定 ：带标签的发布（vYYYY.M.D 或 vYYYY.M.D-<patch>），npm dist-tag  最新 。

测试版：预发布标签（vYYYY.M.D-beta.N），npm dist-tag beta（macOS 应用可能缺失）。

开发者：主项目负责人，NPM 负责人，发布时担任非专业负责人。

切换频道（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 # auto-installs UI deps on first run

pnpm build

pnpm openclaw onboard --install-daemon

# Dev loop (auto-reload on TS changes)

pnpm gateway:watch

注：pnpm openclaw ...... 直接运行 TypeScript（通过 tsx）。PNPM 构建生成 dist/，通过 Node / 打包的 openclaw 二进制文件运行。

安全默认设置（DM 访问）

OpenClaw 连接真实的消息页面。把收到的私信当作不可信的输入 。

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

DM 配对 （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 来发现有风险或配置错误的 DM 策略。

Tailscale 访问（Gateway 仪表盘）

OpenClaw 可以自动配置 Tailscale Serve（仅 tailnet）或 Funnel（公开），而网关则保持绑定回环。配置 gateway.tailscale.mode：

关闭 ：无 Tailscale 自动化（默认）。

serve：仅通过 tailscale 服务的 HTTPS（默认使用 Tailscale 身份头）。

漏斗 ：通过 Tailscale Funnel 公开 HTTPS（需要共享密码认证）。

注释：

当 Serve/Funnel 启用时，gateway.bind 必须保持循环 （OpenClaw 强制执行）。

可以通过设置 gateway.auth.mode 强制要求密码：“password” 或 gateway.auth.allowTailscale: false 。

漏斗拒绝启动，除非设置了 gateway.auth.mode： “password”。

可选：gateway.tailscale.resetOnExit，在关闭时撤销 Serve/Funnel。

远程网关（Linux 很棒）

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

Gateway 主机默认运行执行工具和通道连接。

设备节点通过 node.invoke 执行设备本地作（system.run、摄像头、屏幕录制、通知）。简而言之：执行官在门户所在地运营;设备作运行在设备所在的位置。

macOS 通过 Gateway 协议获取权限

macOS 应用可以在节点模式下运行，并通过 Gateway WebSocket（node.list / node.describe）宣传其功能 + 权限映射。客户端随后可以通过 node.invoke 执行本地作：

system.run 运行本地命令并返回 stdout/stderr/exit 代码;set needsScreenRecording：true，要求屏幕录制权限（否则会 PERMISSION_MISSING）。

System.notify 会发布用户通知，如果通知被拒绝则会失败。

canvas.*、camera.*、screen.record 和 location.get 也通过 node.invoke 路由，并遵循 TCC 权限状态。

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

使用 /elevated on|off 来切换每场会话的提升访问，当启用 + 允许列表时。

Gateway 通过 sessions.patch（WS 方法）与 thinkingLevel、verboseLevel、model、sendPolicy 和 groupActivate 一起，维持了每会话的切换。

代理对代理（sessions_* 工具）

利用这些资源在不同会话间协调工作，避免在聊天界面间跳跃。

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 — 重启网关（组中仅限所有者）

/激活提及|始终  — 组激活切换（仅限组组）

应用（可选）

仅《Gateway》就带来了极佳的体验。所有应用都是可选的，并增加了额外功能。

如果你打算构建/运行配套应用，请按照下面的平台运行手册作。

macOS（OpenClaw.app）（可选）

Gateway 和生命值的菜单栏控制。

语音唤醒+按键通话叠加。

WebChat + 调试工具。

通过 SSH 远程网关控制。

注意：签名构建是 macOS 权限跨重建保持的前提条件（参见 docs/mac/permissions.md）。

iOS 节点（可选）

作为网关 WebSocket 上的节点配对（设备配对）。

语音触发转发 + Canvas 表面。

通过 openclaw 节点控制......

运行手册：iOS 连接 。

Android 节点（可选）

通过设备配对（openclaw 设备等 ）作为 WS 节点配对。

它展示了 Connect/聊天/语音标签页，以及 Canvas、摄像头、屏幕录制和 Android 设备命令系列。

运行手册：Android 连接 。

代理工作空间+技能

Workspace root：~/.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",

  },

}

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

安全模型（重要）

默认： 主会话工具会在主机上运行，所以当只有你一个人时，代理可以完全访问。

组/通道安全： 设置为 agents.defaults.sandbox.mode: "non-main" 在每个会话的 Docker 沙箱中运行非主会话 （组/通道）;bash 随后在 Docker 中运行这些会话。

沙盒默认值： 允许列表 bash、process、 读取 、 写 、 编辑 、sessions_list、sessions_history、sessions_send、sessions_spawn;否认者浏览器 、Canvas、 节点 、Cron、Discord、 网关 。

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

WhatsApp

设备链接：pnpm openclaw 频道登录 （信用记录存储在 ~/.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

设置 DISCORD_BOT_TOKEN 或 channels.discord.token（env wins）。

可选：设置 commands.native、commands.text 或 commands.useAccessGroups，以及 channels.discord.allowFrom、channels.discord.guilds 或 channels.discord.mediaMaxMb。

{

  channels: {

    discord: {

      token: "1234abcd",

    },

  },

}

信号

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

BlueBubbles（iMessage）

推荐 iMessage 集成。

配置 channels.bluebubbles.serverUrl + channels.bluebubbles.password 和一个 webhook（ channels.bluebubbles.webhookPath ）。

BlueBubbles 服务器运行在 macOS 上;网关可以在 macOS 或其他平台运行。

iMessage（遗产）

通过 imsg 实现的仅限 macOS 的旧式集成（消息必须登录）。

如果设置为 channels.imessage.groups，则会变成组允许列表;包含 “*” 以允许所有。

Microsoft Teams

配置一个 Teams 应用 + 机器人框架，然后添加 msteams 配置部分。

允许列表，谁可以通过 msteams.allowFrom 聊天;通过 msteams.groupAllowFrom 或 msteams.groupPolicy（“open”）访问组。

网络聊天

使用 Gateway WebSocket;没有单独的 WebChat 端口/配置。

浏览器控制（可选）：

{

  browser: {

    enabled: true,

    color: "#FF4500",

  },

}