跳转至

技能与模型提供商

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

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 长上下文请求被拒绝时,运行仍能继续进行。

相关:

上游 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 路径设置范围收敛的允许或跳过规则,避免为整个站点禁用保护。

Warning

一次成功的最小化 curl 并不能保证真实的 SDK 风格请求能够通过相同的上游安全层。

相关:

本地 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 数量或完整智能体运行时提示词时出现的后端崩溃。
常见特征
  • 本地 MLX/vLLM 风格服务器出现 model_not_found:验证 baseUrl 是否包含 /v1,对于 /v1/chat/completions 后端,api 是否为 "openai-completions",以及 models.providers.<provider>.models[].id 是否为裸提供商本地 ID。使用提供商前缀选择一次,例如 mlx/mlx-community/Qwen3-30B-A3B-6bit;目录条目保持为 mlx-community/Qwen3-30B-A3B-6bit。
  • messages[...].content: invalid type: sequence, expected a string:后端拒绝结构化的 Chat Completions 内容部分。修复方法:设置 models.providers.<provider>.models[].compat.requiresStringContent: true。
  • validation.keys 或类似 ["role","content"] 的允许消息键:后端拒绝 Chat Completions 消息上的 OpenAI 风格重放元数据。修复方法:设置 models.providers.<provider>.models[].compat.strictMessageKeys: true。
  • incomplete turn detected ... stopReason=stop payloads=0:后端完成了 Chat Completions 请求,但该轮次未返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次;持续失败通常意味着后端正在输出空/非文本内容,或抑制了最终答案文本。
  • 小型直接请求成功,但 OpenClaw 智能体运行因后端/模型崩溃而失败(例如某些 llama-server 构建在 llmman 后运行 Gemma 时):OpenClaw 传输层很可能本身没有问题;是后端在较大的智能体运行时提示词形态上失败。
  • 禁用工具后失败减少但未消失:工具模式是造成压力的部分原因,但剩余问题仍然是上游模型/服务器容量或后端缺陷。
修复选项
  1. 对于仅支持字符串的 Chat Completions 后端,设置 compat.requiresStringContent: true。
  2. 对于严格的 Chat Completions 后端,如果每条消息仅接受 role 和 content,设置 compat.strictMessageKeys: true。
  3. 对于无法可靠处理 OpenClaw 工具架构接口的模型/后端,设置 compat.supportsTools: false。
  4. 尽可能降低提示词压力:使用更小的工作区初始化、更短的会话历史、更轻量的本地模型,或使用长上下文支持更强的后端。
  5. 如果极小的直接请求持续通过,而 OpenClaw 代理轮次仍在后端内部崩溃,请将其视为上游服务器/模型限制,并在该处提交可复现问题,附上已接受的载荷结构。

相关:

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw