技能和模型提供商

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

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

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"],
    },
  },
}

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

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

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

相关：

• 技能配置
• 配置示例

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

当日志/错误包含 HTTP 429: rate_limit_error: Extra usage is required for long context requests 时使用。

openclaw logs --follow
openclaw models status
openclaw 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 凭据不符合长上下文使用条件。
• 仅在需要 1M 上下文路径的长会话/模型运行时请求失败。

修复选项：

1. 使用标准上下文窗口

切换到标准窗口模型，或从较旧的不具备 1M 上下文 GA 能力的模型配置中移除旧的 context1m。

2. 使用符合条件的凭据

使用符合长上下文请求条件的 Anthropic 凭据，或切换到 Anthropic API 密钥。

3. 配置回退模型

配置回退模型，以便在 Anthropic 长上下文请求被拒绝时继续运行。

相关：

• Anthropic
• Token 使用与成本
• 为什么我会看到来自 Anthropic 的 HTTP 429？

上游 403 被拦截的响应¶

当上游 LLM 提供商返回诸如 Your request was blocked 之类的通用 403 时使用。

不要假设这始终是 OpenClaw 配置问题。该响应可能来自上游安全层，例如 CDN、WAF、机器人管理规则或位于 OpenAI 兼容端点之前的反向代理。

openclaw status
openclaw gateway status
openclaw logs --follow

查找以下情况：

• 同一提供商下的多个模型以相同方式失败。
• 返回 HTML 或通用安全文本，而不是正常的提供商 API 错误。
• 同一请求时间出现提供商侧安全事件。
• 小型直接 curl 探测成功，而正常的 SDK 形态请求失败。

当证据指向 WAF/CDN 拦截时，首先修复提供商侧的过滤。优先为 OpenClaw 使用的 API 路径设置范围严格限定的允许或跳过规则，并避免为整个站点禁用防护。

相关：

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

本地 OpenAI 兼容后端能通过直接探测，但代理运行失败¶

在以下情况使用：

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

curl http://127.0.0.1:1234/v1/models
curl 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" --json
openclaw logs --follow

查找以下情况：

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

相关：

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