> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 文件处理

> 让代理读写本地文件系统

文件工具允许代理访问本地文件系统。未使用绝对路径时，路径默认相对工作区根目录解析。

***

## 启用方式

文件工具依赖 `ALLOW_LOCAL_TOOLS=true`，默认关闭以避免托管或共享环境下的误访问。

```bash theme={null}
export ALLOW_LOCAL_TOOLS=true
```

***

## 可用操作

* `read_file`：读取文件内容
* `write_file`：写入文件，必要时自动创建父目录
* `list_dir`：列出目录内容
* `apply_patch`：以统一 diff 的方式精确修改已有文件（推荐）

***

## 示例

> "读取 `projects/ironclaw/notes.md`"

> "写一个 README 到 `projects/ironclaw/README.md`"

> "列出 `projects/` 目录下有哪些文件"

> "把 `projects/notes.md` 的状态改成 Completed"

***

## 安全考虑

<AccordionGroup>
  <Accordion title="路径解析与沙箱" icon="folder">
    相对路径如 `notes/todo.md` 会解析为 `<workspace>/notes/todo.md`，绝对路径按原样处理。
  </Accordion>

  <Accordion title="路径穿越防护" icon="shield">
    会检测并拦截 `../` 等路径穿越模式，阻止越出工作区根目录。
  </Accordion>

  <Accordion title="文件内容脱敏" icon="search">
    `read_file` 输出会经过 Safety Layer；疑似 API Key、Token、私钥等敏感内容会被打码。
  </Accordion>

  <Accordion title="不经过 shell 解释" icon="terminal">
    文件路径不会送入 shell。路径中的 `;`、`&`、`$()` 仅按普通字符处理，无法注入命令。
  </Accordion>
</AccordionGroup>