LLM Wiki

Appearance

Built 26/04/16 13:13commit cc1e88d

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:

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

The 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 doctor and look for reason=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:

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

This 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.