[OpenClaw 文档]平台--平台概览

本文档汇总了 OpenClaw 官方文档站 平台 > 平台概览 子模块下的全部 9 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 平台

原文：https://docs.openclaw.ai/zh-CN/platforms

OpenClaw 核心使用 TypeScript 编写。Node 是推荐的运行时。
不推荐将 Bun 用于 Gateway 网关 —— WhatsApp 和
Telegram 渠道存在已知问题；详情见 Bun（实验性）。

macOS（菜单栏应用）和移动节点（iOS/Android）已有配套应用。Windows 和
Linux 配套应用已在计划中，但 Gateway 网关目前已完全支持。
Windows 原生配套应用也已在计划中；建议通过 WSL2 使用 Gateway 网关。

选择你的操作系统

• macOS: macOS
• iOS: iOS
• Android: Android
• Windows: Windows
• Linux: Linux

VPS 和托管

• VPS 中心: VPS 托管
• Fly.io: Fly.io
• Hetzner（Docker）: Hetzner
• GCP（Compute Engine）: GCP
• Azure（Linux VM）: Azure
• exe.dev（VM + HTTPS 代理）: exe.dev

常用链接

• 安装指南: 入门指南
• Gateway 网关运行手册: Gateway 网关
• Gateway 网关配置: 配置
• 服务 Status: openclaw gateway status

Gateway 网关服务安装（CLI）

使用以下任一方式（均受支持）：

• 向导（推荐）: openclaw onboard --install-daemon
• 直接安装: openclaw gateway install
• 配置流程: openclaw configure → 选择 Gateway 网关服务
• 修复/迁移: openclaw doctor（会提供安装或修复服务的选项）

服务目标取决于操作系统：

• macOS: LaunchAgent（ai.openclaw.gateway 或 ai.openclaw.<profile>；旧版 com.openclaw.*）
• Linux/WSL2: systemd 用户服务（openclaw-gateway[-<profile>].service）
• 原生 Windows: 计划任务（OpenClaw Gateway 或 OpenClaw Gateway (<profile>)），如果任务创建被拒绝，则回退为每用户启动文件夹登录项

相关内容

• 安装概览
• macOS 应用
• iOS 应用

📄 macOS 应用

原文：https://docs.openclaw.ai/zh-CN/platforms/macos

macOS 应用是 OpenClaw 的菜单栏配套应用。它负责权限、本地管理/连接 Gateway 网关（通过 launchd 或手动方式），并将 macOS 能力作为节点暴露给智能体。

它的作用

• 在菜单栏中显示原生通知和 Status。
• 负责 TCC 提示（通知、辅助功能、屏幕录制、麦克风、语音识别、自动化/AppleScript）。
• 运行或连接 Gateway 网关（本地或远程）。
• 暴露仅限 macOS 的工具（画布、相机、屏幕录制、system.run）。
• 在远程模式下启动本地节点主机服务（launchd），并在本地模式下停止它。
• 可选托管 PeekabooBridge 以用于 UI 自动化。
• 按需通过 npm、pnpm 或 bun 安装全局 CLI（openclaw）（应用优先使用 npm，其次是 pnpm，再其次是 bun；Node 仍是推荐的 Gateway 网关运行时）。

本地模式与远程模式

• 本地（默认）：如果存在正在运行的本地 Gateway 网关，应用会连接它；否则会通过 openclaw gateway install 启用 launchd 服务。
• 远程：应用通过 SSH/Tailscale 连接到 Gateway 网关，并且绝不启动本地进程。
  应用会启动本地节点主机服务，以便远程 Gateway 网关可以访问这台 Mac。
  应用不会将 Gateway 网关作为子进程生成。
  Gateway 网关发现现在优先使用 Tailscale MagicDNS 名称，而不是原始 tailnet IP，因此当 tailnet IP 变化时，Mac 应用能更可靠地恢复。

Launchd 控制

应用管理一个按用户划分的 LaunchAgent，标签为 ai.openclaw.gateway
（使用 --profile/OPENCLAW_PROFILE 时为 ai.openclaw.<profile>；旧版 com.openclaw.* 仍会卸载）。

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

运行具名配置时，将标签替换为 ai.openclaw.<profile>。

如果尚未安装 LaunchAgent，请从应用中启用它，或运行
openclaw gateway install。

节点能力（mac）

macOS 应用会将自身呈现为一个节点。常见命令：

• 画布：canvas.present、canvas.navigate、canvas.eval、canvas.snapshot、canvas.a2ui.*
• 相机：camera.snap、camera.clip
• 屏幕：screen.snapshot、screen.record
• 系统：system.run、system.notify

节点会报告一个 permissions 映射，以便智能体判断允许执行哪些操作。

节点服务 + 应用 IPC：

• 当无头节点主机服务正在运行时（远程模式），它会作为节点连接到 Gateway 网关 WS。
• system.run 通过本地 Unix 套接字在 macOS 应用中执行（UI/TCC 上下文）；提示和输出都留在应用内。

图示（SCI）：

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)

执行审批（system.run）

system.run 由 macOS 应用中的执行审批控制（设置 → 执行审批）。
安全策略、询问策略和允许列表会本地存储在 Mac 上：

