跳转至

macOS 权限授予是脆弱的

TCC 将权限授予与应用的代码签名、捆绑标识符和磁盘路径相关联。如果其中任何一项发生变化,macOS 会将应用视为新应用,并可能丢弃或隐藏提示。

打开 macOS 应用中的 Dashboard → Settings → This Mac → Permissions,即可检查各项权限、请求访问,或打开其 macOS 系统设置面板。该页面还控制位置访问和精确度。在系统设置中更改授权后返回应用、聚焦 Dashboard 或完成权限请求时,权限状态会刷新。已打开的 Dashboard 窗口不会启动后台权限轮询。

屏幕录制和辅助功能在访问被确认前显示 未授予;macOS 的二进制检查无法区分首次请求与拒绝。在系统设置中查找 OpenClaw 之前,请先点击 授予 以请求访问权限。如果访问被拒绝或提示不再出现,请使用相邻的 打开系统设置 操作。已确认拒绝的权限会提供该操作,而不是 授予。

启用相机访问、电脑控制、桌面共享、保持电脑唤醒、Peekaboo 桥接、浏览器 Cookie 同步或持续 Voice Wake 监听,需要原生确认,且默认选中 取消。提高位置访问级别(从关闭到使用期间或始终,或从使用期间到始终)以及启用精确位置也需要确认。添加 Cookie 域即使在同步启用之前也需要确认;更改目标位置则在同步启用期间需要确认。禁用这些功能或降低位置访问级别无需原生确认即可生效。取消 Cookie 域或目标位置的更改会恢复显示的原生值;较新的编辑会保持待处理状态,直到其自身确认完成。

需要 macOS 授权的 Voice Wake 和位置更改会保持待处理状态,直到权限被授予。关闭或替换其 Dashboard 文档会丢弃待处理的更改。来自另一个 Dashboard 窗口的较新设置也会取代较旧的权限请求,因此其后续完成无法撤销较新的选择。

稳定权限的要求

  • 相同路径:从 /Applications/OpenClaw.app 运行发布版应用;将开发构建保留在固定路径,例如 dist/OpenClaw.app。
  • 相同捆绑标识符:发布构建使用 ai.openclaw.mac;开发构建默认为 ai.openclaw.mac.debug。两者各具有独立的权限身份。
  • 已签名应用:未签名或临时签名 (ad-hoc) 的构建无法持久保留权限。
  • 一致签名:使用真实的 Apple Development 或 Developer ID 证书,使签名在每次重建中保持稳定。

临时签名会在每次构建时生成新的身份。macOS 会忘记之前的授权,提示可能完全消失,直到过时的条目被清除。

授予访问权限后屏幕录制仍显示缺失

如果 Quick Chat 仍显示 需要额外权限:屏幕录制:

  1. 在 OpenClaw 中点击 授予。
  2. 如果 macOS 打开系统设置,请在 隐私与安全性 -> 屏幕与系统音频录制(在旧版 macOS 上称为 屏幕录制)下启用正在运行的 OpenClaw 应用。
  3. 返回 OpenClaw 并重试截图。Dashboard → Settings → This Mac → Permissions 会显示刷新后的访问状态。

在明确的 授予 请求之后,OpenClaw 会同时检查 ScreenCaptureKit 和 macOS 权限预检。这让它能在预检仍报告旧的拒绝状态时识别访问已获授权。被动状态检查不会在你请求访问之前发起此检查。

如果访问仍显示缺失,请从相同的应用路径退出并重新打开 OpenClaw。某些 macOS 权限更改需要重启应用后才能正常采集。如果同时安装了发布版和开发构建,请授权给实际正在运行的构建:批准 /Applications/OpenClaw.app 并不会授予具有不同捆绑标识符的开发构建访问权限。

Node 和 CLI 运行时的辅助功能授权

建议优先将辅助功能授予 OpenClaw.app、Peekaboo.app 或另一个具有自身捆绑标识符的已签名辅助程序,而不是授予通用的 node 二进制文件。

macOS TCC 会将辅助功能授予其所见进程的代码身份。如果 Homebrew、nvm、pnpm 或 npm 工作流导致共享的 node 可执行文件获得辅助功能,则通过该同一可执行文件启动的任何 JavaScript 包都可能继承 GUI 自动化权限。

请将系统设置中的 node 条目视为对该 Node 运行时的宽泛授权,而非对某个 npm 包的授权。除非你信任通过该确切 Node 安装启动的每个脚本和包,否则请避免向 node 授予辅助功能。

