Platforms

支持概览 角色：配套节点应用（Android 不托管 Gateway 网关）。 需要 Gateway 网关：是（在 macOS、Linux 或通过 WSL2 的 Windows 上运行）。 安装：入门指南 + 配对。 Gateway 网关：操作手册 + 配置。 协议：Gateway 网关协议（节点 + 控制平面）。 系统控制 系统控制（launchd/systemd）位于 Gateway 网关主机上。参见 Gateway 网关。 连接操作手册 Android 节点应用 ⇄（mDNS/NSD + WebSocket）⇄ Gateway 网关 Android 直接连接到 Gateway 网关 WebSocket（默认 ws://<host>:18789）并使用 Gateway 网关拥有的配对。 前置条件 你可以在"主"机器上运行 Gateway 网关。 Android 设备/模拟器可以访问 Gateway 网关 WebSocket： 使用 mDNS/NSD 的同一局域网，或 使用 Wide-Area Bonjour / unicast DNS-SD 的同一 Tailscale tailnet（见下文），或 手动 Gateway 网关主机/端口（回退方案） 你可以在 Gateway 网关机器上运行 CLI（openclaw）（或通过 SSH）。 1）启动 Gateway 网关 openclaw gateway --port 18789 --verbose 在日志中确认你看到类似内容： ...

macOS 应用使用 WKWebView 嵌入一个智能体控制的 Canvas 面板。它是一个用于 HTML/CSS/JS、A2UI 和小型交互式界面的轻量级可视化工作区。 Canvas 存储位置 Canvas 状态存储在 Application Support 下： ~/Library/Application Support/OpenClaw/canvas/<session>/... Canvas 面板通过自定义 URL 方案提供这些文件： openclaw-canvas://<session>/<path> 示例： openclaw-canvas://main/ → <canvasRoot>/main/index.html openclaw-canvas://main/assets/app.css → <canvasRoot>/main/assets/app.css openclaw-canvas://main/widgets/todo/ → <canvasRoot>/main/widgets/todo/index.html 如果根目录下没有 index.html，应用会显示一个内置脚手架页面。 面板行为 无边框、可调整大小的面板，锚定在菜单栏（或鼠标光标）附近。 记住每个会话的大小/位置。 当本地 canvas 文件更改时自动重新加载。 一次只显示一个 Canvas 面板（根据需要切换会话）。 可以从设置 → 允许 Canvas 禁用 Canvas。禁用时，canvas 节点命令返回 CANVAS_DISABLED。 智能体 API 接口 Canvas 通过 Gateway 网关 WebSocket 暴露，因此智能体可以： 显示/隐藏面板 导航到路径或 URL 执行 JavaScript 捕获快照图像 CLI 示例： openclaw nodes canvas present --node <id> openclaw nodes canvas navigate --node <id> --url "/" openclaw nodes canvas eval --node <id> --js "document.title" openclaw nodes canvas snapshot --node <id> 注意事项： ...

可用性：内部预览。iOS 应用尚未公开分发。 功能 通过 WebSocket（LAN 或 tailnet）连接到 Gateway 网关。 暴露节点能力：Canvas、屏幕快照、相机捕获、位置、对话模式、语音唤醒。 接收 node.invoke 命令并报告节点状态事件。 要求 Gateway 网关运行在另一台设备上（macOS、Linux 或通过 WSL2 的 Windows）。 网络路径： 通过 Bonjour 的同一 LAN，或 通过单播 DNS-SD 的 Tailnet（示例域：openclaw.internal.），或 手动主机/端口（备选）。 快速开始（配对 + 连接） 启动 Gateway 网关： openclaw gateway --port 18789 在 iOS 应用中，打开设置并选择一个已发现的 Gateway 网关（或启用手动主机并输入主机/端口）。 在 Gateway 网关主机上批准配对请求： openclaw nodes pending openclaw nodes approve <requestId> 验证连接： openclaw nodes status openclaw gateway call node.list --params "{}" 发现路径 Bonjour（LAN） Gateway 网关在 local. 上广播 _openclaw-gw._tcp。iOS 应用会自动列出这些。 ...

Gateway 网关在 Linux 上完全支持。Node 是推荐的运行时。 不推荐 Bun 用于 Gateway 网关（WhatsApp/Telegram 存在 bug）。 原生 Linux 配套应用已在计划中。如果你想帮助构建，欢迎贡献。 新手快速路径（VPS） 安装 Node 22+ npm i -g openclaw@latest openclaw onboard --install-daemon 从你的笔记本电脑：ssh -N -L 18789:127.0.0.1:18789 <user>@<host> 打开 http://127.0.0.1:18789/ 并粘贴你的令牌 分步 VPS 指南：exe.dev 安装 入门指南 安装与更新 可选流程：Bun（实验性）、Nix、Docker Gateway 网关 Gateway 网关运行手册 配置 Gateway 网关服务安装（CLI） 使用以下任一方式： openclaw onboard --install-daemon 或： openclaw gateway install 或： openclaw configure 出现提示时选择 Gateway service。 修复/迁移： openclaw doctor 系统控制（systemd 用户单元） OpenClaw 默认安装 systemd 用户服务。对于共享或常驻服务器使用系统 服务。完整的单元示例和指南 在 Gateway 网关运行手册 中。 ...

此应用通常从 scripts/package-mac-app.sh 构建，该脚本目前会： 设置稳定的调试 Bundle 标识符：ai.openclaw.mac.debug 使用该 Bundle ID 写入 Info.plist（可通过 BUNDLE_ID=... 覆盖） 调用 scripts/codesign-mac-app.sh 对主二进制文件和应用包进行签名，使 macOS 将每次重新构建视为相同的已签名包，并保留 TCC 权限（通知、辅助功能、屏幕录制、麦克风、语音）。要获得稳定的权限，请使用真实签名身份；临时签名是可选的且不稳定（参阅 macOS 权限）。 默认使用 CODESIGN_TIMESTAMP=auto；为 Developer ID 签名启用受信任的时间戳。设置 CODESIGN_TIMESTAMP=off 可跳过时间戳（离线调试构建）。 将构建元数据注入 Info.plist：OpenClawBuildTimestamp（UTC）和 OpenClawGitCommit（短哈希），以便"关于"面板可以显示构建信息、git 信息和调试/发布渠道。 打包需要 Node 22+：脚本会运行 TS 构建和 Control UI 构建。 从环境变量中读取 SIGN_IDENTITY。将 export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"（或你的 Developer ID Application 证书）添加到 shell 配置文件中，以始终使用你的证书签名。临时签名需要通过 ALLOW_ADHOC_SIGNING=1 或 SIGN_IDENTITY="-" 显式启用（不建议用于权限测试）。 签名后运行 Team ID 审计，如果应用包内的任何 Mach-O 文件由不同的 Team ID 签名则会失败。设置 SKIP_TEAM_ID_CHECK=1 可跳过此检查。 用法 # 从仓库根目录 scripts/package-mac-app.sh # 自动选择身份；未找到时报错 SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh # 真实证书 ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh # 临时签名（权限不会持久化） SIGN_IDENTITY="-" scripts/package-mac-app.sh # 显式临时签名（同样的限制） DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh # 仅限开发的 Sparkle Team ID 不匹配解决方案 临时签名注意事项 使用 SIGN_IDENTITY="-"（临时签名）签名时，脚本会自动禁用强化运行时（--options runtime）。这是为了防止应用在尝试加载不共享相同 Team ID 的嵌入式框架（如 Sparkle）时崩溃。临时签名还会破坏 TCC 权限持久化；参阅 macOS 权限 了解恢复步骤。 ...

OpenClaw.app 不再捆绑 Node/Bun 或 Gateway 网关运行时。macOS 应用期望有一个外部的 openclaw CLI 安装，不会将 Gateway 网关作为子进程启动，而是管理一个每用户的 launchd 服务来保持 Gateway 网关运行（或者如果已有本地 Gateway 网关正在运行，则连接到现有的）。 安装 CLI（本地模式必需） 你需要在 Mac 上安装 Node 22+，然后全局安装 openclaw： npm install -g openclaw@<version> macOS 应用的安装 CLI按钮通过 npm/pnpm 运行相同的流程（不推荐使用 bun 作为 Gateway 网关运行时）。 Launchd（Gateway 网关作为 LaunchAgent） 标签： bot.molt.gateway（或 bot.molt.<profile>；旧版 com.openclaw.* 可能仍然存在） Plist 位置（每用户）： ~/Library/LaunchAgents/bot.molt.gateway.plist （或 ~/Library/LaunchAgents/bot.molt.<profile>.plist） 管理者： macOS 应用在本地模式下拥有 LaunchAgent 的安装/更新权限。 CLI 也可以安装它：openclaw gateway install。 行为： “OpenClaw Active"启用/禁用 LaunchAgent。 应用退出不会停止 Gateway 网关（launchd 保持其存活）。 如果 Gateway 网关已经在配置的端口上运行，应用会连接到它而不是启动新的。 日志： ...

