企业官网建设流程全解析

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯

导读

本文聚焦 OpenClaw 中「节点（Node）可见但节点工具（canvas、camera、screen、exec 等）调用失败」这一经典场景，以官方节点故障排查文档为主体，系统讲解诊断命令阶梯、前台运行约束、权限矩阵、配对与审批的两层心智模型、常见错误码及快速恢复循环。读者将掌握从openclaw status起步、逐层定位到具体错误码，并最终通过「设备配对 + 执行审批 + OS 权限」三轴修复问题的完整实战能力，同时理解这些规则背后的网关协议与节点宿主实现原理。

适用场景与核心心智模型

本文对应的排查入口非常明确：当节点在openclaw status中可见（connected/paired），但canvas.*、camera.*、screen.*、system.run等节点工具调用失败时，应优先使用本文的排查路径。相关的基础设施与命令面定义在 docs/nodes/index.md 中：一个**节点（node）**是连接 Gateway WebSocket（与操作者同一端口）的伴随设备（macOS/iOS/Android/headless），以role: "node"身份连接，并通过node.invoke暴露命令面（如canvas.*、camera.*、device.*、notifications.*、system.*）。

在动手排查前，先建立两个关键心智模型：

1. 节点是外设，不是网关：节点不运行网关服务，Telegram/WhatsApp 等消息落在网关上，而非节点上；节点只是被网关调用的能力提供方。
2. 两层独立的门禁：设备能否连接网关（配对）与设备能否执行某条 shell 命令（审批）是两套完全不同的门禁，后面会详细展开。

命令阶梯（Command ladder）：从全局到节点

官方排查文档给出的标准起点是一组从全局到节点的命令阶梯：

openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe

• openclaw status与openclaw gateway status：确认网关整体健康，节点工具的调用都经由网关转发，网关异常会让一切节点调用失败。
• openclaw logs --follow：实时观察调用失败时的错误码与内部日志，是后续所有步骤的眼睛。
• openclaw doctor：系统性体检，可发现配置、状态与权限方面的隐患（对应 docs/gateway/doctor.md）。
• openclaw channels status --probe：探测渠道凭据（--probe在 cli/channels-cli.ts 中定义为"Probe channel credentials"），用于排除渠道层面的干扰。

随后进入节点专属检查：

openclaw nodes status openclaw nodes describe --node <idOrNameOrIp> openclaw approvals get --node <idOrNameOrIp>

健康信号（Healthy signals）应同时满足：

• 节点已连接且以node角色完成配对（paired for rolenode）。
• nodes describe的输出包含你正在调用的能力（capability）。
• 执行审批（Exec approvals）显示预期的模式（security/ask）与 allowlist。

关于nodes describe的字段语义，可参考 cli/nodes-cli/register.status.ts：describe通过node.describeRPC 获取节点信息，输出 ID、Name、IP、Device、Model、Perms、Version、PATH、Status、Caps 等字段，并单独列出该节点上报的 Commands 列表（obj.commands）。如果你要调用的命令不在 Commands 列表里，即使节点已配对连接，调用也会失败——这正是"能力未上报"类问题的判断依据。

前台运行要求（Foreground requirements）

canvas.*、camera.*、screen.*在 iOS/Android 节点上仅在前台（foreground）可用，后台调用一律失败。这是移动操作系统对摄像头、屏幕录制等敏感能力的硬性限制。

快速检查与修复：

openclaw nodes describe --node <idOrNameOrIp> openclaw nodes canvas snapshot --node <idOrNameOrIp> openclaw logs --follow

如果日志中出现NODE_BACKGROUND_UNAVAILABLE，把节点 App 切到前台后重试即可。

源码佐证：在 docs/nodes/camera.md 中明确说明"Likecanvas.*, the iOS node only allowscamera.*commands in theforeground. Background invocations returnNODE_BACKGROUND_UNAVAILABLE."；docs/nodes/location-command.md 也指出 Android 在后台会拒绝location.get。可以推断这类错误码由节点端按平台分别实现，因此排查时务必确认具体平台的行为差异。

