OpenClaw 工具与 Skill 完全手册 2026：内置工具清单 + 自定义开发

写了半年 OpenClaw，我发现国内社区最缺的不是概念文章，而是查得到参数的工具手册。半夜 agent 报错，你需要的不是"什么是 Skill 的设计哲学"，而是"Write 工具第二个参数到底叫 content 还是 text"、“SKILL.md 的 frontmatter 是不是必须用三个短横线”、“tavily-search 在国内网络下为啥加载不出来”。

这篇文章就是这份手册。覆盖 OpenClaw 2026 的 9 个内置工具、ClawHub skill 加载机制、SKILL.md 完整契约、tavily-search 实操配置、自定义 skill 开发流程，以及我踩过的 5 个常见坑。如果你已经在用 OpenClaw 写 skill，建议直接 Ctrl+F 找你要的工具名；如果刚入门，先看 OpenClaw 架构深度解析。

为什么需要这份手册

OpenClaw 官方文档是为理解设计的，不是为查询设计的。想知道 skill 的哲学？官网写得不错。想知道 Write 工具到底有几个参数？你得翻三篇教程交叉对照才能确认。

我吃过这个亏。去年调试一个自定义 skill 加载失败，我花了两小时才发现是 SKILL.md 的 --- 分隔符被编辑器替换成了全角破折号。后来写一个 CI 脚本调用 OpenClaw，我凭直觉给 Bash 工具的 timeout 参数传了 60，结果命令直接被杀——因为那个字段单位是毫秒不是秒。这些时间本来都是可以省的，只要有一张查询表。

另外一个动机是 GSC 数据。我自己博客的搜索后台显示，“openclaw write tool parameters path content”、“openclaw clawhub skill skill.md tavily-search” 这些长尾词合计有上万次展示，但点击率接近 0——因为没有任何一篇文章直接回答这些问题。所有现有文章都在讲理念。这个位置有一个巨大的"参考手册"形状的空洞。

9 个内置工具的精确签名

OpenClaw 内置 9 个工具，除非在 openclaw.json 里通过 disabled_tools 显式禁用，否则每个 agent 都能用。下面给出每个工具的精确参数名、类型、最常踩的坑。

Read——读文件

最常见的错是传相对路径。OpenClaw 不会展开 ~ 也不会按当前工作目录解析，它把字符串按字面量使用。一定要传 /Users/你/project/config.json 这种完整路径。

读目录会报错不会列出内容，想列目录用 Glob 或 Bash ls。读超过 2000 行的文件会被静默截断——想读完整文件就要循环传 offset 和 limit。

Write——写文件

三个团队踩过同一个坑：Write 不会自动创建父目录。如果调用 Write("/tmp/new/sub/file.txt", "...") 但 /tmp/new/sub 不存在，直接报错——不会静默 mkdir。正确做法是先用 Bash 跑一次 mkdir -p。

第二个坑是 content 完全按字面量写入。OpenClaw 不做任何模板渲染、不替换环境变量、不转义特殊字符。你传什么，磁盘上就是什么。

Edit——改文件

同一会话中必须先 Read 后 Edit。OpenClaw 强制这个规则以防止覆盖 agent 没看过的改动。跳过 Read 会直接报 “file not read in this session”。

old_string 必须唯一这个约束是编辑失败的主因。如果你想替换 return x 但文件里有三处，Edit 会拒绝执行。解决办法是加上足够的上下文（通常 2-3 行），让字符串在整个文件里唯一。

Bash——跑命令

OpenClaw 的 Bash 在持久工作目录里跑，但不共享 shell 状态——你在一次调用里 export FOO=bar，下一次调用看不到。需要在单次调用内生效就内联前缀：PATH=/opt/tools:$PATH mytool。

timeout 单位是毫秒，不是秒。我见过有人传 timeout: 60 期望 1 分钟，结果立刻被杀。

Grep——搜内容

Grep 底层是 ripgrep，所以字面花括号需要转义（interface\{\}），. 默认不匹配换行。output_mode 最值得记——默认 files_with_matches 只返回路径列表，这正是你后续 Read 时想要的。

Glob——找文件

用 Glob 按文件名找文件，不是按内容。结果按修改时间排序（最新优先），查"我最近改过哪些文件"特别好用。

Task——派生子 agent

