Skill: jiangwill2023/kimi2-5skill (version 1.0.0)

--- name: kimi2.5skill description: Troubleshoot and operate Kimi 2.5 / OpenClaw image understanding. Use when image recognition fails, OCR/images cannot be analyzed, `image` tool reports `Unknown model`, configured vision models are ignored at runtime, or you need a safe recovery workflow for OpenClaw image-capable models. --- # kimi2.5skill 处理 OpenClaw 中 Kimi 2.5 / 识图模型的排障、恢复、验证与运维收口。 ## 快速流程 1. 先做 runtime 实测，不要只看配置文件 2. 再检查： - `~/.openclaw/openclaw.json` - `~/.openclaw/agents/<agent>/agent/models.json` 3. 如果出现 `Unknown model`，优先怀疑 agent 级 `models.json` 的非法 provider 配置导致整份自定义模型注册表加载失败 4. 修复后必须重启 gateway，并跑一张真实图片回归测试 ## 参考文件 - 修复流程：`references/recovery-playbook.md` - 本次事件：`references/incident-2026-04-14.md` ## 本轮已验证结论（2026-04-14） 本轮问题的真实根因是： > agent 级 `models.json` 中的自定义 `codex` provider 配置不合法，导致模型注册表加载异常，继而让 `image` runtime 报 `Unknown model`。 已验证修复点： - `/Users/admin-ai/.openclaw/agents/qiang/agent/models.json` - `/Users/admin-ai/.openclaw/agents/sally-bot/agent/models.json` 移除有问题的 `codex` provider 后，`image` 工具已成功返回图片描述，说明识图 runtime 恢复。 ## 成功标准 以下同时满足才算修好： - 不再出现 `Unknown model` - `image` 工具返回正常图片描述 / OCR 结果 - gateway 状态正常 - 至少完成一张真实图片回归测试 ## 收口口径 恢复后统一表述： - 识图已恢复可用 - 根因是 agent 级 `models.json` 非法 provider 配置污染了 image runtime 注册表 - 后续若再遇 `Unknown model`，优先检查 `~/.openclaw/agents/<agent>/agent/models.json`

path: references/incident-2026-04-14.md
content: # Incident 2026-04-14

## Summary
OpenClaw image understanding failed even though image-capable models were present in config.

## Root cause
Agent-level `models.json` included an invalid custom provider block (`codex`) that broke custom model registry loading for image runtime.

## Observed effect
- `image` tool returned `Unknown model`
- static config appeared valid
- runtime behavior contradicted config expectations

## Fix applied
Removed invalid `codex` provider from affected agent-level `models.json` files:
- `/Users/admin-ai/.openclaw/agents/qiang/agent/models.json`
- `/Users/admin-ai/.openclaw/agents/sally-bot/agent/models.json`

## Validation
After repair:
- gateway was healthy
- `image` tool returned a normal image description
- notifications were sent to relevant agents

## Durable lesson
Config presence is not runtime proof. Trust runtime verification over static JSON presence.


path: references/recovery-playbook.md
content: # Recovery Playbook

## Scope
Use this playbook when OpenClaw image understanding fails with symptoms like:
- `Unknown model`
- configured vision model exists in JSON but runtime does not recognize it
- image/OCR suddenly stops working across one or more agents

## Confirm the symptom first
Do runtime verification first:
1. Run `openclaw status`
2. Run an actual `image` tool call against a real local or inbound image
3. Treat runtime output as ground truth

Do not call it fixed if you only checked config files.

## Files to inspect
- `~/.openclaw/openclaw.json`
- `~/.openclaw/agents/<agent>/agent/models.json`

## Highest-probability root cause
A single invalid provider block inside agent-level `models.json` can cause the custom model registry to fail loading.

In the 2026-04-14 incident, the invalid block was a custom `codex` provider definition. Removing it restored image runtime registration.

## Minimal repair sequence
1. Back up the affected `models.json`
2. Remove only the invalid provider block
3. Restart gateway
4. Run a real image regression test
5. Notify affected agents

## Success criteria
All of these must be true:
- no `Unknown model`
- image tool returns a valid description or OCR result
- gateway healthy
- at least one real image regression passed

## Non-success criteria
These do not count as fixed:
- model exists in config
- service is running
- no real image tested


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)