[Bug] imageModel调用火山引擎API返回404错误

[279759781]

问题描述

OpenClaw配置imageModel.primary为volcengine-plan/doubao-seed-2.0-pro后，当用户发送图片时，OpenClaw内部的image工具调用火山引擎API返回404错误。

环境信息

• OpenClaw版本：2026.4.14
• 配置的imageModel：volcengine-plan/doubao-seed-2.0-pro
• 火山引擎API：https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions

问题现象

1. OpenClaw内部调用失败

当用户发送图片时，OpenClaw的image工具返回错误：

<active_memory_plugin>
LLM request failed: provider rejected the request schema or tool payload.
</active_memory_plugin>

或404错误。

2. 直接调用API成功

使用Python直接调用同一个API，完全正常：

import base64, requests

with open('image.jpg', 'rb') as f:
    img = base64.b64encode(f.read()).decode()

response = requests.post(
    'https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions',
    headers={
        'Authorization': 'Bearer <API_KEY>',
        'Content-Type': 'application/json'
    },
    json={
        'model': 'doubao-seed-2.0-pro',
        'messages': [{
            'role': 'user',
            'content': [
                {'type': 'text', 'text': '描述这张图片的内容'},
                {'type': 'image_url', 'image_url': {'url': f'data:image/jpeg;base64,{img}'}}
            ]
        }],
        'max_tokens': 1000
    },
    timeout=60
)
# 状态码: 200 ✅
# 正常返回图片描述内容

3. 文本模型正常

OpenClaw内部调用火山引擎的文本模型（不带图片）完全正常，只有imageModel（多模态）失败。

可能原因

1. OpenClaw内部image工具的请求格式不正确

   • 可能使用了错误的endpoint
   • 可能请求body格式不符合火山引擎API要求

2. 模型ID映射问题

   • OpenClaw可能使用了内部映射的模型ID，而非配置文件中指定的ID

3. 多模态请求处理逻辑有bug

   • 图片base64编码方式不对
   • content数组格式不对

临时解决方案

创建了自定义image-recognition技能，绕过OpenClaw的imageModel工具，直接调用火山引擎API。

期望修复

1. 修复OpenClaw内部image工具对火山引擎API的调用逻辑
2. 或者提供更清晰的错误信息（当前只显示404，没有具体原因）
3. 在文档中说明各provider的imageModel兼容性

配置文件

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "baiduqianfancodingplan/glm-5"
      },
      "imageModel": {
        "primary": "volcengine-plan/doubao-seed-2.0-pro"
      }
    }
  }
}

补充信息

• 用户环境：飞书平台
• 发现时间：2026-04-17
• OpenClaw运行环境：Linux 服务器

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve.

Summary
Keep open. Current main still does not support the reported Volcengine Plan imageModel path: the exact volcengine-plan/doubao-seed-2.0-pro model is absent, all built-in volcengine-plan catalog rows are text-only, and the related pull request remains open and incomplete for this exact model/endpoint.

Reproducibility: no. high-confidence live reproduction for the provider-side 404 is available without Volcengine credentials. Source inspection does show current main still treats the reported volcengine-plan imageModel path as unsupported because the exact model is absent and the coding catalog is text-only.

Next step
Manual provider-owner review is needed because the fix depends on live Volcengine verification and a product decision about advertising or documenting this coding image path.

Review details

Best possible solution:

Keep this open until maintainers live-verify the exact Ark coding image endpoint and model ID, then either add Volcengine-owned image-capable catalog/runtime/docs coverage with regression tests or document this path as unsupported with a supported alternative.

Do we have a high-confidence way to reproduce the issue?

No high-confidence live reproduction for the provider-side 404 is available without Volcengine credentials. Source inspection does show current main still treats the reported volcengine-plan imageModel path as unsupported because the exact model is absent and the coding catalog is text-only.

Is this the best way to solve the issue?

Unclear. A metadata-only change is not enough until maintainers verify the upstream model/endpoint; the safer solution is provider-owned support with live proof, or explicit docs saying this Volcengine Plan image path is unsupported.

Acceptance criteria:

• Live Volcengine Ark check for volcengine-plan/doubao-seed-2.0-pro with image input through OpenClaw imageModel routing, with credentials and private data redacted.
• If implementation proceeds: node scripts/run-vitest.mjs extensions/volcengine/index.test.ts src/media-understanding/image.test.ts src/media-understanding/provider-registry.test.ts src/agents/tools/image-tool.test.ts.
• If docs change: run pnpm docs:list, read the relevant provider docs, and run the docs validation path selected by maintainers.

What I checked:

• Live issue state: The issue is still open, has no protected labels, and has no closed-by pull request references; the two existing ClawSweeper comments also kept it open for the same unsupported Volcengine Plan image path.
• Related pull request is not a complete merged fix: The related pull request at Providers: restore image input on shared Volc coding models #55688 is still open, touches stale/partial catalog surfaces, and does not add or prove volcengine-plan/doubao-seed-2.0-pro. (089e64e88ea5)
• Volcengine Plan catalog remains text-only: Current main declares the reported coding endpoint for volcengine-plan, but every built-in volcengine-plan row has input: ["text"]; no row advertises image input. (extensions/volcengine/openclaw.plugin.json:94, 41810a462e3c)
• Exact reported model is absent: Repository search found no catalog, docs, or runtime entry for volcengine-plan/doubao-seed-2.0-pro; only unrelated pricing/usage tests mention the normalized doubao-seed-2-0-pro under other contexts. (41810a462e3c)
• Docs also describe coding models as text-only: The public-source Volcengine provider docs list volcengine-plan as the coding endpoint and show every coding row with Input as text, while general volcengine/* rows are listed as text/image. Public docs: docs/providers/volcengine.md. (docs/providers/volcengine.md:89, 41810a462e3c)
• Explicit imageModel routing still selects configured refs: agents.defaults.imageModel primary/fallback refs are converted into media-understanding provider/model entries before auto image selection, so the reported config still routes toward the configured Volcengine Plan ref. (src/media-understanding/runner.ts:595, 41810a462e3c)

Likely related people:

• shakkernerd: Authored the active Volcengine manifest-backed catalog and bundled static provider-catalog work that owns the volcengine-plan model metadata surface. (role: provider catalog contributor; confidence: high; commits: 1cfa22acb198, 3254e961e943; files: extensions/volcengine/openclaw.plugin.json, extensions/volcengine/models.ts, extensions/volcengine/provider-catalog.ts)
• steipete: Current blame and commit metadata show recent model catalog registration and manifest/catalog maintenance touching the same Volcengine model-resolution path. (role: recent area contributor; confidence: medium; commits: 93b9223bee0a, 311e4608d173; files: extensions/volcengine/openclaw.plugin.json, src/plugin-sdk/provider-catalog-shared.ts, src/media-understanding/image.ts)
• 1yihui: Authored recent media-understanding diagnostics around failures when configured image models lack image-capable metadata. (role: adjacent image-runtime contributor; confidence: medium; commits: 4eb30fc13a5b; files: src/media-understanding/image.ts, src/media-understanding/image.test.ts)
• zhang-guiping: Authored configured image-model resolution work that is adjacent to this path but does not add support for absent or text-only Volcengine Plan catalog rows. (role: configured image-model resolver contributor; confidence: medium; commits: 91adb69c57b1; files: src/media-understanding/image.ts, src/media-understanding/image.test.ts)
• fanziqing: Introduced the original Volcengine and BytePlus provider integration before later manifest refactors moved the active catalog surface. (role: original provider introducer; confidence: medium; commits: 559736a5a0d3; files: src/agents/doubao-models.ts, src/agents/byteplus-models.ts, src/commands/auth-choice.apply.volcengine.ts)

Remaining risk / open question:

• Live Volcengine credentials were not available, so the exact upstream support, entitlement behavior, model ID spelling, and 404 response path were not verified.
• The open related pull request at Providers: restore image input on shared Volc coding models #55688 may address nearby shared coding rows, but it does not prove this exact reported model/endpoint and is not merged.
• The right outcome may be either supported catalog/runtime coverage or explicit unsupported-status documentation, so provider-owner judgment is needed before changing capability metadata.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 41810a462e3c.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve.

Current main still does not solve the reported Volcengine Plan imageModel path: the explicit imageModel route remains active, but the bundled volcengine-plan catalog is text-only, the reported model is absent from the catalog, and there is no Volcengine-owned media-understanding adapter or regression coverage for this Ark coding image endpoint. The related #55688 remains an open partial catalog-capability candidate, not a merged fix for this exact model/endpoint.

Required change / next step:

Manual review is the right next step because the fix depends on live Volcengine model/endpoint verification and a maintainer decision between supporting this coding image path or documenting it unsupported; #55688 is useful context but not a complete merged fix.

Review details

Best possible solution:

Keep the issue open until maintainers verify the exact Volcengine Ark coding image endpoint and model ID. Then either add Volcengine-owned image-capable catalog/media-understanding support with regression coverage, or explicitly document volcengine-plan imageModel as unsupported and guide users to a supported image-capable volcengine/* model or custom provider config with input: ["text", "image"].

Acceptance criteria:

• Live Volcengine Ark check for volcengine-plan/doubao-seed-2.0-pro with an image through OpenClaw imageModel routing, using redacted credentials.
• Targeted tests if implementation proceeds: pnpm test extensions/volcengine/index.test.ts src/media-understanding/image.test.ts src/media-understanding/provider-registry.test.ts src/agents/tools/image-tool.test.ts.
• Docs check if support status changes: pnpm docs:list plus the relevant docs validation path maintainers choose for provider docs.

What I checked:

• Issue context: The report is from a non-maintainer on OpenClaw 2026.4.14, with Feishu/Linux image input failing through OpenClaw while a direct Python request to the same Ark coding endpoint succeeds; the only prior comment is a ClawSweeper keep-open review that also calls Providers: restore image input on shared Volc coding models #55688 partial.
• Volcengine Plan remains text-only: The current bundled volcengine-plan manifest uses the reported coding base URL but every built-in coding model row declares input: ["text"]; doubao-seed-2.0-pro is not present in the bundled Volcengine catalog. (extensions/volcengine/openclaw.plugin.json:94, acae48b790fa)
• Docs still describe coding models as text-only: The public-source Volcengine provider docs list all volcengine-plan coding entries with Input as text, while only the general volcengine rows are shown with image input. Public docs: docs/providers/volcengine.md. (docs/providers/volcengine.md:89, acae48b790fa)
• Explicit imageModel is still selected: agents.defaults.imageModel primary/fallback refs are converted into provider/model media-understanding entries before auto image-model selection, so the reported configuration still drives OpenClaw toward volcengine-plan/doubao-seed-2.0-pro. (src/media-understanding/runner.ts:595, acae48b790fa)
• Runtime still requires image-capable model metadata: The generic image runtime fails if the resolved model is unknown or lacks image in its input metadata, which means the current built-in text-only Volcengine Plan rows cannot be treated as supported imageModel entries. (src/media-understanding/image.ts:184, acae48b790fa)
• No Volcengine media-understanding provider is registered: The Volcengine manifest declares speech capability only; the registry can synthesize generic image providers only from configured providers that explicitly declare an image-capable model, which the bundled volcengine-plan catalog does not do. (extensions/volcengine/openclaw.plugin.json:204, acae48b790fa)

Likely related people:

• steipete: Available git history/blame shows the current Volcengine manifest/catalog and the relevant media-understanding routing were last created or maintained in recent mainline commits by Peter Steinberger. (role: recent maintainer; confidence: medium; commits: a972c9ec4547, be8c24633aaa; files: extensions/volcengine/openclaw.plugin.json, extensions/volcengine/models.ts, extensions/volcengine/provider-catalog.ts)

Remaining risk / open question:

• The exact upstream support and entitlement behavior for volcengine-plan/doubao-seed-2.0-pro on the Ark coding image endpoint still needs live maintainer verification before marking a bundled catalog entry image-capable.
• Merging metadata-only image capability from Providers: restore image input on shared Volc coding models #55688 could still leave this report unresolved if the reported model ID, endpoint, or payload shape needs separate Volcengine-specific handling.

Codex review notes: model gpt-5.5, reasoning high; reviewed against acae48b790fa.