20-文件访问控制与保护目录

原创

于 2026-07-02 07:43:09 发布 · 292 阅读

20 — 文件访问控制与保护目录

系列导读 | 本文是 Codex 安全与权限系列的第六篇（共四篇），深入解析 Codex CLI 的文件访问控制体系，包括受保护的系统目录、自定义保护规则、命令白名单/黑名单、工作目录限制、网络访问控制以及完整的 sandbox 配置段详解。

一、为什么需要文件访问控制？

在传统的开发环境中，你的代码拥有与你本人相同的文件系统权限——可以读取 ~/.ssh/id_rsa、可以修改 /etc/hosts、可以删除整个项目目录。当 AI Agent 获得了执行命令的能力，如果没有文件访问控制，那么 Agent 也同样拥有这些权限。

Codex 的文件访问控制系统通过 三层防护 来解决这个问题：

受保护目录（Protected Directories）— 系统关键路径的自动保护
工作目录限制（Working Directories）— 限制 Agent 可写入的范围
自定义规则（Custom Rules）— 用户定义的额外保护策略

二、受保护的系统目录

Codex CLI 内置了一份 受保护目录列表，这些目录默认禁止 Agent 的写入操作（即使在 workspace-write 模式下），部分目录甚至禁止读取。

默认受保护路径清单

SSH 密钥相关：

~/.ssh/
~/.ssh/*

云服务凭证：

~/.aws/
~/.aws/*
~/.azure/
~/.azure/*
~/.gcp/
~/.gcp/*
~/.config/gcloud/
~/.config/gcloud/*

Git 配置：

~/.gitconfig
~/.git-credentials

系统配置：

/etc/
/etc/*
/usr/
/usr/*

包管理全局配置：

~/.npmrc
~/.pip/
~/.pip/*
~/.gem/
~/.gem/*
~/.cargo/credentials

其他敏感路径：

~/.gnupg/
~/.gnupg/*
~/.netrc
~/.config/gh/
~/.config/gh/*
~/.docker/config.json

保护级别

每个受保护路径有不同的保护级别：

级别	行为	示例
`deny-write`	禁止写入，允许读取	`~/.gitconfig`
`deny-read-write`	禁止读写，完全隔离	`~/.ssh/id_rsa`
`deny-execute`	禁止执行其中的可执行文件	`/etc/` 下的敏感脚本

注意：即使读取受保护目录中的文件（如查看 SSH 公钥）在某些情况下被允许，写入操作一律默认禁止。这是为了防止 Agent 修改或覆盖你的凭证。

保护机制的工作原理

当 Agent 尝试访问受保护目录时，Codex 的沙盒拦截器会在系统调用层面进行检查：

Agent 命令: cat ~/.ssh/id_rsa
            ↓
沙盒拦截器: 检查目标路径 → 匹配 deny-read-write 规则
            ↓
操作被拒绝: "Error: Access denied to protected file ~/.ssh/id_rsa"
            ↓
审批策略: 如果为 on-request，弹窗询问用户是否覆盖保护

三、自定义保护规则配置

除了内置的受保护目录，你可以在 codex.json 中定义自己的保护规则。

语法

{
   
   
  "sandbox": {
   
   
    "protected_paths": [
      {
   
   
        "path": "/path/to/protect",
        "level": "deny-write",
        "description": "自定义保护规则"
      }
    ]
  }
}

示例：保护公司内部私密项目

{
   
   
  "sandbox": {
   
   
    "protected_paths": [
      {
   
   
        "path": "/home/user/projects/internal/keys",
        "level": "deny-read-write",
        "description": "内部密钥目录"
      },
      {
   
   
        "path": "/home/user/.config/proxy-config.ovpn",
        "level": "deny-read-write",
        "description": "代理配置文件"
      },
      {
   
   
        "path": "/home/user/.env.production",
        "level": "deny-read-write",
        "description": "生产环境变量"
      }
    ]
  }
}