CodeAgent 是一个跑在终端里的开源 AI 编程 Agent：它读代码、改文件、跑命令、跑测试，一直迭代到任务完成。但一个能"自己敲命令"的助手，最让人担心的就是它误删文件、篡改密钥。CodeAgent 的权限安全体系正是为此设计：每条命令要依次穿过 5 道闸门（底线检查、硬拒绝黑名单、破坏性审批、用户审批、LLM 语义分类），文件写入受路径白名单约束，Linux 下还能用 bwrap 沙箱把命令关进内核级"笼子"。下面带你快速看懂这套设计。

权限安全总览：一道命令要过多少关？

先给结论：CodeAgent 里每一次rm、每一次写文件之前，都要先过安检。安检的地基是 agent/permission.py 的模块头注释，作者把整个流程画成了"小区保安"式的关卡图：

主入口是 PermissionChecker.check()：按 闸门 0 → 内容级规则 → 危险删除 → 黑名单 → 注入面 → 只读快速通道 → 破坏性审批 → LLM 分类 → 默认放行 的顺序走完。顺序就是安全优先级——黑名单永远排在快速通道之前。

闸门 0：即使"跳过所有审批"也绕不过的底线

最容易被忽略、却最重要的一关是闸门 0。它包含两条：

• 系统级不可逆破坏（permission.py#L237-L243）：mkfs格式化、fork bomb、dd写裸磁盘设备、rm -rf /或rm -rf ~整棵树。其中rm的判定不走正则而是逐 token 比对（permission.py#L253-L289），因为-fr、--recursive --force、--no-preserve-root这些变体一条正则罩不住。
• 自我保护（permission.py#L178-L227）：AI 不许在 CodeAgent 自己的代码目录里跑uv add/pip install——"给自己动手术"只会把助手搞瘫痪。

即便你在/permission里选了bypassPermissions（跳过全部审批）模式，闸门 0 依然生效。这是整个权限系统里唯一的"绝对不可绕过"检查。

路径白名单：写文件只准碰三个地方

命令有闸门，文件同样有。agent/path_guard.py 是路径安全的核心，规则非常直白：

1. 受保护路径，读写全拒（path_guard.py#L48-L70）：~/.ssh、~/.aws、~/.gnupg、~/.config/gh（GitHub token）、/etc、C:\Windows等 17 条。注意它会同时检查"原始写法"和"软链展开后的真实写法"，软链指向~/.ssh也逃不掉（path_guard.py#L82-L118）。
2. 写保护路径，只读不改：CodeAgent 自己的项目代码目录允许读、禁止写，防止 AI 篡改自身源码。
3. 写白名单（path_guard.py#L326-L350）：默认只允许写 ① 当前工作目录 ②~/.codeAgent③ 你用/add-dir显式追加的目录。白名单外的写入会弹审批，选"总是允许"后父目录持久化到settings.json。

还有一个容易忽视的细节——可疑路径形态检测（path_guard.py#L214-L271）。Windows 下有些"改名绕过安检"的花招：8.3 短名（GIT~1和GIT是同一个文件）、长路径前缀\\?\、文件名尾点（.git.实际就是.git）、NTFS 数据流冒号、DOS 设备名（settings.json.CON）……这些写法能让同一个文件呈现出对不上的字符串，全部直接拒绝，且全平台都查（NTFS 磁盘可以挂在任何系统上）。

顺序铁律：保护表排白名单前面——就算你把整个家目录加进白名单，~/.ssh照样写不了。

bwrap 沙箱：把命令关进内核级"小房间"

闸门和白名单是"软件层"的检查，agent/sandbox_runner.py 提供的是 OS 层的硬隔离。用/sandbox on开启后，Linux 下命令会被包装成：

bwrap --die-with-parent --new-session --unshare-pid --unshare-ipc \ --ro-bind /usr /usr --ro-bind /etc /etc ... \ --dev /dev --proc /proc --tmpfs /tmp \ --bind <工作目录> <工作目录> -- bash -c "<你的命令>"

包装逻辑在 _bwrap_wrap()，几个设计点很讲究：

• 系统目录只读挂载（sandbox_runner.py#L264-L271）：/usr、/etc等"只给看不给改"；/dev改用沙箱自带的--dev临时盘，否则>/dev/null这种 curl/git 惯用写法会直接撞 EROFS 报错。
• 独立 PID 命名空间：不隔离进程的话，沙箱里的命令能看见宿主机全部进程，一条kill -9就能干掉 Agent 自己。
• /tmp用内存盘：不挂宿主机的/tmp（里面可能有敏感东西），改用沙箱内部 tmpfs。
• 可写目录白名单复用：沙箱里能写的只有工作目录 +~/.codeAgent+ 配置中的sandbox_writable_roots，和路径白名单同源。

macOS 走系统自带的 Seatbelt（sandbox-exec+ 每次现写的.sb规则文件，7 天自动清理，sandbox_runner.py#L393-L468）；Windows 走 Job Object 进程笼子（win_job_object.py）。沙箱不可用时自动降级为普通执行并记警告（fail-open），不会把任务卡死。

审批体验：少打扰、有记忆、后台分身自动拒

权限系统的另一半是"怎么问才不烦人"，三个机制值得学：

• 只读快速通道（readonly_commands.py#L30-L57）：ls、cat、git status、grep这类"只看不动手"的命令零打扰放行。判定保守优先——find -delete这类带写副作用的形态会被参数黑名单拦下，复合命令逐段切分判定，ls & rm xxx混不过去。
• 注入面检测（bash_injection.py#L564）：$()、反引号、进程替换<(...)这些"所见非所执行"的写法不是直接拒绝，而是升级审批——写法本身不一定是攻击，但至少该让人看到原文后亲手点批准。语义是"宁可多问，不漏问"。
• 两级审批缓存（permission.py#L456-L460）：本次会话批过的命令不重复问（防信任漂移）；选"总是允许"的命令存成 JSON 白名单，跨会话生效，还会派生前缀规则（同类npm test命令下次免审）。想管理已批准的命令，用/approved查看。

四种权限模式（/permission切换）覆盖不同场景：

另外，你可以在settings.json的permissions段写allow/deny/ask内容级规则（如Bash(npm test)），优先级 deny > ask > allow，连 bypass 模式也不豁免用户的显式 deny（tool_permissions.py#L39-L44）。

相关源码速查

小结

CodeAgent 的权限安全体系核心思路可以概括为一句话：底线不可绕、白名单优先、拿不准就问人。5 道闸门管命令，路径白名单管文件，bwrap 沙箱在 OS 层兜底，审批缓存保证安全不打扰。如果你也在做 Agent 类项目，这套"顺序即优先级"的防线设计非常值得参考——先读 permission.py 的 check() 主流程，再顺着它 import 的每个子模块走一遍，基本就能读懂全部设计细节。