Task 会派生一个拥有独立上下文窗口的子 agent。子 agent 看不到父会话——你需要的所有信息都要塞进 prompt 里。返回值是子 agent 的最终消息，不包含它的中间工具调用。

TodoWrite——维护任务列表

替换语义是反直觉的。TodoWrite 不是追加，而是每次传完整的当前状态，包括已完成和进行中的项。忘了这点，agent 会以为任务丢了。

WebFetch / WebSearch——联网

这两个受 openclaw.json 里 webAccess 策略管控。参数简单（WebFetch 传 url、WebSearch 传 query），但如果没返回结果，先看 webAccess.allowedDomains——OpenClaw 在 production 模式下默认拒绝非白名单域名。国内用户还要注意，如果通过代理访问，代理配置在 ~/.openclaw/proxy.json，不是操作系统的 HTTP_PROXY。

ClawHub Skill 架构

OpenClaw 最容易混淆的地方是 “skill” 有两层含义：一层是内置工具（runtime 硬编码的 Read/Write 那些），另一层是 ClawHub skill（SKILL.md + 附加文件）。这一节讲后者。

SKILL.md 格式

每个 ClawHub skill 是一个文件夹，里面必须有 SKILL.md。frontmatter 的契约极简：

---
name: my-skill-name
description: 当用户提到 X、Y、Z 时触发，用来完成 A、B、C 操作。
---

# Skill Body

skill 被触发后 agent 读到的指令。
可以包含代码块、示例、引用其他文件。

我违反过、也后悔过的两条规则：

description 不是文档，是触发条件。 OpenClaw 会把每个 skill 的 description 塞进 agent 的 system prompt 作为"工具目录"。如果写"处理天气相关请求"，agent 可能会用；如果写"天气 skill"，agent 永远不知道什么时候该用。把 description 写成触发条件句，不是名词标题。

附加文件放在 skill 文件夹内，用相对路径引用。 skill 需要一个 Python 脚本？把它放在 SKILL.md 旁边，在 body 里写 执行 scripts/fetch.py。agent 会以 skill 文件夹为根解析路径。不要写绝对路径——别的用户安装后会全部失效。

加载优先级

OpenClaw 按三级目录扫描，越具体越优先：

1. <workspace>/clawhub/skills/ ——项目级，最高
2. ~/.openclaw/skills/ ——用户级
3. ClawHub 远程仓库 ——系统级，本地有缓存

同名 skill 按上述顺序覆盖。跑 openclaw skills list 可以看每个 skill 实际加载的路径，谁覆盖谁一眼看清。

tavily-search 完整配置（国内场景）

tavily-search 是最常被搜索的 ClawHub skill，这里给出国内网络下的实操配置。skill 位置 clawhub/skills/tavily-search/SKILL.md，参数：

配置步骤：

# 1. 安装 skill
openclaw skills install tavily-search

# 2. 写入 API Key
echo 'TAVILY_API_KEY=tvly-xxxx' >> ~/.openclaw/.env

# 3. 国内用户必须配代理
cat > ~/.openclaw/proxy.json <<EOF
{
  "http": "http://127.0.0.1:7890",
  "https": "http://127.0.0.1:7890",
  "allowedDomains": ["api.tavily.com"]
}
EOF

# 4. 验证
openclaw skills list | grep tavily

国内替代方案：如果你不想折腾海外 API，可以自己写一个基于 Bing/SerpAPI 的 skill，只需要一份 SKILL.md + 一个 curl 命令，参考下一节的自定义 skill 示例改造即可。实际用下来，国内查中文内容用 Bing 的准确率反而比 Tavily 高。

如果 openclaw skills list 没显示 tavily-search，九成是 SKILL.md 的 frontmatter --- 被富文本编辑器替换成了特殊字符。用 hexdump -C SKILL.md | head 看前几个字节，正常的 --- 是 2d 2d 2d；如果看到 e2 80 94（em dash）就得重写。

自定义一个可用的 Skill

下面是一个最小可用的 skill，查询指定城市的当前天气。保存到 <workspace>/clawhub/skills/weather/SKILL.md：

---
name: weather
description: 当用户询问某个城市的当前天气、温度、气象时触发。调用 wttr.in 返回简短天气摘要。
---

# Weather Skill

被触发时，从用户消息中提取城市名，执行：

    curl -s "wttr.in/${CITY}?format=3"

解析输出，用友好的一句话回复。
如果城市名不明确（如"老家"），先向用户确认。

就这样——不用注册、不用编译。保存后 openclaw skills reload，agent 就能用。

三条分辨"能用的 skill"和"不能用的 skill"的原则：

让 description 承担加载权重。 agent 在决定是否调用之前只看 description，根本看不到 body。如果 description 不能让触发条件一眼可见，agent 就会漏调。我第一个 skill 的 description 改了三次，agent 才开始稳定触发。

body 写成动作导向。 body 是 agent 已经决定调用之后才读的。所以不要写"这个 skill 是用来…的"这种导言，直接列步骤。

用 git 管理 skill 目录。 每个上过生产的 skill 都至少经历过一次 regression。skill 是纯文本文件夹，在 skill 根目录 git init 零成本。更深入的版本管理策略在 OpenClaw 记忆管理策略 里讲过。

OpenClaw vs CrewAI vs AutoGen vs LangGraph

这张对比表是我当初选型时希望有的。四个框架理论上都能搭多 agent 系统，差别在胶水代码由谁写。

我在四个框架里都实际跑过项目后的真实推荐：

选 OpenClaw：agent 要长期驻在聊天渠道里（飞书、企微、Discord），且希望非工程同事能提交 skill。文件系统优先的设计是杀手锏——PM 可以直接提 PR 加 skill，不用学 Python。

选 CrewAI：一次性研究管道。给一个话题、研究、写报告、结束。CrewAI 的 Process 抽象（sequential、hierarchical）为这种场景而生。

选 AutoGen：任务中途需要 agent 互相对话的场景。AutoGen 的 GroupChat 比 OpenClaw 的 sessions_send 成熟。

选 LangGraph：工作流本身就是有状态、有循环、有条件分支的图。如果你在纸上画过状态机，选它。

不推荐用 OpenClaw 做纯 CLI 工具或批处理任务，除非已经在用它做别的事。它的渠道优先设计对这种场景是过度设计。这一点我在 OpenClaw vs 传统 AI Agent 框架 里有更详细的拆解。

5 个常见错误与修复

按我收到求助的频率排序。

“skill 加载了但从不触发”：description 写得太含糊。运行 openclaw debug tools 看 agent 实际看到的工具目录。如果 description 是名词短语（“天气工具”），改成触发条件句（“当用户询问某个城市的天气时”）。

“Write 报 parent directory not found”：Write 不会 mkdir。前面加 Bash: mkdir -p $(dirname /path/to/file)。

“Edit 报 string not unique”：old_string 匹配到多处。加上下文让它唯一，或者传 replace_all: true——但前提是你真的想改所有地方。

“两个相似 skill agent 选错”：skill 名字和 description 在触发空间里竞争。如果同时存在 search-web 和 search-docs，其中一个的 description 要写得更具体（“用于公司内部文档"vs"用于公网”）。用 openclaw skills list 把 description 并排看清再决定。

“Bash 报 permission denied”：查 ~/.openclaw/permissions.json。OpenClaw 本地权限白名单，没匹配的命令要交互确认。CI 环境提前用 openclaw permissions add "git *" 加白。完整权限模型在 OpenClaw 多 Agent 配置指南 里。

记住三件事

如果只带走三点：

把 description 当触发条件写，不是标题。 这是 skill 开发第一大错，几乎没有之一。

所有路径都用绝对路径。 每个涉及文件的工具（Read、Write、Edit、Glob）都只认绝对路径。相对路径会以让你浪费几小时的方式静默失败。

把这篇加入书签。 OpenClaw 大版本之间参数名会变，但查询手册的形状稳定。agent 出问题时，十有八九是参数名错了、frontmatter 字段缺了，或者 skill 放错文件夹。先查表再提 bug。

想深入了解生产环境多 agent 模式，OpenClaw 自动化避坑指南 列了启发本文一半内容的生产事故；社区 skill 浏览去 ClawHub 官方仓库。

相关阅读

• OpenClaw 架构深度解析 ——Gateway-Agent-Skill 模型
• OpenClaw 多 Agent 配置指南 ——bindings、Lobster、成本优化
• OpenClaw vs 传统 AI Agent 框架 ——框架对比
• OpenClaw 自动化避坑指南 ——生产事故案例
• OpenClaw 记忆管理策略 ——SOUL.md 与记忆治理