macOS 应用默认通过 launchd 管理 Gateway 网关，不会将 Gateway 网关作为子进程生成。它首先尝试连接到配置端口上已运行的 Gateway 网关；如果无法访问，它会通过外部 openclaw CLI（无嵌入式运行时）启用 launchd 服务。这为你提供了可靠的登录时自动启动和崩溃后重启。 子进程模式（由应用直接生成 Gateway 网关）目前未使用。 如果你需要与 UI 更紧密的耦合，请在终端中手动运行 Gateway 网关。 默认行为（launchd） 应用安装标记为 bot.molt.gateway 的按用户 LaunchAgent （使用 --profile/OPENCLAW_PROFILE 时为 bot.molt.<profile>；支持旧版 com.openclaw.*）。 当启用本地模式时，应用确保 LaunchAgent 已加载，并 在需要时启动 Gateway 网关。 日志写入 launchd Gateway 网关日志路径（在调试设置中可见）。 常用命令： launchctl kickstart -k gui/$UID/bot.molt.gateway launchctl bootout gui/$UID/bot.molt.gateway 运行命名配置文件时，将标签替换为 bot.molt.<profile>。 未签名的开发构建 scripts/restart-mac.sh --no-sign 用于在没有签名密钥时的快速本地构建。为了防止 launchd 指向未签名的中继二进制文件，它： 写入 ~/.openclaw/disable-launchagent。 已签名运行的 scripts/restart-mac.sh 会在标记存在时清除此覆盖。要手动重置： rm ~/.openclaw/disable-launchagent 仅连接模式 要强制 macOS 应用永不安装或管理 launchd，请使用 --attach-only（或 --no-launchd）启动它。这会设置 ~/.openclaw/disable-launchagent， 因此应用只会连接到已运行的 Gateway 网关。你可以在调试设置中切换相同的 行为。 ...

如何从菜单栏应用查看关联渠道是否健康。 菜单栏 状态圆点现在反映 Baileys 健康状态： 绿色：已关联 + socket 最近已打开。 橙色：正在连接/重试。 红色：已登出或探测失败。 第二行显示"linked · auth 12m"或显示失败原因。 “Run Health Check"菜单项触发按需探测。 设置 通用选项卡新增健康卡片，显示：关联认证时间、会话存储路径/数量、上次检查时间、上次错误/状态码，以及运行健康检查/显示日志按钮。 使用缓存快照，因此 UI 立即加载，离线时优雅降级。 渠道选项卡显示渠道状态 + WhatsApp/Telegram 的控制（登录二维码、登出、探测、上次断开/错误）。 探测工作原理 应用每约 60 秒和按需时通过 ShellExecutor 运行 openclaw health --json。探测加载凭证并报告状态，不发送消息。 分别缓存上次成功的快照和上次错误以避免闪烁；显示每个的时间戳。 有疑问时 你仍然可以使用 Gateway 网关健康 中的 CLI 流程（openclaw status、openclaw status --deep、openclaw health --json），并在 /tmp/openclaw/openclaw-*.log 中跟踪 web-heartbeat / web-reconnect。

本指南涵盖从源代码构建和运行 OpenClaw macOS 应用程序的必要步骤。 前置条件 在构建应用之前，确保你已安装以下内容： Xcode 26.2+：Swift 开发所需。 Node.js 22+ & pnpm：Gateway 网关、CLI 和打包脚本所需。 1. 安装依赖 安装项目范围的依赖： pnpm install 2. 构建和打包应用 要构建 macOS 应用并将其打包到 dist/OpenClaw.app，运行： ./scripts/package-mac-app.sh 如果你没有 Apple Developer ID 证书，脚本将自动使用 ad-hoc 签名（-）。 有关开发运行模式、签名标志和 Team ID 故障排除，请参阅 macOS 应用 README： https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md 注意：Ad-hoc 签名的应用可能会触发安全提示。如果应用立即崩溃并显示"Abort trap 6"，请参阅故障排除部分。 3. 安装 CLI macOS 应用期望全局安装 openclaw CLI 来管理后台任务。 安装方法（推荐）： 打开 OpenClaw 应用。 转到 General 设置标签页。 点击 “Install CLI”。 或者，手动安装： npm install -g openclaw@<version> 故障排除 构建失败：工具链或 SDK 不匹配 macOS 应用构建期望最新的 macOS SDK 和 Swift 6.2 工具链。 ...

macOS 权限授予是脆弱的。TCC 将权限授予与应用的代码签名、Bundle 标识符和磁盘路径关联。如果其中任何一项发生变化，macOS 会将该应用视为新应用，可能会丢弃或隐藏权限提示。 稳定权限的要求 相同路径：从固定位置运行应用（对于 OpenClaw，为 dist/OpenClaw.app）。 相同 Bundle 标识符：更改 Bundle ID 会创建新的权限身份。 已签名的应用：未签名或临时签名的构建不会持久化权限。 一致的签名：使用真实的 Apple Development 或 Developer ID 证书，以确保签名在多次构建之间保持稳定。 临时签名每次构建都会生成新的身份。macOS 会忘记之前的授权，提示可能完全消失，直到清除过期条目为止。 权限提示消失时的恢复清单 退出应用。 在系统设置 -> 隐私与安全性中移除该应用条目。 从相同路径重新启动应用并重新授予权限。 如果提示仍未出现，使用 tccutil 重置 TCC 条目后重试。 某些权限仅在完全重启 macOS 后才会重新出现。 重置示例（根据需要替换 Bundle ID）： sudo tccutil reset Accessibility bot.molt.mac sudo tccutil reset ScreenCapture bot.molt.mac sudo tccutil reset AppleEvents 如果你正在测试权限，请始终使用真实证书签名。临时签名的构建仅适用于不需要权限的快速本地运行。