## 一、CowAgent 简介

[CowAgent](https://github.com/zhayujie/CowAgent)（原名 chatgpt-on-wechat）是一个开源的超级 AI 助理框架，GitHub **45,000+ Stars**，是国内 AI Agent 生态中 Star 数最高的项目之一，支持多模型（DeepSeek/OpenAI/Claude 等）、多渠道（微信/飞书/网页等）接入。

![Snipaste_2026-06-16_17-12-05.jpg](https://developer.qcloudimg.com/http-save/yehe-7747548/1cd2d77a0ad4f33d8185a5bf2dabf09d.jpg)

![img](https://developer.qcloudimg.com/http-save/yehe-7747548/bd222b515387a156d11c9a05cb48c3d6.png)

---

## 二、问题现象

在 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：

```python
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 发送请求时，我怀疑认证头格式不对。分别测试了两种方式：

```python
# 方式一：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。

在容器内分别测试：

```python
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**：

| 调用方式             | 请求 URL                               | 结果     |
| -------------------- | -------------------------------------- | -------- |
| 直接 requests        | `http://<API网关>/v1/chat/completions` | ✅ 正常   |
| CowAgent HTTP Client | `http://<API网关>/chat/completions`    | ❌ 空响应 |

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

CowAgent 的 URL 拼接逻辑是：

```python
# 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

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

### docker-compose.yml

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

修改后重启容器即可。

![Snipaste_2026-06-16_17-14-19.jpg](https://developer.qcloudimg.com/http-save/yehe-7747548/e9c8cf81388a33a36b46b413449576c6.jpg)

---

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

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

### 5.1 开启 Thinking 模式

```json
{
    "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 行：

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

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

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

```yaml
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](https://github.com/Mintplex-Labs/anything-llm/issues/5683)
- [opencode #24146](https://github.com/anomalyco/opencode/pull/24146)

---

## 六、总结

| 排查步骤             | 结果                            |
| -------------------- | ------------------------------- |
| API 直接调用         | ✅ 正常，排除后端问题            |
| 认证方式测试         | ✅ Bearer 认证正常，排除认证问题 |
| 切换其他模型         | ❌ 同样空响应，排除模型特定问题  |
| SSE 解析 vs 完整链路 | ❌ 解析正常但链路返回 0 chunk    |
| **URL 路径对比**     | **❌ 缺少 `/v1` 前缀**           |

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

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

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

CowAgent 接入第三方网关使用 DeepSeek V4，LLM 持续返回空响应。经 API 直调、SSE 解析到 HTTP Client 链路逐步排查，最终定位到 api_base 缺少 /v1 前缀。

人工智能

后端

开发工具

CowAgent开源AI框架接入DeepSeekV4Pro模型时出现空响应问题，排查发现api_base缺少/v1路径前缀导致请求失败。解决方案：修改api_base为http://<API网关>/v1，并配置thinking模式、增大max_tokens至16000。适用于微信/飞书等多渠道AI助手开发。

容器

Docker

快速部署LLM、AI绘画等应用,助你玩转AIGC！


2026年中大促 | AI 领航 智绘未来

cngw

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

CowAgent 接入第三方网关使用 DeepSeek V4 返回空响应问题的排查与解决-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