OpenClaw 模型配置问题调试实战 - DeepSeek 404 错误解决

问题背景

今天在测试 OpenClaw 的飞书集成时，遇到了一个棘手的问题：在飞书（机器人：clawAdmin）中发送消息时，总是返回错误：

⚠️ Something went wrong while processing your request. Please try again, or use /new to start a fresh session.

这篇文章记录了完整的调试过程和解决方案。

---

问题诊断

第一步：查看日志

首先通过 OpenClaw 日志定位问题：

tail -f /tmp/openclaw-1001/openclaw-2026-05-04.log

发现关键错误信息：

{
  "event": "embedded_run_agent_end",
  "isError": true,
  "error": "404 status code (no body)",
  "failoverReason": "model_not_found",
  "model": "deepseek-v4-flash",
  "provider": "deepseek"
}

问题初步判断 ：DeepSeek 模型调用返回 404，原因是 model_not_found。

---

第二步：验证 API 本身是否可用

首先排除 API Key 或网络问题：

curl -X POST "https://api.deepseek.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 100
  }'

✅ 结果：API 本身工作正常，能够正常返回响应。

---

第三步：分析 OpenClaw 的 API 调用方式

问题 narrowed down 到 OpenClaw 如何调用 API。测试两个不同的端点：

测试 1：Chat Completions 端点 (/v1/chat/completions)

curl -X POST "https://api.deepseek.com/v1/chat/completions" ...

✅ 正常工作 - DeepSeek 标准支持的端点

测试 2：Responses 端点 (/v1/responses)

curl -X POST "https://api.deepseek.com/v1/responses" ...

❌ 不工作 - DeepSeek 不支持 OpenAI Responses API 格式

---

第四步：检查 OpenClaw 配置

查看 openclaw.json 中的 DeepSeek 配置：

{
  "deepseek": {
    "baseUrl": "https://api.deepseek.com",
    "apiKey": "sk-xxxxxx",
    "api": "openai-responses",  // ❌ 问题在这里！
    "models": [{
      "id": "deepseek-v4-flash",
      "name": "deepseek-v4-flash"
    }]
  }
}

关键发现：

• "openai-responses" 类型调用的是 /v1/responses 端点
• DeepSeek 不支持 这个端点，只支持 /v1/chat/completions
• 因此需要将 API 类型改为 "openai-completions"

---

解决方案

步骤 1：修改配置文件

import json

config_path = "/home/openclaw-admin/.openclaw/openclaw.json"
with open(config_path, 'r') as f:
    data = json.load(f)

# 修改 DeepSeek 配置
if "deepseek" in data.get("models", {}).get("providers", {}):
    # 1. 将 API 类型从 openai-responses 改为 openai-completions
    data["models"]["providers"]["deepseek"]["api"] = "openai-completions"
    
    # 2. 确保 baseUrl 包含 /v1 后缀
    base_url = data["models"]["providers"]["deepseek"]["baseUrl"]
    if not base_url.endswith("/v1"):
        data["models"]["providers"]["deepseek"]["baseUrl"] = base_url.rstrip("/") + "/v1"

with open(config_path, 'w') as f:
    json.dump(data, f, indent=2)

修改后的配置：

{
  "deepseek": {
    "baseUrl": "https://api.deepseek.com/v1",  // ✅ 添加 /v1
    "apiKey": "sk-xxxxxx",
    "api": "openai-completions",  // ✅ 改为正确的类型
    "models": [{
      "id": "deepseek-v4-flash",
      "name": "deepseek-v4-flash"
    }]
  }
}

步骤 2：重启 Gateway

# 杀死旧进程
sudo pkill -f "node.*gateway.*39217"

# 启动新的 gateway
sudo -u openclaw-admin bash -c '
  cd ~
  nohup /home/linuxbrew/.linuxbrew/opt/node@24/bin/node \
    /home/openclaw-admin/.npm-global/lib/node_modules/openclaw/dist/index.js \
    gateway --port 39217 > /tmp/openclaw-admin-gateway.log 2>&1 &
  echo "Gateway started, PID: $!"
'

步骤 3：验证

在飞书中发送测试消息，确认能够正常收到回复。

---

技术要点总结

1. OpenClaw 支持的 API 类型

OpenClaw 目前支持以下主要 API 类型：

API 类型	调用端点	适用场景
openai-completions	/v1/chat/completions	大多数兼容 OpenAI 格式的 provider (DeepSeek, 火山引擎等)
openai-responses	/v1/responses	OpenAI 官方的 Responses API
anthropic-messages	/v1/messages	Anthropic Claude

重要：不是所有 provider 都支持所有 API 类型！

2. DeepSeek 的特殊性

• ✅ 支持：/v1/chat/completions (标准 Chat Completions)
• ❌ 不支持：/v1/responses (OpenAI Responses API)
• ❌ 不支持：/v1/completions (旧的文本补全)

3. 配置验证清单

配置新的 model provider 时，需要确认：

1. ✅ api 类型是否匹配 provider 实际支持的端点
2. ✅ baseUrl 是否正确（是否需要 /v1 后缀）
3. ✅ apiKey 是否有效
4. ✅ model.id 是否是 provider 支持的真实模型 ID
5. ✅ 网络连通性（防火墙、代理等）

---

踩坑记录

坑 1：想当然认为 "openai-chat" 存在

一开始我尝试把配置改成 "api": "openai-chat"，结果遇到错误：

Invalid option: expected one of "openai-completions"|"openai-responses"|...

教训：先查看 OpenClaw 实际支持哪些值，不要想当然。

坑 2：配置修改后没有立即生效

OpenClaw gateway 有配置缓存，修改配置后必须重启进程才能生效。

坑 3：baseUrl 的 /v1 后缀

不同 provider 的 baseUrl 格式不同：

• DeepSeek：https://api.deepseek.com/v1（需要 /v1）
• OpenAI：https://api.openai.com/v1（需要 /v1）
• 有些 provider 可能不需要 /v1 后缀

---

调试工具推荐

1. 实时日志监控

tail -f /tmp/openclaw-1001/openclaw-2026-05-04.log | grep -A 5 -B 5 "error|Error|404"

2. 直接测试 API 端点

# 测试 Chat Completions
curl -X POST "https://api.deepseek.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"model": "deepseek-v4-flash", "messages": [{"role": "user", "content": "hi"}]}'

# 列出支持的模型
curl -X GET "https://api.deepseek.com/v1/models" \
  -H "Authorization: Bearer $API_KEY"

3. 检查进程状态

ps aux | grep openclaw-admin | grep node
netstat -tlnp | grep 39217

---

最终成功配置

这是最终工作的 DeepSeek 配置：

{
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "sk-xxxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-v4-flash",
            "name": "deepseek-v4-flash",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0
            },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

---

结语

LLM 集成虽然看起来简单（都是 OpenAI 兼容格式），但实际每个 provider 的实现细节都有差异。遇到 404 错误时，不要只怀疑模型 ID，还要检查：

1. 端点路径是否正确
2. API 类型是否匹配
3. baseUrl 是否包含正确的前缀

希望这篇文章能帮助遇到类似问题的同学！

---

日期 ：2026-05-04
标签 ：#OpenClaw #DeepSeek #LLM #调试 #API