自学教程

Codex CLI Skills、沙箱与示例

Codex 教程

Codex CLI 是命令行客户端，Skills（技能） 是可复用的能力包，用于扩展代理的任务处理逻辑；沙箱（Sandbox） 是安全隔离执行环境，用来限制文件读写、命令执行、MCP调用权限。二者搭配，在终端交互、非交互自动化场景下，安全加载并运行各类预置或自定义技能。本文讲解技能加载、沙箱模式、配置、实操示例与安全规范。

一、Codex CLI Skills 概述

Skills 是一组封装好的指令、工具集、MCP配置、任务模板的集合，可一键导入Codex会话，避免重复编写提示词与工具配置。技能可分为官方内置技能与用户自定义技能。

1.1 技能分类

  1. 内置技能：Codex原生自带，无需额外安装，例如代码评审、单元测试生成、重构、文档生成。
  2. 自定义技能：用户编写的技能包，以文件夹形式存放，包含技能描述、MCP引用、规则、钩子配置，可纳入Git仓库团队共享。

1.2 技能加载方式

方式1：会话内动态加载（交互模式）

# 启动codex交互会话
codex
# 斜杆命令加载技能
/skills load code-review

方式2：配置文件永久加载（config.toml）

[skills]
enable = ["code-review", "test-generator"]
# 加载自定义本地技能包路径
custom_skill_paths = ["./.codex/skills/"]

方式3：非交互模式单次临时加载

codex exec --skills "code-review" "评审当前git变更"

1.3 技能管理命令

# 列出所有可用技能
/skills list查看指定技能详情
/skills info code-review
重载技能配置
/skills reload
卸载技能
/skills unload test-generator

注意：技能加载后，会合并指令到当前代理上下文；多个技能同时加载时，若存在冲突规则，项目AGENTS.md与rules.toml优先级高于技能内定义。

二、Codex 沙箱（Sandbox）机制

沙箱是Codex CLI的安全隔离层，用于约束技能、子代理、工具调用的操作边界，防止误操作删除文件、执行高危命令、访问未授权MCP服务。沙箱分为三种预设模式，和前文系列文档保持一致。

2.1 三种沙箱模式

模式权限说明适用场景
read-only仅读取文件，禁止修改文件、执行shell命令代码审计、文档阅读、PR评审
workspace-write允许读写当前工作目录文件；禁止系统级高危命令本地开发、代码重构、生成测试文件
danger-full-access完整系统权限，可执行任意shell命令、访问全部MCP仅隔离容器环境，生产环境慎用

2.2 沙箱配置位置

  1. 全局默认沙箱：~/.codex/config.toml
  2. 项目级沙箱：.codex/config.toml，优先级更高
  3. 技能单独指定沙箱：技能包内可定义本技能使用的沙箱，加载技能时自动切换
  4. 子代理独立沙箱：子代理toml配置可单独设置沙箱，和主代理隔离

项目配置示例：

[sandbox]
default_mode = "workspace-write"
# 额外禁止路径
block_paths = ["/etc", "/usr/bin", ".env"]

2.3 沙箱生效范围

沙箱会同时约束：

  • CLI内置工具（文件读写、bash执行）
  • 加载的Skills技能包
  • 派生的子代理
  • MCP服务调用权限
  • 钩子脚本执行权限

沙箱拦截行为：当技能尝试执行超出权限的操作，Codex直接阻断并返回安全告警，不会执行操作。

三、Skills、沙箱协同逻辑

  1. Codex CLI启动，读取项目配置，设置默认沙箱。
  2. 加载指定Skills，技能自带工具、指令、可选沙箱覆盖规则。
  3. 代理执行任务，所有工具调用都经过沙箱校验。
  4. 若技能配置独立沙箱，会临时覆盖会话默认沙箱；技能执行结束，恢复原有沙箱。
  5. rules.toml硬规则在沙箱校验之后二次校验，形成双层防护。

双层安全：沙箱控制基础权限，rules.toml定义细粒度黑名单。

四、实操完整示例

示例1：交互模式加载代码评审技能，read-only沙箱

# 进入codex交互会话
codex
# 切换沙箱为只读
/sandbox set read-only
# 加载代码评审技能
/skills load code-review
# 执行评审任务
评审当前项目src目录代码，列出安全隐患与规范问题

示例2：非交互模式，加载技能+指定沙箱（CI流水线推荐）

codex exec \
  --skills code-review \
  --sandbox read-only \
  --quiet \
  "评审git diff变更，输出markdown问题清单"

示例3：自定义技能包目录结构

自定义技能放在项目 .codex/skills/，例如 auto-test 技能：

.codex/skills/auto-test/
├─ skill.json       # 技能元信息，名称、描述、默认沙箱
├─ instructions.md  # 技能系统提示词
├─ mcp.toml         # 技能附带MCP服务配置
└─ rules.toml       # 技能局部规则

skill.json 示例

{
  "name": "auto-test",
  "description": "自动生成单元测试",
  "default_sandbox": "workspace-write"
}

示例4：限制技能可访问MCP服务

在config.toml中配置，限制加载的技能只能访问指定MCP服务

[skills.security]
mcp_allowlist = ["git", "db"]
block_unknown_mcp = true

五、安全最佳实践

  1. 技能最小权限原则：代码评审类技能固定使用read-only；代码生成使用workspace-write。
  2. 不使用来源不明的第三方技能包，外部技能加载前人工审查内部指令与MCP配置。
  3. 技能自带的danger-full-access沙箱，在本地开发环境默认禁止加载。
  4. 非交互自动化任务，技能和沙箱参数在命令行显式声明，便于审计。
  5. 技能内的规则仅作为业务指引，高危防护仍然依靠项目rules.toml。
  6. 多技能组合使用时，避免多个技能同时修改同一份文件，防止冲突。

六、常见问题

Q：加载技能之后沙箱会自动改变吗？
A：如果技能包定义了default_sandbox，加载时会临时切换；任务结束恢复会话原有沙箱，也可以手动锁定沙箱不允许技能修改。

Q：技能是否在非交互模式codex exec中可用？
A：完全支持，--skills参数可以加载技能，沙箱配置同样生效。

Q：沙箱是否可以单独对子代理生效？
A：可以，子代理配置文件可单独定义沙箱，不受主会话沙箱影响。

Q：技能里的MCP配置会覆盖项目MCP吗？
A：不会，技能MCP仅追加，同名MCP服务项目配置优先级更高。

七、总结

Codex CLI的Skills是可复用的任务能力包，内置或自定义技能可以快速扩展代理功能；沙箱是底层安全隔离机制，用来限制文件读写、命令执行和MCP访问权限。

在CLI交互与非交互场景，可按需加载技能，搭配对应的沙箱模式，配合rules.toml、AGENTS.md、MCP、子代理，构建安全可复用的自动化开发能力。技能适合封装重复工作流，沙箱保障操作边界，二者结合是Codex CLI自动化的核心能力。

标签：

0 条笔记