~/.openclaw/exec-approvals.json

示例：

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

说明：

• allowlist 条目是已解析二进制路径的 glob 模式，或通过 PATH 调用的命令的裸命令名。
• 包含 shell 控制或展开语法（&&、||、;、|、`、$、<、>、(、)）的原始 shell 命令文本会被视为允许列表未命中，并需要显式批准（或将 shell 二进制加入允许列表）。
• 在提示中选择 “始终允许” 会将该命令添加到允许列表。
• system.run 环境覆盖项会被过滤（丢弃 PATH、DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT、SHELLOPTS、PS4），然后与应用的环境合并。
• 对于 shell 包装器（bash|sh|zsh ... -c/-lc），请求范围的环境覆盖项会缩减为一个较小的显式允许列表（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）。
• 在允许列表模式下做出始终允许决策时，已知分发包装器（env、nice、nohup、stdbuf、timeout）会持久化内部可执行文件路径，而不是包装器路径。如果无法安全展开，则不会自动持久化任何允许列表条目。

深层链接

应用注册 openclaw:// URL 方案用于本地操作。

openclaw://agent

触发一个 Gateway 网关 agent 请求。
OC_I18N_900004
查询参数：

• message（必需）
• sessionKey（可选）
• thinking（可选）
• deliver / to / channel（可选）
• timeoutSeconds（可选）
• key（可选的无人值守模式密钥）

安全性：

• 没有 key 时，应用会提示确认。
• 没有 key 时，应用会对确认提示强制执行较短的消息长度限制，并忽略 deliver / to / channel。
• 使用有效 key 时，运行将无人值守（用于个人自动化）。

新手引导流程（典型）

1. 安装并启动 OpenClaw.app。
2. 完成权限检查清单（TCC 提示）。
3. 确保本地模式处于活动状态，且 Gateway 网关正在运行。
4. 如果你想使用终端访问，请安装 CLI。

状态目录位置（macOS）

避免将你的 OpenClaw 状态目录放在 iCloud 或其他云同步文件夹中。
由同步支持的路径可能增加延迟，并偶尔导致会话和凭据出现文件锁/同步竞争。

优先使用本地非同步状态路径，例如：
OC_I18N_900005
如果 openclaw doctor 检测到状态位于：

• ~/Library/Mobile Documents/com~apple~CloudDocs/...
• ~/Library/CloudStorage/...

它会发出警告，并建议移回本地路径。

构建和开发工作流（原生）

• cd apps/macos && swift build
• swift run OpenClaw（或 Xcode）
• 打包应用：scripts/package-mac-app.sh

调试 Gateway 网关连接（macOS CLI）

使用调试 CLI 可以执行与 macOS 应用相同的 Gateway 网关 WebSocket 握手和发现逻辑，而无需启动应用。
OC_I18N_900006
连接选项：

• --url <ws://host:port>：覆盖配置
• --mode <local|remote>：从配置解析（默认：配置或本地）
• --probe：强制执行新的健康探测
• --timeout <ms>：请求超时（默认：15000）
• --json：用于差异比较的结构化输出

发现选项：

• --include-local：包含本会被过滤为“本地”的网关
• --timeout <ms>：整体发现窗口（默认：2000）
• --json：用于差异比较的结构化输出

与 openclaw gateway discover --json 对比，查看 macOS 应用的发现管线（local. 加上已配置的广域域名，并带有广域和 Tailscale Serve 回退）是否不同于 Node CLI 基于 dns-sd 的发现。

远程连接管道（SSH 隧道）

当 macOS 应用在远程模式下运行时，它会打开 SSH 隧道，使本地 UI 组件可以像访问 localhost 上的 Gateway 网关一样访问远程 Gateway 网关。

控制隧道（Gateway 网关 WebSocket 端口）

• 用途：健康检查、Status、Web 聊天、配置，以及其他控制平面调用。
• 本地端口：Gateway 网关端口（默认 18789），始终稳定。
• 远程端口：远程主机上的同一个 Gateway 网关端口。
• 行为：没有随机本地端口；应用会复用现有健康隧道，或在需要时重启它。
• SSH 形态：ssh -N -L <local>:127.0.0.1:<remote>，并带有 BatchMode + ExitOnForwardFailure + keepalive 选项。
• IP 报告：SSH 隧道使用 loopback，因此 Gateway 网关会看到节点 IP 为 127.0.0.1。如果你希望显示真实客户端 IP，请使用 Direct（ws/wss）传输（见 macOS 远程访问）。

设置步骤见 macOS 远程访问。协议详情见 Gateway 网关协议。

相关文档

• Gateway 网关运行手册
• Gateway 网关（macOS）
• macOS 权限
• 画布

📄 Linux 应用

原文：https://docs.openclaw.ai/zh-CN/platforms/linux

Gateway 网关在 Linux 上完全受支持。Node 是推荐运行时。
不建议将 Bun 用于 Gateway 网关（WhatsApp/Telegram 错误）。

原生 Linux 配套应用已在计划中。如果你想帮助构建一个，欢迎贡献。

初学者快速路径（VPS）

1. 安装 Node 24（推荐；Node 22 LTS，目前为 22.16+，仍可兼容使用）
2. npm i -g openclaw@latest
3. openclaw onboard --install-daemon
4. 从你的笔记本电脑运行：ssh -N -L 18789:127.0.0.1:18789 <user>@<host>
5. 打开 http://127.0.0.1:18789/，并使用已配置的共享密钥进行身份验证（默认是令牌；如果你设置了 gateway.auth.mode: "password"，则使用密码）

完整的 Linux 服务器指南：Linux 服务器。分步 VPS 示例：exe.dev

安装

• 入门指南
• 安装和更新
• 可选流程：Bun（实验性）、Nix、Docker

Gateway 网关

• Gateway 网关运行手册
• 配置

Gateway 网关服务安装（CLI）

使用以下任一命令：

openclaw onboard --install-daemon

或：

openclaw gateway install

或：

openclaw configure

出现提示时选择 Gateway 网关服务。

修复/迁移：

openclaw doctor

系统控制（systemd 用户单元）

OpenClaw 默认安装 systemd 用户服务。对于共享或始终在线的服务器，请使用系统服务。openclaw gateway install 和
openclaw onboard --install-daemon 已经会为你渲染当前规范单元；只有在需要自定义系统/服务管理器设置时，才需要手动编写。完整服务指南位于 Gateway 网关运行手册。

最小设置：

创建 ~/.config/systemd/user/openclaw-gateway[-<profile>].service：

[Unit]
Description=OpenClaw Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

启用它：

systemctl --user enable --now openclaw-gateway[-<profile>].service

内存压力和 OOM 终止

在 Linux 上，当主机、VM 或容器 cgroup 内存耗尽时，内核会选择一个 OOM 牺牲进程。Gateway 网关可能是一个较差的牺牲目标，因为它拥有长期存在的会话和渠道连接。因此，OpenClaw 会尽可能倾向于先终止临时子进程，而不是 Gateway 网关。

对于符合条件的 Linux 子进程启动，OpenClaw 会通过一个简短的 /bin/sh 包装器启动子进程，该包装器会将子进程自身的 oom_score_adj 提高到 1000，然后 exec 真正的命令。这是一个非特权操作，因为子进程只是在提高自身被 OOM 终止的可能性。

覆盖的子进程表面包括：

• 由 supervisor 管理的命令子进程，
• PTY shell 子进程，
• MCP stdio server 子进程，
• OpenClaw 启动的浏览器/Chrome 进程。

该包装器仅适用于 Linux，并且在 /bin/sh 不可用时会跳过。如果子进程环境设置了 OPENCLAW_CHILD_OOM_SCORE_ADJ=0、false、no 或 off，也会跳过。

验证子进程：

cat /proc/<child-pid>/oom_score_adj

覆盖的子进程预期值为 1000。Gateway 网关进程应保持正常分数，通常为 0。

这不能替代正常的内存调优。如果 VPS 或容器反复终止子进程，请增加内存限制、降低并发，或添加更强的资源控制，例如 systemd MemoryMax= 或容器级内存限制。

相关

• 安装概览
• Linux 服务器
• Raspberry Pi

📄 Windows

原文：https://docs.openclaw.ai/zh-CN/platforms/windows

OpenClaw 同时支持 原生 Windows 和 WSL2。WSL2 是更稳定的路径，也推荐用于完整体验：CLI、Gateway 网关和工具链都在 Linux 内运行，具备完整兼容性。原生 Windows 可用于核心 CLI 和 Gateway 网关使用，但有下面提到的一些注意事项。

原生 Windows 配套应用正在规划中。

WSL2（推荐）

• 入门指南（在 WSL 内使用）
• 安装与更新
• 官方 WSL2 指南（Microsoft）：https://learn.microsoft.com/windows/wsl/install

原生 Windows 状态

原生 Windows CLI 流程正在改进，但 WSL2 仍然是推荐路径。

目前在原生 Windows 上运行良好的内容：

• 通过 install.ps1 使用网站安装器
• 本地 CLI 使用，例如 openclaw --version、openclaw doctor 和 openclaw plugins list --json
• 嵌入式本地智能体/提供商冒烟测试，例如：

openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."

当前注意事项：

• openclaw onboard --non-interactive 仍然要求有可访问的本地 Gateway 网关，除非你传入 --skip-health
• openclaw onboard --non-interactive --install-daemon 和 openclaw gateway install 会优先尝试 Windows 计划任务
• 如果计划任务创建被拒绝，OpenClaw 会回退到每用户 Startup 文件夹登录项，并立即启动 Gateway 网关
• 如果 schtasks 本身卡住或停止响应，OpenClaw 现在会快速中止该路径并改用回退方式，而不是永远挂起
• 计划任务在可用时仍然是首选，因为它们能提供更好的 supervisor 状态

如果你只需要原生 CLI，不安装 Gateway 网关服务，请使用以下命令之一：

openclaw onboard --non-interactive --skip-health
openclaw gateway run

如果你确实想在原生 Windows 上使用托管启动：

openclaw gateway install
openclaw gateway status --json

如果计划任务创建被阻止，回退服务模式仍会在当前用户登录后通过 Startup 文件夹自动启动。

Gateway 网关

• Gateway 网关运行手册
• 配置

Gateway 网关服务安装（CLI）

在 WSL2 内：

openclaw onboard --install-daemon

或者：

openclaw gateway install

或者：

openclaw configure

在提示时选择 Gateway 网关服务。

修复/迁移：

openclaw doctor

Windows 登录前自动启动 Gateway 网关

对于无头设置，确保即使无人登录 Windows，完整启动链也会运行。

1) 保持用户服务在未登录时运行

在 WSL 内：

sudo loginctl enable-linger "$(whoami)"

2) 安装 OpenClaw Gateway 网关用户服务

在 WSL 内：

openclaw gateway install

3) 在 Windows 启动时自动启动 WSL

在以管理员身份运行的 PowerShell 中：

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

将 Ubuntu 替换为以下命令显示的你的发行版名称：

wsl --list --verbose

验证启动链

重启后（Windows 登录前），从 WSL 检查：

systemctl --user is-enabled openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager

高级：通过 LAN 暴露 WSL 服务（portproxy）

WSL 有自己的虚拟网络。如果另一台机器需要访问 WSL 内部 运行的服务（SSH、本地 TTS 服务器或 Gateway 网关），你必须将 Windows 端口转发到当前 WSL IP。WSL IP 会在重启后变化，因此你可能需要刷新转发规则。

示例（以管理员身份运行 PowerShell）：

$Distro = "Ubuntu-24.04"
$ListenPort = 2222
$TargetPort = 22

$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
if (-not $WslIp) { throw "WSL IP not found." }

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
  connectaddress=$WslIp connectport=$TargetPort

允许该端口通过 Windows 防火墙（一次性操作）：

New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow

WSL 重启后刷新 portproxy：

netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
  connectaddress=$WslIp connectport=$TargetPort | Out-Null

注意：

• 从另一台机器发起 SSH 时，目标是 Windows 主机 IP（示例：ssh user@windows-host -p 2222）。
• 远程节点必须指向一个可访问的 Gateway 网关 URL（而不是 127.0.0.1）；使用 openclaw status --all 确认。
• 对 LAN 访问使用 listenaddress=0.0.0.0；127.0.0.1 会将其限制为仅本地访问。
• 如果你希望自动执行此操作，请注册一个计划任务，在登录时运行刷新步骤。

WSL2 分步安装

1) 安装 WSL2 + Ubuntu

打开 PowerShell（管理员）：

wsl --install
# Or pick a distro explicitly:
wsl --list --online
wsl --install -d Ubuntu-24.04

如果 Windows 要求，请重启。

2) 启用 systemd（安装 Gateway 网关所需）

在你的 WSL 终端中：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

然后从 PowerShell 运行：

wsl --shutdown

重新打开 Ubuntu，然后验证：

systemctl --user status

3) 安装 OpenClaw（在 WSL 内）

对于 WSL 内的常规首次设置，请遵循 Linux 入门指南流程：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
pnpm openclaw onboard --install-daemon

如果你是从源码进行开发，而不是首次新手引导，请使用 设置 中的源码开发循环：

pnpm install
# First run only (or after resetting local OpenClaw config/workspace)
pnpm openclaw setup
pnpm gateway:watch

完整指南：入门指南

Windows 配套应用

我们还没有 Windows 配套应用。如果你想帮助实现它，欢迎贡献。

Git 和 GitHub 连接性（贡献者）

某些网络会阻止或限制到 GitHub 的 HTTPS。如果 git clone 因超时或连接重置而失败，请尝试其他网络、VPN，或你的组织提供的 HTTP/HTTPS 代理。

如果 gh auth login 在浏览器设备流程中失败（例如访问 github.com:443 超时），请改用个人访问令牌进行身份验证：

1. 创建一个至少包含 repo 范围（经典 PAT）或等效精细粒度访问权限的令牌。
2. 在当前会话的 PowerShell 中：

$env:GH_TOKEN="<your-token>"
gh auth status
gh auth setup-git

3. 如果 gh auth status 警告缺少 read:org，请生成一个包含该范围的令牌并重新赋值变量：

$env:GH_TOKEN="<your-token-with-repo-and-read:org>"
gh auth status

gh auth refresh -s read:org 只适用于你通过 gh auth login 进行身份验证并已存储可刷新的凭据时（不适用于使用 GH_TOKEN 的情况）。

切勿提交令牌，或将令牌粘贴到 issue 或 pull request 中。

相关

• 安装概览
• 平台

📄 Android 应用

原文：https://docs.openclaw.ai/zh-CN/platforms/android

Android 应用尚未公开发布。源代码位于 OpenClaw 仓库的 apps/android 下。你可以使用 Java 17 和 Android SDK（./gradlew :app:assemblePlayDebug）自行构建。构建说明请参阅 apps/android/README.md。

支持快照

• 角色：配套节点应用（Android 不托管 Gateway 网关）。
• 需要 Gateway 网关：是（通过 WSL2 在 macOS、Linux 或 Windows 上运行）。
• 安装：入门指南 + 配对。
• Gateway 网关：运行手册 + 配置。
• 协议：Gateway 网关协议（节点 + 控制平面）。

系统控制

系统控制（launchd/systemd）位于 Gateway 网关主机上。请参阅 Gateway 网关。

连接运行手册

Android 节点应用 ⇄（mDNS/NSD + WebSocket）⇄ Gateway 网关

Android 直接连接到 Gateway 网关 WebSocket，并使用设备配对（role: node）。

对于 Tailscale 或公网主机，Android 需要安全端点：

• 首选：Tailscale Serve / Funnel，使用 https://<magicdns> / wss://<magicdns>
• 同样支持：任何其他带有真实 TLS 端点的 wss:// Gateway 网关 URL
• 明文 ws:// 仍支持私有 LAN 地址 / .local 主机，以及 localhost、127.0.0.1 和 Android 模拟器桥接地址（10.0.2.2）

前提条件

• 你可以在“主”机器上运行 Gateway 网关。
• Android 设备/模拟器可以访问 Gateway 网关 WebSocket：
• 同一 LAN，使用 mDNS/NSD，或
• 同一 Tailscale tailnet，使用 Wide-Area Bonjour / 单播 DNS-SD（见下文），或
• 手动 Gateway 网关主机/端口（回退）
• Tailnet/公网移动端配对不使用原始 tailnet IP ws:// 端点。请改用 Tailscale Serve 或其他 wss:// URL。
• 你可以在 Gateway 网关机器上（或通过 SSH）运行 CLI（openclaw）。

1) 启动 Gateway 网关

openclaw gateway --port 18789 --verbose

确认日志中能看到类似内容：

• listening on ws://0.0.0.0:18789

对于通过 Tailscale 远程访问 Android，优先使用 Serve/Funnel，而不是原始 tailnet 绑定：

openclaw gateway --tailscale serve

这会为 Android 提供安全的 wss:// / https:// 端点。普通的 gateway.bind: "tailnet" 设置不足以完成首次远程 Android 配对，除非你还单独终止 TLS。

2) 验证设备发现（可选）

在 Gateway 网关机器上：

dns-sd -B _openclaw-gw._tcp local.

更多调试说明：Bonjour。

如果你还配置了广域发现域名，请对比：

openclaw gateway discover --json

它会一次性显示 local. 加上配置的广域域名，并使用解析后的服务端点，而不是只依赖 TXT 提示。

通过单播 DNS-SD 进行 tailnet（维也纳 ⇄ 伦敦）发现

Android NSD/mDNS 发现无法跨网络。如果你的 Android 节点和 Gateway 网关位于不同网络，但通过 Tailscale 连接，请改用 Wide-Area Bonjour / 单播 DNS-SD。

仅有设备发现不足以进行 tailnet/公网 Android 配对。发现到的路由仍需要安全端点（wss:// 或 Tailscale Serve）：

1. 在 Gateway 网关主机上设置 DNS-SD 区域（例如 openclaw.internal.），并发布 _openclaw-gw._tcp 记录。
2. 为你选择的域配置 Tailscale split DNS，指向该 DNS 服务器。

详细信息和 CoreDNS 示例配置：Bonjour。

3) 从 Android 连接

在 Android 应用中：

• 应用通过前台服务（持久通知）保持 Gateway 网关连接存活。
• 打开 Connect 选项卡。
• 使用 Setup Code 或 Manual 模式。
• 如果设备发现被阻止，请在 Advanced controls 中使用手动主机/端口。对于私有 LAN 主机，ws:// 仍可使用。对于 Tailscale/公网主机，请开启 TLS 并使用 wss:// / Tailscale Serve 端点。

首次成功配对后，Android 会在启动时自动重新连接：

• 手动端点（如果已启用），否则
• 上次发现的 Gateway 网关（尽力而为）。

在线状态存活信标

在经过身份验证的节点会话连接后，以及应用进入后台但前台服务仍保持连接时，Android 会调用 node.event，并带上 event: "node.presence.alive"。Gateway 网关只有在已知经过身份验证的节点设备身份之后，才会把它记录为已配对节点/设备元数据上的 lastSeenAtMs/lastSeenReason。

只有当 Gateway 网关响应包含 handled: true 时，应用才会把该信标计为成功记录。旧版 Gateway 网关可能会用 { "ok": true } 确认 node.event；该响应兼容，但不会计为持久的最后可见时间更新。

4) 批准配对（CLI）

在 Gateway 网关机器上：

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

配对详情：配对。

可选：如果 Android 节点始终从严格受控的子网连接，你可以通过显式 CIDR 或精确 IP 选择启用首次节点自动批准：

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

默认禁用。它仅适用于没有请求作用域的新 role: node 配对。操作员/浏览器配对，以及任何角色、作用域、元数据或公钥变更，仍需要手动批准。

5) 验证节点已连接

• 通过节点 Status：

bash
openclaw nodes status

• 通过 Gateway 网关：

bash
openclaw gateway call node.list --params "{}"

6) 聊天 + 历史记录

Android Chat 选项卡支持会话选择（默认 main，以及其他现有会话）：

• 历史记录：chat.history（显示已规范化；内联指令标签会从可见文本中剥离，纯文本工具调用 XML 载荷（包括 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> 和被截断的工具调用块）以及泄漏的 ASCII/全角模型控制令牌会被剥离，精确为 NO_REPLY / no_reply 等纯静默令牌的 assistant 行会被省略，过大的行可被替换为占位符）
• 发送：chat.send
• 推送更新（尽力而为）：chat.subscribe → event:"chat"

7) Canvas + 摄像头

Gateway 网关 Canvas 主机（推荐用于 Web 内容）

如果你希望节点显示智能体可以在磁盘上编辑的真实 HTML/CSS/JS，请将节点指向 Gateway 网关 canvas 主机。

节点从 Gateway 网关 HTTP 服务器加载 canvas（与 gateway.port 相同端口，默认 18789）。

1. 在 Gateway 网关主机上创建 ~/.openclaw/workspace/canvas/index.html。

2. 将节点导航到该位置（LAN）：

openclaw nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__openclaw__/canvas/"}'

Tailnet（可选）：如果两台设备都在 Tailscale 上，请使用 MagicDNS 名称或 tailnet IP，而不是 .local，例如 http://<gateway-magicdns>:18789/__openclaw__/canvas/。

该服务器会向 HTML 注入实时重载客户端，并在文件变更时重新加载。
A2UI 主机位于 http://<gateway-host>:18789/__openclaw__/a2ui/。

Canvas 命令（仅前台）：

• canvas.eval、canvas.snapshot、canvas.navigate（使用 {"url":""} 或 {"url":"/"} 返回默认脚手架）。canvas.snapshot 返回 { format, base64 }（默认 format="jpeg"）。
• A2UI：canvas.a2ui.push、canvas.a2ui.reset（canvas.a2ui.pushJSONL 旧版别名）

摄像头命令（仅前台；受权限控制）：

• camera.snap（jpg）
• camera.clip（mp4）

参数和 CLI 辅助工具请参阅摄像头节点。

8) 语音 + 扩展的 Android 命令表面

• 语音选项卡：Android 有两种显式采集模式。Mic 是手动的语音选项卡会话，会把每次停顿作为聊天轮次发送，并在应用离开前台或用户离开语音选项卡时停止。Talk 是连续的 Talk 模式，会持续监听，直到被关闭或节点断开连接。
• Talk 模式会在采集开始前将现有前台服务从 dataSync 提升为 dataSync|microphone，然后在 Talk 模式停止时降级。Android 14+ 要求声明 FOREGROUND_SERVICE_MICROPHONE、授予 RECORD_AUDIO 运行时权限，并在运行时使用麦克风服务类型。
• 语音回复通过配置的 Gateway 网关 Talk 提供商使用 talk.speak。仅在 talk.speak 不可用时才使用本地系统 TTS。
• Android UX/运行时中仍禁用语音唤醒。
• 其他 Android 命令族（可用性取决于设备 + 权限）：
• device.status、device.info、device.permissions、device.health
• notifications.list、notifications.actions（见下方通知转发）
• photos.latest
• contacts.search、contacts.add
• calendar.events、calendar.add
• callLog.search
• sms.search
• motion.activity、motion.pedometer

Assistant 入口点

Android 支持从系统 assistant 触发器（Google Assistant）启动 OpenClaw。配置后，长按主屏幕按钮或说“Hey Google, ask OpenClaw...”会打开应用，并将提示词交给聊天输入框。

这使用 Android App Actions 元数据，该元数据在应用清单中声明。Gateway 网关侧无需额外配置；assistant intent 完全由 Android 应用处理，并作为普通聊天消息转发。

App Actions 的可用性取决于设备、Google Play Services 版本，以及用户是否已将 OpenClaw 设置为默认 assistant 应用。

通知转发

Android 可以将设备通知作为事件转发到 Gateway 网关。多个控制项可用于限定转发哪些通知以及何时转发。

通知选择器还会对转发的通知事件使用更安全的行为，防止意外转发敏感系统通知。

配置示例：

{
  notifications: {
    allowPackages: ["com.slack", "com.whatsapp"],
    denyPackages: ["com.android.systemui"],
    quietHours: {
      start: "22:00",
      end: "07:00",
    },
    rateLimit: 5,
  },
}

通知转发需要 Android 通知监听器权限。应用会在设置期间提示授予该权限。

相关

• iOS 应用
• 节点
• Android 节点故障排除

📄 iOS 应用

原文：https://docs.openclaw.ai/zh-CN/platforms/ios

可用性：内部预览。iOS 应用尚未公开分发。

它的作用

• 通过 WebSocket（局域网或 tailnet）连接到 Gateway 网关。
• 暴露节点能力：Canvas、Screen snapshot、Camera capture、Location、Talk 模式、Voice wake。
• 接收 node.invoke 命令并报告节点 Status 事件。

要求

• 另一台设备上正在运行的 Gateway 网关（macOS、Linux，或通过 WSL2 运行的 Windows）。
• 网络路径：
• 通过 Bonjour 使用同一局域网，或
• 通过单播 DNS-SD 使用 tailnet（示例域名：openclaw.internal.），或
• 手动主机/端口（后备）。

快速开始（配对 + 连接）

1. 启动 Gateway 网关：

openclaw gateway --port 18789

2. 在 iOS 应用中，打开设置并选择一个已发现的 Gateway 网关（或启用 Manual Host 并输入主机/端口）。

3. 在 Gateway 网关主机上批准配对请求：

openclaw devices list
openclaw devices approve <requestId>

如果应用使用已更改的认证详情（角色/作用域/公钥）重试配对，
先前的待处理请求会被取代，并创建新的 requestId。
批准前再次运行 openclaw devices list。

可选：如果 iOS 节点始终从严格受控的子网连接，你
可以通过显式 CIDR 或精确 IP 选择启用首次节点自动批准：

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

默认禁用此功能。它仅适用于新的 role: node 配对且
未请求任何作用域。操作者/浏览器配对，以及任何角色、作用域、元数据或
公钥变更仍需要手动批准。

4. 验证连接：

openclaw nodes status
openclaw gateway call node.list --params "{}"

官方构建的中继推送

官方分发的 iOS 构建使用外部推送中继，而不是将原始 APNs
令牌发布到 Gateway 网关。

Gateway 网关侧要求：

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
        },
      },
    },
  },
}

流程的工作方式：

• iOS 应用使用 App Attest 和 StoreKit 应用交易 JWS 向中继注册。
• 中继返回一个不透明的中继句柄以及注册作用域的发送授权。
• iOS 应用获取已配对的 Gateway 网关身份，并将其包含在中继注册中，因此该中继支持的注册会委托给该特定 Gateway 网关。
• 应用通过 push.apns.register 将该中继支持的注册转发给已配对的 Gateway 网关。
• Gateway 网关使用存储的中继句柄执行 push.test、后台唤醒和唤醒轻推。
• Gateway 网关中继基础 URL 必须与官方/TestFlight iOS 构建内置的中继 URL 匹配。
• 如果应用之后连接到不同 Gateway 网关，或连接到带有不同中继基础 URL 的构建，它会刷新中继注册，而不是复用旧绑定。

此路径下 Gateway 网关不需要：

• 不需要部署范围的中继令牌。
• 官方/TestFlight 中继支持发送不需要直接 APNs 密钥。

预期操作者流程：

1. 安装官方/TestFlight iOS 构建。
2. 在 Gateway 网关上设置 gateway.push.apns.relay.baseUrl。
3. 将应用与 Gateway 网关配对，并让它完成连接。
4. 应用在拥有 APNs 令牌、操作者会话已连接且中继注册成功后，会自动发布 push.apns.register。
5. 之后，push.test、重连唤醒和唤醒轻推都可以使用存储的中继支持注册。

后台存活信标

当 iOS 因静默推送、后台刷新或重要位置事件唤醒应用时，应用
会尝试短暂重连节点，然后使用 event: "node.presence.alive" 调用 node.event。
只有在认证后的节点设备身份已知后，Gateway 网关才会把它作为 lastSeenAtMs/lastSeenReason
记录到已配对节点/设备元数据上。

只有当 Gateway 网关响应包含 handled: true 时，应用才会将后台唤醒视为已成功记录。
较旧的 Gateway 网关可能会用 { "ok": true } 确认 node.event；该响应
兼容，但不算作持久的最后在线时间更新。

兼容性说明：

• OPENCLAW_APNS_RELAY_BASE_URL 仍可作为 Gateway 网关的临时环境覆盖使用。

认证和信任流程

中继的存在是为了强制执行两个直接在 Gateway 网关上使用 APNs 无法为
官方 iOS 构建提供的约束：

• 只有通过 Apple 分发的真实 OpenClaw iOS 构建才能使用托管中继。
• Gateway 网关只能为与该特定 Gateway 网关配对的 iOS 设备发送中继支持的推送。

逐跳说明：

1. iOS app -> gateway
   - 应用首先通过正常的 Gateway 网关认证流程与 Gateway 网关配对。
   - 这会给应用一个经过认证的节点会话，以及一个经过认证的操作者会话。
   - 操作者会话用于调用 gateway.identity.get。

2. iOS app -> relay
   - 应用通过 HTTPS 调用中继注册端点。
   - 注册包含 App Attest 证明以及 StoreKit 应用交易 JWS。
   - 中继验证 bundle ID、App Attest 证明和 Apple 分发证明，并要求
   官方/生产分发路径。
   - 这就是阻止本地 Xcode/开发构建使用托管中继的机制。本地构建可以被
   签名，但它不满足中继所期望的官方 Apple 分发证明。

3. gateway identity delegation
   - 在中继注册之前，应用从
   gateway.identity.get 获取已配对 Gateway 网关的身份。
   - 应用将该 Gateway 网关身份包含在中继注册载荷中。
   - 中继返回一个中继句柄和一个注册作用域的发送授权，二者委托给
   该 Gateway 网关身份。

4. gateway -> relay
   - Gateway 网关存储来自 push.apns.register 的中继句柄和发送授权。
   - 在 push.test、重连唤醒和唤醒轻推时，Gateway 网关使用自己的
   设备身份签名发送请求。
   - 中继根据注册时委托的 Gateway 网关身份，验证存储的发送授权和
   Gateway 网关签名。
   - 即使另一个 Gateway 网关以某种方式获得了该句柄，也不能复用该存储注册。

5. relay -> APNs
   - 中继拥有生产 APNs 凭据以及官方构建的原始 APNs 令牌。
   - 对于中继支持的官方构建，Gateway 网关永不存储原始 APNs 令牌。
   - 中继代表已配对的 Gateway 网关向 APNs 发送最终推送。

创建此设计的原因：

• 让生产 APNs 凭据不进入用户的 Gateway 网关。
• 避免在 Gateway 网关上存储官方构建的原始 APNs 令牌。
• 只允许官方/TestFlight OpenClaw 构建使用托管中继。
• 防止一个 Gateway 网关向归属于另一个 Gateway 网关的 iOS 设备发送唤醒推送。

本地/手动构建仍使用直接 APNs。如果你在不使用中继的情况下测试这些构建，
Gateway 网关仍需要直接 APNs 凭据：

export OPENCLAW_APNS_TEAM_ID="TEAMID"
export OPENCLAW_APNS_KEY_ID="KEYID"
export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)"

这些是 Gateway 网关主机运行时环境变量，不是 Fastlane 设置。apps/ios/fastlane/.env 只存储
App Store Connect / TestFlight 认证，例如 ASC_KEY_ID 和 ASC_ISSUER_ID；它不配置
本地 iOS 构建的直接 APNs 投递。

推荐的 Gateway 网关主机存储方式：

mkdir -p ~/.openclaw/credentials/apns
chmod 700 ~/.openclaw/credentials/apns
mv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
export OPENCLAW_APNS_PRIVATE_KEY_PATH="$HOME/.openclaw/credentials/apns/AuthKey_KEYID.p8"

不要提交 .p8 文件，也不要将它放在仓库检出目录下。

设备发现路径

Bonjour（局域网）

iOS 应用在 local. 上浏览 _openclaw-gw._tcp，并在配置后浏览同一个
广域 DNS-SD 发现域。同一局域网的 Gateway 网关会自动从 local. 出现；
跨网络发现可以使用配置的广域域名，而无需更改信标类型。

Tailnet（跨网络）

如果 mDNS 被阻止，请使用单播 DNS-SD 区域（选择一个域名；示例：
openclaw.internal.）和 Tailscale 分割 DNS。
有关 CoreDNS 示例，请参阅 Bonjour。

手动主机/端口

在设置中，启用 Manual Host 并输入 Gateway 网关主机 + 端口（默认 18789）。

Canvas + A2UI

iOS 节点渲染 WKWebView canvas。使用 node.invoke 驱动它：

openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18789/__openclaw__/canvas/"}'

说明：

• Gateway 网关 canvas 主机提供 /__openclaw__/canvas/ 和 /__openclaw__/a2ui/。
• 它由 Gateway 网关 HTTP 服务器提供服务（与 gateway.port 相同的端口，默认 18789）。
• 当已通告 canvas 主机 URL 时，iOS 节点会在连接时自动导航到 A2UI。
• 使用 canvas.navigate 和 {"url":""} 返回内置脚手架。

与 Computer Use 的关系

iOS 应用是移动节点界面，不是 Codex Computer Use 后端。Codex
Computer Use 和 cua-driver mcp 通过 MCP
工具控制本地 macOS 桌面；iOS 应用通过 OpenClaw 节点命令
暴露 iPhone 能力，例如 canvas.*、camera.*、screen.*、location.* 和 talk.*。

智能体仍可通过调用节点
命令，借助 OpenClaw 操作 iOS 应用，但这些调用会经过 Gateway 网关节点协议，并遵循 iOS
前台/后台限制。使用 Codex Computer Use
进行本地桌面控制；使用本页了解 iOS 节点能力。

Canvas eval / snapshot

openclaw nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'

openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'

Voice wake + Talk 模式

• Voice wake 和 Talk 模式可在设置中使用。
• 支持 Talk 的 iOS 节点会通告 talk 能力，并可以声明
  talk.ptt.start、talk.ptt.stop、talk.ptt.cancel 和 talk.ptt.once；
  Gateway 网关默认允许受信任且支持 Talk 的节点使用这些按住说话命令。
• iOS 可能会挂起后台音频；当应用未处于活跃状态时，请将语音功能视为尽力而为。

常见错误

• NODE_BACKGROUND_UNAVAILABLE：将 iOS 应用带到前台（canvas/camera/screen 命令需要它）。
• A2UI_HOST_NOT_CONFIGURED：Gateway 网关没有通告 Canvas 插件界面 URL；检查 Gateway 网关配置 中的 plugins.entries.canvas.config.host。
• 配对提示从未出现：运行 openclaw devices list 并手动批准。
• 重新安装后重连失败：Keychain 配对令牌已被清除；重新配对节点。

相关文档

• Pairing
• 设备发现
• Bonjour

📄 DigitalOcean（平台）

原文：https://docs.openclaw.ai/zh-CN/platforms/digitalocean

此页面已移至 DigitalOcean。

相关

• 安装概览
• VPS 托管

📄 Oracle Cloud（平台）

原文：https://docs.openclaw.ai/zh-CN/platforms/oracle

此页面已移至 Oracle Cloud。

相关

• 安装概览
• VPS 托管

📄 Raspberry Pi（平台）

原文：https://docs.openclaw.ai/zh-CN/platforms/raspberry-pi

此页面已移至 Raspberry Pi。

相关内容

• 安装概览
• Linux 服务器
• 平台