技能与模型提供商
技能符号链接因路径逃逸被跳过¶
当日志包含以下内容时使用:
每个技能根目录都是一个包含边界。当 ~/.agents/skills、<workspace>/.agents/skills、<workspace>/skills 或 ~/.openclaw/skills 下的符号链接的真实目标解析到该根目录之外时,该符号链接会被跳过,除非该目标被显式信任。
检查该链接:
如果该目标是有意为之,请同时配置直接技能根目录和允许的符号链接目标:
{
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 时使用。
排查要点:
- 所选 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 兼容端点之前的反向代理。
排查要点:
- 同一提供商下的多个模型以相同方式失败。
- 返回 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 传输层很可能本身没有问题;是后端在较大的智能体运行时提示词形态上失败。 - 禁用工具后失败减少但未消失:工具模式是造成压力的部分原因,但剩余问题仍然是上游模型/服务器容量或后端缺陷。
修复选项
- 对于仅支持字符串的 Chat Completions 后端,设置
compat.requiresStringContent: true。 - 对于严格的 Chat Completions 后端,如果每条消息仅接受
role和content,设置compat.strictMessageKeys: true。 - 对于无法可靠处理 OpenClaw 工具架构接口的模型/后端,设置
compat.supportsTools: false。 - 尽可能降低提示词压力:使用更小的工作区初始化、更短的会话历史、更轻量的本地模型,或使用长上下文支持更强的后端。
- 如果极小的直接请求持续通过,而 OpenClaw 代理轮次仍在后端内部崩溃,请将其视为上游服务器/模型限制,并在该处提交可复现问题,附上已接受的载荷结构。
相关:
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw