Agent Safehouse命令选项完全指南：20个--enable开关逐一讲透

Agent Safehouse命令选项完全指南：20个--enable开关逐一讲透

【免费下载链接】agent-safehouseSandbox your local AI agents so they can read/write only what they need项目地址: https://gitcode.com/gh_mirrors/ag/agent-safehouse

Agent Safehouse 是一款面向 macOS 的 AI 编程代理沙箱工具，用原生sandbox-exec和可组合的策略档案，让 Claude、Codex、Gemini 等本地 AI 代理只能读写它们真正需要的文件。它的核心配置入口就是--enable命令选项——通过一组功能开关，按需解锁浏览器、Docker、Keychain、GPU 等集成能力。本文把这些--enable开关按场景逐一讲透，帮你用最少权限跑满最强能力。

一、为什么需要 --enable 开关？

Agent Safehouse 遵循「拒绝优先」（deny-first）的默认假设：

• 默认只授予工作目录读写、~/.config、~/.cache等窄范围权限；
• 一切额外能力（浏览器、麦克风、云凭证……）都必须显式开启；
• 完整的选项说明见 docs/docs/options.md。

--enable就是这套最小权限模型的「总闸」：不开就是关，开了才把对应的策略档案混入最终生成的沙箱策略。可选功能档案统一放在 profiles/55-integrations-optional/，每个.sb文件对应一个开关，解析逻辑在 bin/lib/policy/selection.sh 中实现。

二、三种写法：逗号分隔、可重复、可持久化

开关的解析与合并逻辑见 bin/lib/policy/request.sh：

# 逗号分隔，一次开多个 safehouse --enable=docker,kubectl -- kubectl get pods -A # 开关可重复 safehouse --enable=ssh --enable=gpg -- codex

还可以写进工作目录的.safehouse配置文件（需配合--trust-workdir-config），格式见 docs/docs/options.md：

enable=docker,shell-init

三、开发调试类开关

1. lldb：本地原生调试器

--enable=lldb为 LLDB 打开沙箱侧许可，适合让代理驱动原生调试。注意 macOS 仍可能拒绝附加到受保护的目标进程。

2. xcode：完整 Xcode 开发环境

解锁 Xcode 开发者根目录、DerivedData与CoreSimulator状态，配合xcodebuild使用。它不包含调试器 task-port 权限——真要用调试器请另开lldb。

3. gpg：GPG 提交签名

先在沙箱外启动代理进程，沙箱内的git即可签名提交：

gpgconf --launch gpg-agent && gpgconf --launch keyboxd safehouse --enable=gpg -- git commit -S -m "signed"

4. ssh：SSH 访问

放行 SSH 相关路径，便于代理访问 Git 远端。

5. process-control：宿主机进程枚举与信号

允许进程枚举/信号发送，主要用于本地调试场景，权限较大，按需开启。

6. shell-init：读取 Shell 启动文件

让运行时能读取.zshrc、.bashrc等启动配置。⚠️ 开启前请先审计这些文件，代理可能继承其中导出的凭证与 token。

四、桌面与 GUI 类开关

7. macos-gui：桌面 GUI 权限

为需要与桌面交互的代理流程提供基础 GUI 放行。

8. electron：Electron 应用支持

自动隐含gpu与macos-gui，用于跑 Electron 宿主的应用内代理工作流。

9. gpu：Metal 与 GPU IOKit 权限

授予 Metal 着色器编译（MTLCompilerService）与 GPU IOKit 用户客户端，适合纯 GPU/Metal 工作负载。electron和chromium-headless都会传递性地拉入它。

10. launch-services：open -b 应用启动

允许沙箱内进程调用open -b复用已运行的应用（例如复用已在运行的 VS Code 做 Claude 的外部编辑器交接）。由于它可以启动沙箱外任意应用，请谨慎开启。

11. vscode：冷启动独立 VS Code

没有vscode开关时只能复用已运行的 VS Code；开启后 Safehouse 可以冷启动一个隔离的 VS Code 编辑器窗口处理 Claude 的临时 prompt 文件（不继承你的扩展与最近列表）。若已设置EDITOR/VISUAL则不会注入。

12. spotlight / clipboard / microphone / cleanshot

• spotlight：Spotlight 索引访问；
• clipboard：剪贴板读写；
• microphone：麦克风权限；
• cleanshot：CleanShot 媒体目录访问。

均为细粒度开关，按需单独开启即可。

五、浏览器类开关（注意依赖链）

13. agent-browser：代理浏览器自动化

为浏览器自动化代理流程放行所需路径。

14. chromium-headless / chromium-full / playwright-chrome

三者存在清晰的隐含依赖链：

playwright-chrome ⇒ chromium-full ⇒ chromium-headless ⇒ gpu

⚠️ 在 Safehouse 内运行 Chromium 家族进程时，务必给浏览器自身传--no-sandbox，否则会先撞上 Chromium 内层 Seatbelt 沙箱报错。

15. browser-native-messaging：浏览器原生消息通道

放行 native messaging 清单与扩展检测（不是浏览数据）。

六、凭证与云资源类开关

16. keychain / 1password：密码管理器访问

keychain主要用于插件或辅助流程需要 macOS 钥匙串凭证的场景（核心opencode不需要）；1password则放行 1Password 集成路径。

17. cloud-credentials / cloud-storage：云凭证与云存储

分别放行云凭证文件与云存储同步目录，让代理能配置并访问对象存储。

七、基础设施类开关

18. docker：Docker 套接字访问

safehouse --enable=docker -- docker ps

19. kubectl：K8s 配置与 krew 路径

放行kubectl配置、缓存及 krew 路径，可直接执行集群命令。

20. herdr：本地调试面板集成

允许宿主机进程枚举/信号交互以支持 herdr 调试；当环境中检测到HERDR_ENV时还会自动启用并透传相关环境变量。

八、三个「全家桶」开关

这三者会短路常规的命令/应用匹配流程（见 bin/lib/policy/selection.sh），属于「最大便利」选项，日常开发建议只开wide-read级别的只读放宽。

九、新手快速上手清单

1. 默认运行即可享受最窄权限：safehouse claude --dangerously-skip-permissions
2. 常用基础设施一次性配齐：--enable=docker,kubectl
3. 需要写代码+跑测试：默认工具链（/usr/bin/git、make、clang等）不需要--enable，已由默认档案覆盖
4. 浏览器自动化：--enable=playwright-chrome一条搞定整条依赖链
5. 拿不准开什么？跑一次会报Unknown feature in --enable并列出全部支持的开关清单，等价于内置帮助；更多示例见 docs/docs/usage.md

十、延伸阅读

• 完整命令选项表：docs/docs/options.md
• 使用模式与集成示例：docs/docs/usage.md
• 策略档案目录：profiles/
• 开关解析测试：tests/surface/cli/enable-parsing.bats

💡 记住原则：开最少的开关，给最窄的权限——这正是 Agent Safehouse 把 20+ 个功能拆成独立--enable开关的意义所在。

【免费下载链接】agent-safehouseSandbox your local AI agents so they can read/write only what they need项目地址: https://gitcode.com/gh_mirrors/ag/agent-safehouse