Skills and model providers

Skill symlink skipped as path escape

Use when logs include:

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

Every skill root is a containment boundary. A symlink under ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills, or ~/.openclaw/skills is skipped when its real target resolves outside that root, unless the target is explicitly trusted.

Inspect the link:

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

If the target is intentional, configure both the direct skill root and the allowed symlink target:

{  skills: {    load: {      extraDirs: ["~/path/to/skills"],      allowSymlinkTargets: ["~/path/to/skills"],    },  },}

Then start a new session or wait for the skills watcher to refresh. Restart the gateway if the running process predates the config change.

Do not use broad targets such as ~, /, or a whole synced project folder. Keep allowSymlinkTargets scoped to the real skill root that contains trusted SKILL.md directories.

Skill Workshop does not use these trusted discovery targets. It writes only inside the active agent's <state-dir>/agents/<agentId>/agent/workshop-skills.

Related:

• Skills config
• Configuration examples

Anthropic 429 extra usage required for long context

Use when logs/errors include: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

Look for:

• Selected Anthropic model is a GA-capable 1M Claude 4.x model (Opus 4.6/4.7/4.8, Sonnet 4.6), or the model config still carries legacy params.context1m: true.
• Current Anthropic credential is not eligible for long-context usage.
• Requests fail only on long sessions/model runs that need the 1M context path.

Fix options:

Related:

• Anthropic
• Token use and costs
• Why am I seeing HTTP 429 from Anthropic?

Upstream 403 blocked responses

Use when an upstream LLM provider returns a generic 403 such as Your request was blocked.

Do not assume this is always an OpenClaw configuration issue. The response can come from an upstream security layer such as a CDN, WAF, bot-management rule, or reverse proxy in front of an OpenAI-compatible endpoint.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Look for:

• Multiple models under the same provider failing the same way.
• HTML or generic security text instead of a normal provider API error.
• Provider-side security events for the same request time.
• A tiny direct curl probe succeeding while normal SDK-shaped requests fail.

Fix the provider-side filtering first when evidence points to a WAF/CDN block. Prefer a narrowly scoped allow or skip rule for the API path OpenClaw uses, and avoid disabling protection for the whole site.

Related:

• OpenAI-compatible endpoints
• Provider configuration
• Logs

Local OpenAI-compatible backend passes direct probes but agent runs fail

Use when:

• curl ... /v1/models works.
• Tiny direct /v1/chat/completions calls work.
• OpenClaw model runs fail only on normal agent turns.

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

Look for:

• Direct tiny calls succeed, but OpenClaw runs fail only on larger prompts.
• model_not_found or 404 errors even though direct /v1/chat/completions works with the same bare model id.
• Backend errors about messages[].content expecting a string.
• Intermittent incomplete turn detected ... stopReason=stop payloads=0 warnings with an OpenAI-compatible local backend.
• Backend crashes that appear only with larger prompt-token counts or full agent runtime prompts.

Related:

• Configuration
• Local models
• OpenAI-compatible endpoints