基本存在检测来自与 OpenClaw 的交互,无需辅助功能授权。Dashboard → Settings → This Mac → Permissions → 系统范围存在检测 (System-wide presence detection) 是一个独立的、默认关闭的控制项,包含其他应用中的物理活动。仅批准辅助功能并不能启用它。将其关闭会清除系统范围样本并回退到应用本地活动,而不会撤销辅助功能或断开节点连接。

如果你不小心将辅助功能授予了 node,请从系统设置 -> 隐私与安全性 -> 辅助功能中移除该条目。然后授予应拥有 UI 自动化的已签名应用或辅助程序。

独立的电脑控制授权

macOS 将辅助功能、事件发布、输入监听和屏幕录制分别保存在独立的 TCC 桶中。一次成功的授权并不能证明其他授权可用。OpenClaw 的电脑控制状态会分别检查辅助功能、事件发布和屏幕录制;这就是截图可以成功而点击和键入失败的原因。

辅助功能行也可能在看起来仍为启用状态的同时,其代码要求被固定到较旧的构建。当 OpenClaw 报告 辅助功能授权可能已过期 时,请在 系统设置 -> 隐私与安全性 -> 辅助功能 下选中 OpenClaw,使用 - 移除,然后重新添加 /Applications/OpenClaw.app。之后退出并重新打开 OpenClaw,因为辅助功能信任可能仍缓存在正在运行的进程中。

桌面可用性与保持唤醒

仪表盘 → 设置 → 此 Mac 会基于原生 macOS 会话显示 桌面可用性 为 已锁定、已解锁 或 未知。此运行状态独立于权限授予和可选的 活动电脑存在 设置。已连接的节点或成功的 Screen Sharing 连接不能证明桌面已解锁。

在 Computer 执行期间,OpenClaw 会从该执行的首个操作起使用临时保持唤醒断言,最长一小时。这包括后台窗口和浏览器操作。完成、取消、断开连接、提供商替换或本地 Stop 会释放该执行的保持唤醒请求。网页桌面查看器不会创建 OpenClaw 保持唤醒执行。

要在任务之间保持专用 Mac 唤醒,请在同一设置页面上启用 保持电脑唤醒 并接受原生确认。它默认关闭,并且仅在此 Mac 已连接并实际托管时生效。它不会更改 macOS 电源或锁定设置。

Screen Sharing 可能在最后一个查看器断开时请求立即锁定。即使启用了 保持电脑唤醒,OpenClaw 也会遵守该锁定。

手动锁定、注销或未知桌面状态会释放保持唤醒断言,并终止活动的 Computer 执行。OpenClaw 不会在登录后解锁 Mac 或恢复这些执行。请通过 Screen Sharing 或本地使用正常的 macOS 登录屏幕,然后启动新的 Computer 执行。在验证解锁后,只要其托管和连接要求仍然满足,保持唤醒选项可以重新激活。

网页桌面查看器仍可作为登录途径使用,并显示已锁定或未知状态。macOS 可能会限制对其安全登录屏幕的捕获;空白或仅显示壁纸的查看器不能证明 Mac 已解锁。参见 Computer 使用故障排除。

提示消失时的恢复检查清单

  1. 退出应用。
  2. 从系统设置 -> 隐私与安全性中移除该应用条目。
  3. 从相同路径重新启动应用并重新授予权限。
  4. 如果提示仍未出现,请使用 tccutil 重置 TCC 条目并重试。
  5. 某些权限只有在完整重启 macOS 后才会重新出现。

重置示例(使用 OpenClaw 的 bundle ID,ai.openclaw.mac):

sudo tccutil reset Accessibility ai.openclaw.mac
sudo tccutil reset ScreenCapture ai.openclaw.mac

文件和文件夹权限(Desktop/Documents/Downloads)

macOS 也可能对终端/后台进程限制 Desktop、Documents 和 Downloads 的访问。如果文件读取或目录列表挂起,请向执行文件操作的同一进程上下文授予访问权限(例如 Terminal/iTerm、由 LaunchAgent 启动的应用或 SSH 进程)。

变通方法:如果想避免逐文件夹授权,请将文件移动到 OpenClaw 工作区(~/.openclaw/workspace)。

如果你正在测试权限,请始终使用真实证书进行签名。Ad-hoc 构建仅适用于权限无关紧要的快速本地运行。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw