CowAgent 接入第三方网关使用 DeepSeek V4 返回空响应问题的排查与解决

一、CowAgent 简介

CowAgent是一个开源的超级 AI 助理框架，GitHub 45,000+ Stars，是国内 AI Agent 生态中 Star 数最高的项目之一，支持多模型（DeepSeek/OpenAI/Claude 等）、多渠道（微信/飞书/网页等）接入。

二、问题现象

在 CowAgent v2.x 的 Web 控制台配置好 DeepSeek V4 Pro 模型后，发送消息始终无法得到正常回复。查看容器日志，反复出现以下警告：

[WARNING] LLM returned empty response (stop_reason: None), retrying once...
[WARNING] LLM returned empty response after retry (no content and no tool calls)
[INFO] Generated fallback response for empty LLM output

前端表现为通用的兜底回复："抱歉，我暂时无法生成回复……"

三、排查过程

3.1 排除 API 本身的问题

直接在容器内用 requests 调 API：

import requests

r = requests.post(
    "http://<API网关>/v1/chat/completions",
    headers={
   "Authorization": "Bearer sk-****"},
    json={
   "model": "deepseek-v4-pro", "messages": [{
   "role": "user", "content": "hi"}]},
    timeout=10
)
print(r.json()["choices"][0]["message"]["content"])
# 输出：Hi there! How can I help you today?

API 完全正常，模型能正常返回内容。

3.2 排除认证方式的问题

CowAgent 对自定义 provider 发送请求时，我怀疑认证头格式不对。分别测试了两种方式：

# 方式一：Bearer Token（推荐）
headers = {
   "Authorization": "Bearer sk-****"}
# 返回 200 ✅

# 方式二：api-key Header
headers = {
   "api-key": "sk-****"}
# 返回 401 ❌ Invalid token

确认 API 接受 Bearer Token 认证，且 CowAgent 的代码也是用 Bearer Token 发请求的。认证没问题。

3.3 排除模型本身的问题

换成 gpt-5.4 等其他非推理模型，同样返回空响应。确认不是 DeepSeek V4 Pro 特有的问题。

3.4 排除 SSE 解析的问题

CowAgent 处理流式响应时使用自定义的 _iter_sse_events 方法解析 SSE（Server-Sent Events）。我怀疑它的解析逻辑有 bug。

在容器内分别测试：

from models.openai.openai_http_client import OpenAIHTTPClient

# 测试 1：直接调用 _iter_sse_events 解析原始响应
r = requests.post(..., stream=True)
events = list(OpenAIHTTPClient._iter_sse_events(r))
print(len(events))  # 输出：33 ✅ 能正确解析

# 测试 2：通过 chat_completions 走完整链路
client = OpenAIHTTPClient(api_key="sk-****", api_base="http://<API网关>")
chunks = list(client.chat_completions(model="gpt-5.4", ...))
print(len(chunks))  # 输出：0 ❌ 一个 chunk 都没收到！

关键发现：同样的 API 响应，直接解析有 33 个事件，但走 chat_completions 完整链路却是 0。

3.5 定位根因

对比两种调用方式，发现唯一的区别在于请求的 URL：

根因：api_base 缺少 /v1 路径前缀！

CowAgent 的 URL 拼接逻辑是：

# openai_http_client.py
url = f"{api_base}{path}"  # path = "/chat/completions"

如果你的 api_base 配置为 http://<API网关>（不带 /v1），最终请求的 URL 就是 http://<API网关>/chat/completions，而正确的 API 路径是 http://<API网关>/v1/chat/completions。

大部分 OpenAI 兼容 API（如 DeepSeek 官方 https://api.deepseek.com/v1、OpenAI 官方 https://api.openai.com/v1）本身就把 /v1 包含在 api_base 里了，所以填它们的时候不会有这个问题。但接入内网 API 网关或自定义地址时，很容易漏掉这个路径前缀。

四、解决方案

将 api_base 从 http://<API网关> 改为 http://<API网关>/v1：

config.json

{
   
    "model": "deepseek-v4-pro",
    "bot_type": "deepseek",
    "deepseek_api_base": "http://<API网关>/v1",
    "deepseek_api_key": "sk-****"
}

docker-compose.yml

environment:
  DEEPSEEK_API_BASE: 'http://<API网关>/v1'

修改后重启容器即可。

五、附加：DeepSeek V4 推理模型的特殊配置

除路径问题外，DeepSeek V4 Pro 作为推理模型，还需要额外配置：

5.1 开启 Thinking 模式

{
   
    "enable_thinking": true,
    "reasoning_effort": "high"
}

若不开启，CowAgent 的 Agent Bridge 会显式传 thinking={"type": "disabled"} 给 API，可能导致推理模型行为异常。

5.2 增大 max_tokens

DeepSeek V4 Pro 推理时先输出思考链（reasoning_content），再输出正文（content）。如果 max_tokens 太小，token 全消耗在推理阶段，正文就是空的。

CowAgent 的 DeepSeekBot.call_with_tools() 方法不主动传 max_tokens，需要打一个小补丁让它在 config 中读取。

修改 deepseek_bot.py 第 229 行：

# 修改前
max_tokens = kwargs.pop("max_tokens", None)

# 修改后
max_tokens = kwargs.pop("max_tokens", None) or conf().get("max_tokens")

然后在 config.json 中设置 "max_tokens": 16000，并将补丁文件挂载到容器：

volumes:
  - ./deepseek_bot.py:/app/models/deepseek/deepseek_bot.py

5.3 reasoning_content 回传

DeepSeek V4 在多轮工具调用中，要求后续请求必须原样回传 reasoning_content（即使是空字符串）。这一问题 CowAgent v2.0.8 已部分修复，确保使用最新版镜像即可。

相关社区讨论：

• anything-llm #5683
• opencode #24146

六、总结

核心教训：CowAgent 的 api_base 填 OpenAI 兼容 API 地址时，一定要检查是否包含 /v1 路径。它在 api_base 后面直接拼接 /chat/completions，不会自动补 /v1。