跳转至

macOS 权限

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

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

屏幕录制（Screen Recording）和辅助功能（Accessibility）在访问权限确认之前会显示 Not granted（未授予）；macOS 的二元检查无法区分首次请求与拒绝。在前往系统设置查找 OpenClaw 之前，请先点击 Grant（授予）请求访问权限。如果访问被拒绝或提示不再出现，请使用旁边的 Open System Settings（打开系统设置）操作。对于已确认被拒绝的权限，会提供该操作而不是 Grant（授予）。

启用摄像头访问、Computer Control、桌面共享、保持电脑唤醒（Keep computer awake）、Peekaboo 桥接、浏览器 Cookie 同步或连续 Voice Wake 监听时，需要进行一次系统原生确认，且默认选中 Cancel（取消）。提升位置访问级别（从 Off 到 While Using 或 Always，或从 While Using 到 Always）以及启用精确定位也需要确认。即使同步尚未启用，添加 Cookie 域名也需要确认；在同步启用期间更改目标位置则需要确认。关闭这些功能或降低位置访问级别无需系统原生确认即可生效。取消 Cookie 域名或目标位置的更改会恢复所显示的原生值；较新的编辑会保持待定，直到其自身的确认完成。

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

稳定权限的要求

  • 相同路径：从 /Applications/OpenClaw.app 运行发布版应用；将开发构建固定在一个路径，例如 dist/OpenClaw.app。
  • 相同 Bundle 标识符：发布版使用 ai.openclaw.mac；开发构建默认使用 ai.openclaw.mac.debug。两者各自拥有独立的权限身份。
  • 已签名的应用：未签名或 ad-hoc 签名的构建无法持久保留权限。
  • 一致的签名：使用真实的 Apple Development 或 Developer ID 证书，以便签名在多次重新构建之间保持稳定。

Ad-hoc 签名每次构建都会生成新的身份。macOS 会忘记之前的授权，提示也可能完全消失，直到过期的条目被清除。

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

如果 Quick Chat 仍显示 Needs additional permissions: Screen Recording（需要额外权限：屏幕录制）：

  1. 在 OpenClaw 中点击 Grant（授予）。
  2. 如果 macOS 打开了系统设置，请在 Privacy & Security -> Screen & System Audio Recording（在旧版 macOS 上称为 Screen Recording）下启用正在运行的 OpenClaw 应用。
  3. 返回 OpenClaw 并重试截图。Dashboard → Settings → This Mac → Permissions 会显示刷新后的访问状态。

在明确的 Grant（授予）请求之后，OpenClaw 除了检查 macOS 权限预检之外，还会检查 ScreenCaptureKit。这样，即使预检仍报告旧的拒绝状态，它也能识别出已获得访问权限。在你请求访问权限之前，被动状态检查不会发起此探测。

如果访问权限仍然显示缺失，请从相同的应用路径退出并重新打开 OpenClaw。某些 macOS 权限更改需要先重启应用，采集功能才能正常工作。如果同时安装了发布版和开发构建，请为你实际运行的构建授予访问权限：批准 /Applications/OpenClaw.app 并不会让具有不同 Bundle 标识符的开发构建获得访问权限。

面向 Node 和 CLI 运行时的辅助功能（Accessibility）授权

请优先将辅助功能（Accessibility）授予 OpenClaw.app、Peekaboo.app 或其他带有自身 Bundle 标识符的已签名辅助程序，而不是授予通用的 node 二进制文件。

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

请将系统设置中的 node 条目视为针对该 Node 运行时的广泛权限，而不是针对某个 npm 包的权限。除非你信任通过该特定 Node 安装启动的每一个脚本和包，否则请避免将辅助功能授予 node。

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

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

独立的 Computer Control 授权

macOS 将辅助功能（Accessibility）、事件发送（Event Posting）、输入监听和屏幕录制（Screen Recording）分别存放在不同的 TCC 存储桶中。一次成功的授权并不能证明其他授权也可用。OpenClaw 的 Computer Control 状态会分别检查辅助功能、事件发送和屏幕录制；这就是为什么截图可以成功，而点击和键入却会失败。

辅助功能条目也可能看似仍处于启用状态，而其代码要求却被固定到较旧的构建。当 OpenClaw 报告 Accessibility grant may be stale（辅助功能授权可能已过期）时，请在 System Settings -> Privacy & Security -> Accessibility 中选中 OpenClaw，使用 - 将其移除，然后重新添加 /Applications/OpenClaw.app。之后请退出并重新打开 OpenClaw，因为辅助功能信任可能仍缓存在正在运行的进程中。

桌面可用性与保持唤醒

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

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

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

屏幕共享可能在最后一个查看器断开连接时请求立即锁定。即使启用了 保持电脑唤醒，OpenClaw 也会遵守该锁定。

手动锁定、注销或未知桌面状态会释放保持唤醒断言，并终止活动的 Computer 执行。OpenClaw 不会在登录后解锁 Mac 或 恢复这些执行。请通过屏幕共享或本地使用正常的 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