为什么我的 OpenClaw Skill 不工作？—— 一次 Tool Profile 排查实录

安装了 Skill、配好了 API Key，Agent 却说"我没有这个工具"？问题可能出在你没注意到的一行配置上。

背景

我给 OpenClaw 写了一个 URL 缩短 Skill（shortener-url-dljbz），它通过 curl 调用 dlj.bz 的 API 把长链接变短。Skill 的工作流很简单：

1
2
3
4
5
curl -s -X POST \
  --data-urlencode "url=https://github.com/microsoft/playwright" \
  --data-urlencode "api_key=$DLJ_BZ_API_KEY" \
  -H "Accept: application/json" \
  "http://dlj.bz/api/v2/short"

1
2
3
4
{
  "short": "http://dlj.bz/iH9R",
  "url": "https://github.com/microsoft/playwright"
}

在 Cursor 里运行得很好。但部署到 OpenClaw 之后，Agent 的表现让人困惑——

症状

当我对 OpenClaw Agent 说"帮我缩短这个链接"时，Agent 返回了一大段自言自语：

1
2
3
4
5
6
7
8
I see I need to use the URL shortener skill...
Actually, I don't have curl or exec tools available.
Looking at my tool list, I only have messaging and session management tools.
...
Since I can't execute the skill directly from this interface, you might want to:
1. Use the skill from a different OpenClaw interface
2. Manually use the dlj.bz website
3. Use another URL shortener service

Agent 知道 Skill 存在，能描述它的功能，但就是执行不了。它反复尝试各种思路，最终承认自己"没有 exec 工具"。

排查过程

第一步：确认 Skill 已安装

1
2
ls -la ~/.openclaw/skills/
# shortener-url-dljbz/  ✅ 存在

第二步：确认 Skill 已启用且 API Key 已配置

查看 ~/.openclaw/openclaw.json 的 skills 部分：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "skills": {
    "entries": {
      "shortener-url-dljbz": {
        "enabled": true,
        "env": {
          "DLJ_BZ_API_KEY": "xxxxxxx"
        }
      }
    }
  }
}

一切正常。✅

第三步：确认执行审批没有阻止

1
cat ~/.openclaw/exec-approvals.json

1
2
3
4
5
{
  "version": 1,
  "defaults": {},
  "agents": {}
}

没有任何拒绝规则。✅

第四步：发现真正的问题

最终目光落在 openclaw.json 里一个不起眼的配置上：

1
2
3
4
5
{
  "tools": {
    "profile": "messaging"
  }
}

就是它。

根因：Tool Profile 限制了 Agent 的能力

OpenClaw 使用三层访问控制模型管理 Agent 可以使用的工具：

1
Base Profile → Allow/Deny Lists → Provider-Specific Policy

其中 Base Profile 是第一层，决定了 Agent 的基础工具集。OpenClaw 提供四个预设 Profile：

Profile	包含的工具	适用场景
`full`	所有工具	完全信任的 Agent
`coding`	`group:fs` + `group:runtime` + `group:sessions` + `group:memory` + `image`	编码、文件操作、命令执行
`messaging`	`group:messaging` + 部分 session 工具	仅消息收发
`minimal`	仅 `session_status`	只读观察

而 Tool Group 对应的具体工具是：

Group	包含的工具
`group:runtime`	`exec`, `bash`, `process`
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:web`	`web_search`, `web_fetch`
`group:messaging`	`message`

我的配置是 "profile": "messaging"，这意味着 Agent 只有消息工具——没有 exec（不能执行 curl）、没有 read（不能读取 SKILL.md 的指令）、没有 web_fetch（不能替代 curl 调 API）。

而这个 Skill 是"指令型"的——SKILL.md 告诉 Agent 具体怎么做（读文件 → 执行 curl），而不是提供一个封装好的 tool。Agent 需要 read 来读取指令，需要 exec 来执行 curl。两者都被 messaging profile 拦截了。

修复

方案 A：切换到包含 exec 的 Profile

1
2
3
4
5
{
  "tools": {
    "profile": "full"
  }
}

或者用 coding profile，它包含 group:runtime（exec）和 group:fs（read）。

方案 B：保持 messaging Profile，用 Allow List 添加所需工具

如果你不想给 Agent 完整权限，可以在 messaging 基础上精确添加：

1
2
3
4
5
6
{
  "tools": {
    "profile": "messaging",
    "allow": ["group:runtime", "group:fs"]
  }
}

这样 Agent 既能收发消息，又能执行 curl 和读取文件。

方案 C：仅允许最小权限

1
2
3
4
5
6
{
  "tools": {
    "profile": "messaging",
    "allow": ["exec", "read"]
  }
}

只开放 exec（执行 curl）和 read（读取 SKILL.md），不给 write/edit 等写权限。

用 CLI 快速修改

除了手动编辑 openclaw.json，你也可以用 openclaw config 命令来查看和修改配置：

1
2
3
4
5
6
7
8
# 查看当前配置文件路径
openclaw config file

# 查看当前 tools 配置
openclaw config get tools

# 将 profile 切换为 full
openclaw config set tools.profile "full"

修改后重启 Gateway 使配置生效：

1
openclaw restart

经验总结

1. Skill 不工作 ≠ Skill 有 Bug

Skill 安装正确、API Key 配好、exec-approvals 没阻止——问题出在更上层的 Tool Profile。这是一个容易忽略的配置层。

2. OpenClaw 的三层访问控制要逐层检查

排查工具问题时，按这个顺序：

Base Profile (tools.profile) → Agent 基础能力集
Allow/Deny Lists (tools.allow / tools.deny) → 精细调整，deny 永远优先
Provider-Specific Policy (tools.byProvider) → 针对特定模型的额外限制

3. 指令型 Skill 对 Agent 能力有隐式依赖

“指令型” Skill（SKILL.md 里写的是步骤指引，Agent 自己去执行）要求 Agent 具备：

文件读取 (read) —— 读取 SKILL.md 获取指令
命令执行 (exec) —— 执行 curl、python 等命令
环境变量 —— API Key 等敏感配置

如果你的 Agent 运行在受限 Profile 下（如 messaging、minimal），这类 Skill 天然无法工作。

4. 最小权限原则

OpenClaw 的设计遵循最小权限原则——默认不给，按需开放。deny 永远覆盖 allow。建议从 minimal 或 messaging 起步，通过 allow 精确添加所需工具，而不是直接用 full。

速查清单

当你的 OpenClaw Skill 不工作时：

Skill 文件在 ~/.openclaw/skills/<name>/SKILL.md？
openclaw.json 中 skills.entries.<name>.enabled 为 true？
所需环境变量（如 DLJ_BZ_API_KEY）已在 skills.entries.<name>.env 中配置？
所需二进制（如 curl）在 PATH 中可用？（which curl）
tools.profile 包含 Skill 所需的工具组？（最常被忽略！）
tools.deny 没有阻止所需工具？
tools.byProvider 没有针对当前模型做额外限制？
exec-approvals.json 没有阻止相关命令？

背景

症状