第十六课：工具系统

学习目标

• 理解 Codex 的工具系统架构
• 掌握 shell 和 apply_patch 工具
• 了解工具注册和调用流程
• 理解工具执行安全机制

一、工具系统概述

Codex 的工具系统让模型能够与外部世界交互。模型可以执行 shell 命令、修改文件、读取文件内容。工具系统是 Agent Loop 的核心组件。

二、核心工具

2.1 shell 工具

shell 是最核心的工具，让模型可以执行任意命令：

{
  "name": "shell",
  "arguments": {
    "command": "python src/test.py"
  }
}

执行流程：

1. 模型请求调用 shell
2. Codex 检查沙盒策略
3. 检查审批策略（可能需要用户确认）
4. 在沙盒中执行命令
5. 收集 stdout/stderr
6. 返回结果给模型

2.2 apply_patch 工具

apply_patch 用于修改文件，使用特殊的 patch 格式：

*** Begin Patch
*** Update File: src/utils.ts
@@ -10,3 +10,3 @@
- const x = 1;
+ const x = 2;
*** End Patch

Patch 格式说明：

• *** Begin Patch：开始标记
• *** Update File: path：指定要修改的文件
• @@ -old +new @@：修改位置
• - 删除行，+ 新增行
• *** End Patch：结束标记

2.3 文件读取

模型可以通过 shell 工具读取文件：

cat src/utils.py

三、工具注册

工具在 Codex 启动时注册，定义工具的名称、描述和参数 Schema：

{
  "type": "function",
  "name": "shell",
  "description": "Execute a shell command",
  "parameters": {
    "type": "object",
    "properties": {
      "command": {"type": "string"}
    },
    "required": ["command"]
  }
}

四、工具执行安全

每次工具调用前，Codex 会检查：

1. 沙盒策略：read-only/workspace-write/danger-full-access
2. 审批策略：untrusted/on-request/never
3. ExecPolicy 规则：自定义的命令执行策略

五、本课小结

要点	说明
shell 工具	执行 shell 命令
apply_patch	修改文件（patch 格式）
工具注册	启动时注册 JSON Schema
安全检查	沙盒 + 审批 + ExecPolicy

下一步

下一课我们将了解上下文管理。