File System Skill 详细使用指南¶
File System Skill 让 OpenClaw 能够读取、写入和管理本地文件，是连接 AI 与本地数据的桥梁。
目录¶
Skill 简介¶
什么是 File System？¶
File System Skill 赋予 OpenClaw 操作本地文件的能力，让 AI 能够： - 📖 读取文件内容 - ✍️ 写入和创建文件 - 📁 管理目录结构 - 🔍 搜索文件内容 - 📊 批量处理文件
核心能力¶
| 能力 | 说明 | 示例 |
|---|---|---|
| 读取 | 读取各种格式文件 | 文本、代码、配置文件 |
| 写入 | 创建和修改文件 | 生成报告、保存数据 |
| 管理 | 目录操作 | 创建、删除、移动 |
| 搜索 | 文件内容搜索 | 代码搜索、日志分析 |
安装方法¶
方式一：通过 ClawHub 安装（推荐）¶
方式二：手动安装¶
验证安装¶
基本使用¶
示例 1：读取文件¶
用户输入：
AI 响应：
我来读取这个文件...
📄 文件信息：
- 路径：/home/user/documents/report.txt
- 大小：15.3 KB
- 修改时间：2026-03-08 14:30
📝 文件内容：
═══════════════════════════════════════
月度销售报告 - 2026年2月
═══════════════════════════════════════
一、总体概况
本月销售额：¥2,580,000
环比增长：+15.3%
同比增长：+42.7%
二、产品销售情况
1. 产品A：¥980,000（38%）
2. 产品B：¥750,000（29%）
3. 产品C：¥520,000（20%）
4. 其他：¥330,000（13%）
三、区域分布
- 华东区：35%
- 华南区：28%
- 华北区：22%
- 其他：15%
四、下月计划
目标销售额：¥3,000,000
重点产品：产品A新品推广
报告人：张三
日期：2026-03-01
═══════════════════════════════════════
需要我对报告进行分析吗？
示例 2：写入文件¶
用户输入：
AI 响应：
我来为您创建待办事项列表...
✍️ 创建文件：/home/user/todo.md
📝 文件内容预览：
═══════════════════════════════════════
# 待办事项列表
创建时间：2026-03-09 10:30
## 🔴 高优先级
- [ ] 完成项目报告
- [ ] 回复客户邮件
- [ ] 准备周会PPT
## 🟡 中优先级
- [ ] 更新文档
- [ ] 代码审查
- [ ] 学习新技能
## 🟢 低优先级
- [ ] 整理桌面文件
- [ ] 备份数据
- [ ] 阅读技术文章
---
## 📊 统计
- 总计：9 项
- 高优先级：3 项
- 中优先级：3 项
- 低优先级：3 项
## 💡 提示
使用 `- [x]` 标记已完成事项
═══════════════════════════════════════
✅ 文件创建成功！
需要我添加更多内容吗？
示例 3：列出目录¶
用户输入：
AI 响应：
我来查看您的项目目录...
📁 目录：/home/user/projects
📂 项目列表：
┌─────────────────────────────────────────┐
│ 名称 │ 类型 │ 大小 │ 修改时间 │
├─────────────────────────────────────────┤
│ 📁 openclaw │ 目录 │ 2.3MB │ 2026-03-08 │
│ 📁 website │ 目录 │ 15MB │ 2026-03-07 │
│ 📁 mobile-app │ 目录 │ 45MB │ 2026-03-05 │
│ 📁 data-analysis│ 目录 │ 128MB │ 2026-03-01 │
│ 📄 README.md │ 文档 │ 5KB │ 2026-02-28 │
│ 📄 .gitignore │ 配置文件 │ 1KB │ 2026-02-25 │
└─────────────────────────────────────────┘
📊 统计信息：
- 目录数量：4 个
- 文件数量：2 个
- 总大小：190.3 MB
需要我查看某个项目的详细信息吗？
实战示例¶
场景 1：代码审查助手¶
任务：审查代码文件并提供建议
对话流程：
用户：读取 ~/projects/myapp/src/main.js 并审查代码
AI：我来读取并审查这段代码...
📄 读取文件：main.js (3.2 KB)
📝 代码内容：
```javascript
const express = require('express');
const app = express();
const port = 3000;
// 数据库连接
const db = require('./db');
app.get('/users', async (req, res) => {
const users = await db.query('SELECT * FROM users');
res.json(users);
});
app.post('/users', async (req, res) => {
const { name, email } = req.body;
const result = await db.query(
`INSERT INTO users (name, email) VALUES ('${name}', '${email}')`
);
res.json(result);
});
app.listen(port, () => {
console.log(`Server running on port ${port}`);
});
🔍 代码审查报告：
🔴 严重问题： 1. SQL 注入漏洞（第16行） - 问题：直接拼接 SQL 字符串 - 风险：攻击者可执行任意 SQL - 修复：使用参数化查询
🟡 改进建议： 2. 缺少错误处理 - 建议：添加 try-catch 块
app.get('/users', async (req, res) => {
try {
const users = await db.query('SELECT * FROM users');
res.json(users);
} catch (error) {
res.status(500).json({ error: error.message });
}
});
- 缺少输入验证
- 建议：验证 name 和 email 格式
-
可使用 joi 或 express-validator
-
缺少安全中间件
- 建议添加：
🟢 良好实践： - ✅ 使用 async/await - ✅ 模块化数据库连接 - ✅ 使用环境变量（port）
📊 评分：6/10（需要修复安全问题）
需要我生成修复后的完整代码吗？
用户：帮我整理 ~/downloads 目录，将所有图片移动到 ~/Pictures，按日期创建子目录AI：我来帮您整理下载目录...
📁 分析目录：~/downloads
🔍 扫描结果： - 图片文件：156 个（.jpg, .png, .gif） - 文档文件：43 个 - 压缩包：12 个 - 其他：28 个
📊 图片时间分布： - 2026-03：45 个 - 2026-02：67 个 - 2026-01：32 个 - 2025-12：12 个
🔄 执行操作：
-
创建目录结构：
-
移动图片文件：
- 2026-03/IMG_001.jpg ✓
- 2026-03/screenshot_0301.png ✓
- 2026-02/photo_0215.jpg ✓
-
... (共156个文件)
-
生成整理报告：
- 成功移动：156 个
- 跳过重名：0 个
- 失败：0 个
✅ 整理完成！
📄 已创建索引文件：~/Pictures/index.md 包含所有图片的列表和缩略图信息
需要我清理下载目录中的空文件夹吗？
用户：分析 ~/logs/app.log 中的错误信息AI：我来分析日志文件...
📄 读取日志：app.log (15.6 MB, 125,000 行)
🔍 分析结果：
📊 日志概览： - 时间范围：2026-03-01 00:00 ~ 2026-03-09 10:30 - 总记录数：125,000 - 错误数：234 - 警告数：1,567 - 信息：123,199
🔴 错误分析（Top 5）：
- 数据库连接超时（89次）
- 错误：ConnectionTimeoutError
- 时间：主要集中在 09:00-10:00
- 可能原因：高峰期连接池不足
-
建议：增加连接池大小，优化慢查询
-
内存不足（56次）
- 错误：OutOfMemoryError
- 时间：每天凌晨 02:00-03:00
- 可能原因：定时任务占用大量内存
-
建议：优化批处理任务，分批处理
-
API 限流（45次）
- 错误：RateLimitExceeded
- 来源：/api/v1/data/export
-
建议：增加限流阈值或优化导出逻辑
-
文件不存在（28次）
- 错误：FileNotFoundError
- 路径：/tmp/cache/*.tmp
-
建议：检查缓存清理逻辑
-
权限拒绝（16次）
- 错误：PermissionDenied
- 操作：写入 /var/log/
- 建议：检查文件权限配置
📈 时间分布：
💡 优化建议：
立即处理（高优先级）： 1. 增加数据库连接池（当前：10 → 建议：30） 2. 优化凌晨批处理任务内存使用
本周处理（中优先级）： 3. 增加 API 限流配置 4. 修复缓存文件路径问题
持续监控： 5. 设置日志告警（错误数>10/小时） 6. 建立性能基线监控
需要我生成详细的优化方案吗？
用户：读取 ~/projects/myapp/src 目录下所有 .js 文件AI：我来批量读取 JavaScript 文件...
📁 找到 12 个 .js 文件： - main.js - utils.js - config.js - ...
📝 正在读取内容... ✅ 完成！共读取 45KB 代码
需要我对代码进行整体分析吗？
用户：根据模板生成 10 个配置文件AI：我来批量生成配置文件...
📄 模板：config.template 📝 生成文件： - config_001.json ✓ - config_002.json ✓ - ... ✅ 完成！已生成 10 个配置文件
用户：对比 file1.txt 和 file2.txt 的差异AI：我来对比两个文件...
📊 差异分析： - 相同行：156 - 新增行：23 - 删除行：12 - 修改行：8
🔍 详细差异： [显示具体差异内容]
用户：在 ~/projects 中搜索包含 "TODO" 的所有文件AI：我来搜索 TODO 标记...
🔍 搜索结果：
📁 src/main.js (第45行) // TODO: 优化数据库查询
📁 src/utils.js (第12行) // TODO: 添加错误处理
📁 README.md (第23行) - [ ] TODO: 完善文档
共找到 8 个 TODO 项
~/.openclaw/skills/file-system/config.json### 可配置项
```json
{
"allowed_paths": [
"~/documents",
"~/projects",
"~/downloads"
],
"blocked_paths": [
"~/.ssh",
"~/.openclaw/config"
],
"max_file_size": "10MB",
"allow_write": true,
"allow_delete": false,
"backup_on_write": true
}
配置说明¶
| 配置项 | 默认值 | 说明 |
|---|---|---|
allowed_paths |
- | 允许访问的路径 |
blocked_paths |
- | 禁止访问的路径 |
max_file_size |
10MB | 最大文件大小 |
allow_write |
true | 是否允许写入 |
allow_delete |
false | 是否允许删除 |
backup_on_write |
true | 写入前是否备份 |
与其他 Skill 组合¶
组合 1：搜索 + 抓取 + 文件系统¶
搜索资料 → 读取内容 → 保存到本地知识库组合 2：文件系统 + 浏览器自动化¶
读取测试数据 → 自动填充表单 → 保存结果组合 3：文件系统 + 思考¶
读取日志/数据 → 分析推理 → 生成报告常见问题¶
Q1：无法读取某些文件？¶
A：检查以下设置：
1. 文件是否在 allowed_paths 中
2. 文件权限是否正确
3. 文件大小是否超过限制
4. 路径是否在 blocked_paths 中
Q2：写入失败怎么办？¶
A：排查步骤：
1. 检查 allow_write 配置
2. 确认目录存在且有写权限
3. 检查磁盘空间
4. 查看是否有文件被占用
Q3：如何保护敏感文件？¶
A：安全措施：
1. 将敏感目录加入 blocked_paths
2. 设置 allow_delete: false
3. 启用 backup_on_write
4. 定期审计文件访问日志
Q4：批量操作太慢？¶
A：优化建议： 1. 使用通配符批量操作 2. 排除不需要的目录 3. 异步并行处理 4. 增加系统资源
最佳实践¶
✅ 推荐做法¶
- 明确指定路径
- 使用绝对路径或 ~/ 简写
-
避免相对路径造成歧义
-
定期备份重要文件
- 启用
backup_on_write -
建立版本控制
-
合理设置权限
- 最小权限原则
-
敏感目录加入黑名单
-
验证操作结果
- 写入后验证内容
- 删除前二次确认
❌ 避免做法¶
- 不要操作系统文件
- /etc, /bin, /usr 等
-
可能导致系统损坏
-
不要删除不确定的文件
- 先确认内容
-
重要文件先备份
-
不要处理超大文件
- 超过配置限制
- 可能导致内存不足
相关资源¶
- 官方文档：https://docs.openclaw.ai/skills/file-system
- GitHub 仓库：https://github.com/OpenClaw/file-system
- ClawHub 页面：https://clawhub.ai/skills/file-system
总结¶
File System Skill 是 OpenClaw 的"手"，让 AI 能够直接操作本地文件系统。
核心能力： - 📖 读取各种格式文件 - ✍️ 创建和修改文件 - 📁 管理目录结构 - 🔍 搜索和分析内容 - 📊 批量处理文件
典型应用场景： - 代码审查和重构 - 日志分析和监控 - 文档生成和管理 - 数据处理和转换 - 文件整理和归档
安全提示： - 谨慎设置访问权限 - 重要操作前备份 - 定期审计访问日志
建议：这是连接 AI 与本地数据的关键 Skill，几乎所有工作流都需要它！
社区支持¶
欢迎微信扫码加入龙虾俱乐部
获取更多 OpenClaw 使用技巧、问题解答和社区交流。
文档更新时间：2026-03-09 Skill 版本：v2.3.0 适用 OpenClaw 版本：2026.2.x