LLM Wiki

Appearance

Built 26/04/16 13:13commit cc1e88d

OpenClaw Skills Symlink Escape ​

中文 | English

摘要 ​

即使一个 skill 路径表面上已经挂在 ~/.openclaw/skills/ 下面，只要它 resolve 之后落到了 skills 根目录之外，OpenClaw 仍然会拒绝加载。实践里，这意味着像 ~/.openclaw/skills/llm-wiki -> ~/csh/llm-wiki/.codex/skills/llm-wiki 这样的软链，虽然在文件系统层面“看起来已经安装”，但官方 skill loader 仍会把它判定为 symlink-escape 并直接跳过。

现象 ​

执行 pnpm openclaw doctor 后出现：

text
[skills] Skipping escaped skill path outside its configured root:
source=openclaw-managed
root=~/.openclaw/skills
reason=symlink-escape
requested=~/.openclaw/skills/llm-wiki
resolved=~/csh/llm-wiki/.codex/skills/llm-wiki

这个问题的迷惑性在于，手动检查时 skill 又像是“存在的”：软链在，文件能读，人和 agent 都能直接打开 SKILL.md。

根因 ​

OpenClaw 会对托管 skill 的真实路径做 resolve，只要 resolve 之后的目标逃离了配置好的 skills root，就会拒绝加载。也就是说，入口路径落在根目录内还不够，loader 真正在意的是最终落点，而不是表面路径。

如何确认 ​

  • 检查 ~/.openclaw/skills/ 下的 skill 是否是软链。
  • 运行 pnpm openclaw doctor，确认是否出现 reason=symlink-escape。
  • 对比 requested path 与 resolved path，确认 resolved path 是否落在 ~/.openclaw/skills 之外。
  • 明确区分“这个路径我能读”和“官方 loader 接受这个路径”是两回事。

修复方法 ​

不要再用指向根目录外的软链，而是在 ~/.openclaw/skills/ 里放一个真实目录。

例如：

bash
mkdir -p ~/.openclaw/skills
rm -rf ~/.openclaw/skills/llm-wiki
cp -a /root/repos/llm-wiki/.codex/skills/llm-wiki ~/.openclaw/skills/llm-wiki

这样安装后的 skill 完整落在受信任的 skills root 内，符合 loader 的安全模型。

实践意义 ​

对 OpenClaw 托管 skill 来说，“磁盘上看得见”不等于“loader 真接受”。验证 skill 是否生效时，应优先走官方 loader 的检查路径，而不是只做文件系统层面的确认。

相关页面 ​