权限与系统设置
本页说明桌面端在 macOS 上需要的系统权限、如何授权，以及模型供应商配置为什么只保存在本机。
需要哪些系统权限
只有 Bot 推送实时画面、成员远程操作时才需要系统权限。未授权不影响其他功能：Bot 照常读代码、改文件、跑命令、开放网页预览。
| 权限 | 用途 | 未授权时 |
|---|---|---|
| 屏幕录制 | 推送桌面应用和小程序的实时画面 | 成员看不到画面 |
| 辅助功能 | 远程操作桌面应用和小程序、自动信任小程序项目 | 远程点击和输入不生效 |
这两项权限授予的是共工空间桌面端本身；推流组件 gg-cast 由桌面端启动，沿用同一份授权，不需要单独授权。Windows、Linux 不需要这些权限，相关提示也不会出现。
授权步骤
绑定完成后，如果有权限未授权，桌面端会自动打开「授予系统权限」页面。之后也可以从这些地方进入：概览页顶部的「未授权：…」提示、「实时画面」页的「系统权限」、「日志与诊断」页的诊断项，点其中的「去授权」即可。
- 在「授予系统权限」页面，点某项权限右侧的「去授权」。
- macOS 会弹出系统提示，或直接打开「系统设置 → 隐私与安全性」的对应页面（屏幕录制或辅助功能）。
- 在列表中找到 共工空间，打开它的开关，按提示输入密码确认。
- 回到共工空间窗口，状态会自动刷新为「已授权」。
- 屏幕录制需要重启共工空间后才生效：授权屏幕录制后，点页面上的「重启共工空间」。
- 全部授权后点「完成」；暂时不想授权可以点「稍后」。
列表里找不到共工空间？
先在共工空间里点一次「去授权」，桌面端会把自己登记到系统的权限列表里，然后再去「系统设置」里找。
升级后权限失效
macOS 按应用签名记录这两项授权。使用 Developer ID 证书签名的安装包升级后授权会保留；没有 Developer ID 签名的安装包每个版本签名都不同，升级后需要重新授权。遇到升级后画面推不出来，先到「实时画面」页检查权限状态。
使用命令行 gg 时的权限
用命令行 gg run 运行时，macOS 会把权限算在运行 gg 的程序（如「终端」、iTerm）头上，需要在「系统设置 → 隐私与安全性 → 屏幕录制 / 辅助功能」里允许这个终端程序。gg doctor 会列出这两项是否已授权。
供应商配置只存本机
在「Agent」页和「Bot」页配置的模型供应商（第三方模型服务的地址、API Key、模型、Bot 单独使用的供应商）只保存在这台机器上：
- 保存在本机的
~/.gonggong/providers.json，文件权限仅本人可读写（0600）。 - 不上传服务器，也不会同步到你的其他机器。每台机器需要单独配置。
- 页面上显示的 API Key 是打码后的；编辑时 API Key 留空表示保留已保存的 Key。
- 运行时 Key 只通过本机文件或子进程环境变量交给 Agent，不会出现在命令行参数、日志和报错里。
- 网页上的机器详情也能管理供应商：网页只是把操作转发给这台机器的 daemon，由 daemon 读写本机文件，服务器不保存 Key。机器离线时无法在网页上管理它的供应商。
换机器或重装系统时，需要在新机器上重新配置供应商。命令行下的对应操作见 命令参考 · provider，网页上的操作见 Agent 工具与供应商。
其他系统相关设置
- 开机启动：「设置」里的「开机启动」开关。打开后登录系统时在后台启动，不弹出窗口也能接任务。
- PATH：从 Finder 或 Dock 打开的应用拿不到终端里的 PATH。桌面端启动时会读取你的登录 shell 的 PATH，因此用 nvm、volta、asdf 等安装的 Node.js 和 Agent CLI 也能被找到；另外还会查找
~/.local/bin、/opt/homebrew/bin、/usr/local/bin、~/.npm-global/bin。仍然找不到时，在「Agent」页用「手动指定路径…」。