权限矩阵（Permissions matrix）

不同能力在不同平台上要求的 OS 权限不同，官方文档给出了完整的对照矩阵：

关键解读：

• system.run在 iOS/Android 节点上是n/a（不适用），因为移动端并不直接暴露通用 shell 执行；它只在 macOS 节点 App 与 headless 节点宿主上存在，且由Exec approvals（而非 OS 权限）门禁。
• 相机、屏幕录制失败时，错误码往往以_PERMISSION_REQUIRED结尾，例如CAMERA_PERMISSION_REQUIRED、RECORD_AUDIO_PERMISSION_REQUIRED——这说明是 OS 层授权缺失，需要去系统设置补授权，而不是改 OpenClaw 配置。
• Android 在相机与录音权限缺失时"会在可能时弹出系统授权框；若被拒绝则以*_PERMISSION_REQUIRED失败"（见 docs/nodes/camera.md）。

配对 vs 审批：两层独立的门禁

官方文档用一个两步模型帮助理解节点排障的本质：

1. 设备配对（Device pairing）：该节点能否连接到网关？
2. 执行审批（Exec approvals）：该节点能否执行某条具体的 shell 命令？

快速检查命令：

openclaw devices list openclaw nodes status openclaw approvals get --node <idOrNameOrIp> openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

如果配对缺失 → 先批准节点设备；如果配对正常但system.run失败 → 修复执行审批/allowlist。

配对（Pairing）的底层机制

从 docs/gateway/pairing.md 可知：WS 节点在connect握手期间携带设备身份，网关为role: node创建设备配对请求；待审批请求5 分钟自动过期；批准后网关签发全新 token（token 会在重新配对时轮换），节点用 token 重连后即为 paired。配对状态存储于网关状态目录：~/.openclaw/nodes/paired.json与~/.openclaw/nodes/pending.json。

CLI 形态：

openclaw devices list openclaw devices approve <requestId> openclaw devices reject <requestId> openclaw nodes pending openclaw nodes approve <requestId> openclaw nodes reject <requestId> openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

注意区分：nodes status将节点标记为paired的前提是"设备配对的角色包含node"；而node.pair.*（CLI 为openclaw nodes pending/approve/reject）是独立的网关侧节点配对存储，并不门禁 WS connect 握手（见 docs/nodes/index.md）。排查时如果看到"已配对但连不上"，要检查是否走错了配对通道。

执行审批（Exec approvals）的底层机制

执行审批是伴随 App / 节点宿主的护栏（guardrail），用于让沙箱内的 Agent 在真实主机（gateway或node）上执行命令——只有"策略 + allowlist +（可选）用户审批"三方一致时命令才被放行。关键点（详见 docs/tools/exec-approvals.md）：

• 生效位置：审批在执行宿主本地强制生效——网关宿主是openclaw进程，节点宿主是 macOS 伴随 App 或 headless 节点宿主；数据落在宿主本地的~/.openclaw/exec-approvals.json。
• 策略旋钮：
  • security（exec.security）：deny（全部拦截）/allowlist（仅允许白名单命令）/full（放行一切）。
  • ask（exec.ask）：off（永不提示）/on-miss（仅白名单未命中时提示）/always（每条命令都提示）。
  • askFallback：审批 UI 不可达时的兜底，deny（拦截）/allowlist（仅白名单命中）/full（放行）。
  • 有效策略取更严格者：tools.exec.*与 approvals 默认值中较严格的一方生效；approvals 字段缺省时回落到tools.exec值。
• allowlist 按 Agent 划分：模式是大小写不敏感的 glob 匹配，应解析到二进制路径（仅 basename 的条目会被忽略），例如~/Projects/**/bin/rg、/opt/homebrew/bin/rg。

源码实现证据：审批决策逻辑位于 node-host/exec-policy.ts 的evaluateSystemRunPolicy。它按security === "deny"（返回SYSTEM_RUN_DISABLED: security=deny）→requiresAsk && !approvedByAsk（返回SYSTEM_RUN_DENIED: approval required）→allowlist未命中（返回SYSTEM_RUN_DENIED: allowlist miss）的顺序裁决；shell 包装（bash|sh|zsh -c/-lc）在 allowlist 模式下被判定为shellWrapperBlocked，Windows 上的cmd.exe /c变体被额外标记为windowsShellWrapperBlocked，并在 node-host/exec-policy.ts 的formatSystemRunAllowlistMissMessage中给出带说明的报错信息。

CLI 侧：openclaw nodes run（对应 cli/nodes-cli/register.invoke.ts）会先调用system.run.prepare生成规范化的systemRunPlan，通过exec.approvals.node.get读取节点宿主审批快照，再按需经exec.approval.request发起审批请求；审批结果（allow-once / allow-always / deny）随node.invoke的approved、approvalDecision、runId等参数一并下发。审批请求在批准后绑定规范执行上下文（规范 cwd、可固定的可执行文件路径、解释器式脚本操作数）——若审批后脚本内容漂移，运行会被拒绝而非执行漂移内容。

常见节点错误码

官方文档给出的错误码速查表如下：

补充说明：

• CAMERA_DISABLED与开关的关系：iOS/Android 节点设置中camera.enabled默认开启（缺失键视为启用）；macOS 伴随 App 的openclaw.cameraEnabled默认关闭。关闭状态下camera.*返回CAMERA_DISABLED（见 docs/nodes/camera.md）。
• 定位错误码的完整集合还包括LOCATION_TIMEOUT（超时未定位）与LOCATION_UNAVAILABLE（系统故障/无定位提供方），以及location.get的精度参数desiredAccuracy: coarse|balanced|precise与响应中的accuracyMeters、isPrecise、source等字段（见 docs/nodes/location-command.md）。
• Windows 节点宿主的 allowlist 特例：在 allowlist 模式下，cmd.exe /c ...这类 shell 包装形式会被视为 allowlist miss，除非通过 ask 流程显式批准（文档原文，同时被 node-host/exec-policy.ts 的报错文案证实："Windows shell wrappers like cmd.exe /c require approval; approve once/always or run with --ask on-miss|always"）。shell 包装的通用规则同样适用于sh/bash/zsh -c。
• allowlist 模式下 shell 链接与重定向：&&、||、;仅当每个顶层段都满足 allowlist 时才放行；重定向在 allowlist 模式下不支持；命令替换（$()/ 反引号）在 allowlist 解析时被拒绝（详见 docs/tools/exec-approvals.md）。

快速恢复循环（Fast recovery loop）

当节点工具仍然失败时，官方文档给出标准恢复循环：

openclaw nodes status openclaw nodes describe --node <idOrNameOrIp> openclaw approvals get --node <idOrNameOrIp> openclaw logs --follow

如果仍然卡住，依次执行四步修复：

1. 重新批准设备配对（Re-approve device pairing）——通过openclaw devices approve <requestId>，必要时先openclaw devices list查看待批准请求。
2. 重新打开节点 App（保持前台）（Re-open node app）——解决NODE_BACKGROUND_UNAVAILABLE类问题。
3. 重新授予 OS 权限（Re-grant OS permissions）——解决*_PERMISSION_REQUIRED、LOCATION_PERMISSION_REQUIRED类问题。
4. 重建/调整执行审批策略（Recreate/adjust exec approval policy）——通过openclaw approvals编辑security、ask、askFallback与 allowlist，或直接编辑节点宿主的~/.openclaw/exec-approvals.json。

审批策略调整的实操入口

• CLI：openclaw approvals支持 get/set/allowlist 子命令（见 cli/exec-approvals-cli.ts 的get、set、allowlist注册），并可针对网关或指定节点操作：

