OpenClaw Skills Symlink Escape
中文 | English
Summary
A skill path that looks valid in ~/.openclaw/skills/ can still be rejected by OpenClaw if it resolves outside the configured skills root. In practice, a symlink such as ~/.openclaw/skills/llm-wiki -> ~/csh/llm-wiki/.codex/skills/llm-wiki may look installed at the filesystem level while the official skill loader silently skips it as a symlink-escape.
Symptom
Running pnpm openclaw doctor surfaced:
[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-wikiThe trap is that manual inspection still makes the skill look present: the symlink exists, the files are readable, and a human or agent can open SKILL.md directly.
Root Cause
OpenClaw resolves the real path of managed skills and rejects any skill whose resolved location escapes the configured skills root. That means a root-local symlink is not enough. The loader cares about the resolved target, not only the entry path.
How To Confirm
- Check whether the skill path under
~/.openclaw/skills/is a symlink. - Run
pnpm openclaw doctorand look forreason=symlink-escape. - Compare the requested path with the resolved path and verify that the resolved path falls outside
~/.openclaw/skills. - Distinguish between "I can read this path" and "the official skill loader accepts this path".
Fix
Use a real directory inside ~/.openclaw/skills/ instead of a symlink that points outside the root.
Example fix:
mkdir -p ~/.openclaw/skills
rm -rf ~/.openclaw/skills/llm-wiki
cp -a /root/repos/llm-wiki/.codex/skills/llm-wiki ~/.openclaw/skills/llm-wikiThis keeps the installed skill fully inside the configured root, which matches the loader's security model.
Operational Lesson
For OpenClaw-managed skills, "visible on disk" is not the same as "accepted by the loader". Validate skill installation with the official loader path, not only with filesystem checks.