apply_patch 工具

使用结构化补丁格式来应用文件更改。这非常适合多文件或多变更块编辑，因为此时单个 edit 调用会显得脆弱。

该工具接受一个单独的 input 字符串，其中包含一个或多个文件操作：

*** Begin Patch
*** Add File: path/to/file.txt
+line 1
+line 2
*** Update File: src/app.ts
@@ optional change context
-old line
+new line
*** Update File: src/old-name.ts
*** Move to: src/new-name.ts
@@
 context line
-old line
+new line
*** Update File: src/tail.ts
@@
+appended last line
*** End of File
*** Delete File: obsolete.txt
*** End Patch

*** Move to: 应紧跟在对应的 *** Update File: 头之后的那一行。*** End of File 出现在其所终止的变更块行之后，表示该变更块一直延伸到文件末尾。

参数¶

• input（必填）：完整的补丁内容，包括 *** Begin Patch 和 *** End Patch。

说明¶

• 补丁路径支持相对路径（相对于工作区目录）和绝对路径。
• 对于字面意义上的 ~ 目录中的文件，请使用 ./~/file；~/file 保留其主目录（home-directory）的含义。
• tools.exec.applyPatch.workspaceOnly 默认为 true（限制在工作区内）。仅当您有意让 apply_patch 在工作区目录之外写入/删除时，才将其设为 false。
• 此设置与 tools.exec.mode 无关。设置 tools.exec.mode: "full" 不会解除 apply_patch 的工作区边界。
• tools.fs.workspaceOnly 会独立地限制 apply_patch，因此清除其中一个设置可能会让另一个设置仍然生效。
• 显式的会话权限模式会覆盖上述两个配置设置：full 解除其限制，guarded 和 workspace 会限制 apply_patch，而 read-only 则不会提供该工具。
• 在 full 模式下，必需的工作区根目录和沙箱限制仍然适用。请将补丁路径保持在必需根目录内；更改任一配置设置或会话模式都无法解除该限制。
• 当主机工作区边界拒绝补丁时，操作员日志会指出负责的配置、会话策略、worker 默认值或必需根目录。此提示在 OpenClaw 和 Codex 框架中均可用；模型可见的拒绝信息保持不变。沙箱桥（sandbox bridge）拒绝会保留其自身的解释。
• 内存刷新（memory-flush）运行仅暴露 read 和仅追加的 write，因此即使在 full 模式下，apply_patch 也不可用。
• 整个代理都在 worker 上执行（worker-turn）的运行会忽略这两个配置设置。在没有权限模式的情况下，只要 apply_patch 可用，它们就会限制它；显式的 full 模式会禁用该工具限制。仅用于远程命令（remote-exec）的 worker 会遵循本地运行代理的文件工具策略。
• *** Add File: 和非自身的 *** Move to: 要求目标路径不存在。若要有意替换某个路径，请在同一补丁中先删除它，然后再添加或移动替换内容。
• 对于工作区内的主机路径，更新可以遵循仍位于工作区内的目录别名。添加和移动到新文件会拒绝带别名的父目录；删除最终的符号链接会移除链接本身。通过别名移动到同一文件时，会在原位置应用更新。
• 在 *** Update File: 的变更块中使用 *** Move to: 来重命名文件。
• 需要时，*** End of File 可标记仅限文件末尾（EOF）的插入。
• 默认对所有模型启用。设置 tools.exec.applyPatch.enabled: false 可禁用它，或使用 tools.exec.applyPatch.allowModels 将其限制为特定模型（接受类似 gpt-5.4 的原始 ID 或类似 openai/gpt-5.4 的完整 ID）。
• 该工具的启用和模型设置位于 tools.exec.applyPatch.* 下。

示例¶

{
  "tool": "apply_patch",
  "input": "*** Begin Patch\n*** Update File: src/index.ts\n@@\n-const foo = 1\n+const foo = 2\n*** End Patch"
}

相关¶

Diffs

用于变更展示的只读 diff 查看器。

Exec tool

代理可执行的 Shell 命令。

Code execution

使用 xAI 进行沙箱化远程 Python 分析。