openclaw approvals get --node <idOrNameOrIp> openclaw approvals set --node <idOrNameOrIp> --security allowlist openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname" openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/sw_vers" openclaw approvals allowlist rm --node <idOrNameOrIp> "/usr/bin/uname"

• Control UI：在Control UI → Nodes → Exec approvals卡片中编辑默认值、按 Agent 的覆盖与 allowlist；目标选择器可选择 Gateway（本地审批）或某个节点。节点必须上报system.execApprovals.get/set才能被 UI/CLI 编辑（macOS App 与 headless 节点宿主均支持；iOS/Android 不支持）。
• 直接编辑文件：若节点未上报 exec approvals 命令面，可直接编辑其本地~/.openclaw/exec-approvals.json。该文件 schema 示例（来自 docs/tools/exec-approvals.md）：

{ "version": 1, "socket": { "path": "~/.openclaw/exec-approvals.sock", "token": "base64url-token" }, "defaults": { "security": "deny", "ask": "on-miss", "askFallback": "deny", "autoAllowSkills": false }, "agents": { "main": { "security": "allowlist", "ask": "on-miss", "askFallback": "deny", "autoAllowSkills": true, "allowlist": [ { "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F", "pattern": "~/Projects/**/bin/rg", "lastUsedAt": 1737150000000, "lastUsedCommand": "rg -n TODO", "lastResolvedPath": "/Users/user/Projects/.../bin/rg" } ] } } }

注意：每个 allowlist 条目还跟踪lastUsedAt、lastUsedCommand、lastResolvedPath，便于 UI 展示"上次使用"信息，也方便清理长期未使用的条目。

把 exec 指向指定节点

如果网关配置了多个节点，可以显式绑定 exec 目标（详见 docs/nodes/index.md）：

openclaw config set tools.exec.host node openclaw config set tools.exec.security allowlist openclaw config set tools.exec.node "<id-or-name>"

会话内也可以用斜杠命令覆盖：

/exec host=node security=allowlist node=<id-or-name>

设置后，任何host=node的 exec 调用都会在指定节点宿主上运行，受该节点的 allowlist/审批约束。若要让 exec 默认不绑特定节点，可openclaw config unset tools.exec.node。

深度排障提示：从源码结构可以推断的要点

• 未知平台的保守默认：从 docs/nodes/index.md 可知，未识别platform/deviceFamily的节点使用保守默认 allowlist，排除system.run与system.which；若确需在未知平台使用这些命令，需通过gateway.nodes.allowCommands显式添加。这类节点system.run失败时，先检查是否是平台识别问题而非权限问题。
• 环境变量卫生：节点宿主会忽略PATH覆盖，并剥离危险启动/shell 键（DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT、SHELLOPTS、PS4）；shell 包装的命令行--env覆盖被缩减为显式允许列表（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）。若你的命令因环境变量缺失而失败，应配置节点宿主服务环境，而非通过--env PATH=...传入。
• allow-always 的包装器解包：allowlist 模式下，"允许始终"决策会对已知分发包装器（env、nice、nohup、stdbuf、timeout）持久化内部可执行文件路径而非包装器路径；无法安全解包时不自动持久化 allowlist 条目（node-host/exec-policy.ts 与 docs/nodes/index.md 一致）。
• 系统事件关联：审批门控的 exec 复用审批 id 作为runId出现在系统事件（Exec running/Exec finished/Exec denied）中，配合openclaw logs --follow可精确关联"哪次审批对应哪次执行"。

相关文档导航

• 节点总览与命令面：docs/nodes/index.md
• 相机捕获细节：docs/nodes/camera.md
• 定位命令与权限模式：docs/nodes/location-command.md
• 执行审批完整策略与 allowlist：docs/tools/exec-approvals.md
• 网关侧设备配对机制：docs/gateway/pairing.md
• 审批决策与报错文案实现：node-host/exec-policy.ts
• 节点状态/描述 CLI 实现：cli/nodes-cli/register.status.ts
• 节点命令调用与审批联动实现：cli/nodes-cli/register.invoke.ts

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