技能和模型提供者

技能符号链接因路径逃逸而被跳过

当日志包含以下内容时使用：

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

每个技能根目录都是一个包含边界。当 ~/.agents/skills、<workspace>/.agents/skills、<workspace>/skills 或 ~/.openclaw/skills 下的符号链接，其真实目标解析到该根目录之外时，会被跳过，除非该目标已被显式信任。

检查该链接：

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

如果该目标是有意如此，请同时配置直接技能根目录和允许的符号链接目标：

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

然后启动新的会话，或等待 skills 监视器刷新。如果运行中的进程早于配置更改，则重启网关。

不要使用过于宽泛的目标，例如 ~、/，或整个同步项目文件夹。请将 allowSymlinkTargets 的范围限制在包含受信任 SKILL.md 目录的真实技能根目录。

Skill Workshop 不使用这些可信的发现目标。它仅写入活动代理的 <state-dir>/agents/<agentId>/agent/workshop-skills 内。

相关：

• 技能配置
• 配置示例。

Anthropic 429 长上下文需要额外用量

当 logs/errors 包含：HTTP 429: rate_limit_error: Extra usage is required for long context requests 时使用。

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

查看以下内容：

• 选定的 Anthropic 模型具有本机 1M 上下文窗口（Opus 5、Sonnet 5、Mythos 5、Fable 5.1、Fable 5、Opus 4.6/4.7/4.8、Sonnet 4.6），或者模型配置仍然带有旧版 params.context1m: true。
• 当前 Anthropic 凭据不符合长上下文使用资格。
• Requests 仅在需要 1M 上下文路径的长 sessions/model 运行时失败。

修复选项：

相关：

• 人类
• 代币使用和费用
• 为什么我从 Anthropic 看到 HTTP 429？

上游 403 阻止响应

当上游 LLM 提供方返回通用 403（例如 Your request was blocked）时使用。

不要认为这始终是 OpenClaw 配置问题。响应可以来自上游安全层，例如 CDN、WAF、机器人管理规则或 OpenAI- 兼容端点前面的反向代理。

openclaw statusopenclaw gateway statusopenclaw logs --follow

查看以下内容：

• 同一提供方下的多个模型都以相同方式失败。
• 返回的是 HTML 或通用安全文案，而不是正常的提供方 API 错误。
• 同一请求时间点在提供方侧有安全事件记录。
• A 微小的直接 curl 检查成功，而正常的 SDK- 形请求失败。

当证据指向 WAF/CDN 区块时，首先修复提供者端过滤。对于 OpenClaw 使用的 API 路径，首选范围狭窄的允许或跳过规则，并避免禁用整个站点的保护。

相关：

• OpenAI 兼容端点
• 提供方配置
• 日志

Local OpenAI-兼容后端通过直接检查但代理运行失败

适用场景：

• curl ... /v1/models 可正常工作。
• 直接发起很小的 /v1/chat/completions 调用可正常工作。
• OpenClaw 模型运行仅在正常代理轮次中失败。

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

查看以下内容：

• 直接的小型调用成功，但 OpenClaw 运行仅在更大的提示词下失败。
• 即使直接 /v1/chat/completions 使用相同的裸模型 ID，也会出现 model_not_found 或 404 错误。
• 后端报错 messages[].content 期望字符串。
• 与 OpenAI- 兼容的本地后端出现间歇性 incomplete turn detected ... stopReason=stop payloads=0 警告。
• 仅在更大的提示 token 数或完整代理运行提示词下才出现的后端崩溃。

相关：

• 配置
• 本地模型
• OpenAI 兼容端点