一句话结论:别把 DeepSeek 硬塞成 Codex / Claude Code 的底层模型到处补兼容窟窿。 让 Claude Desktop 当唯一的主控入口,DeepSeek 要么作为网关后面的推理产能,要么做成一个自建 MCP 工具挂进来。所有输入输出都留在同一个会话里,上下文不再分裂。
先说我为什么平时只留 Codex + Claude Desktop
工具试过一圈,最后日常只剩两个:
- Codex:改仓库代码、跑测试、提 PR。它对仓库、沙箱、长任务的掌控力最好。
- Claude Desktop:对话、调研、写作、编排 MCP 工具。一个窗口里能挂文件、浏览器、记忆和各种工具,适合当「总控台」。
DeepSeek 便宜、量大、推理也够用,我一直想把它塞进这两个工具里。结果是:普通对话没问题,一到长会话、工具调用、压缩、自定义命令这些边缘功能就开始翻车。
这篇不是流水账。我把过去 3 周的会话日志过了一遍,把反复出现的坑归成三类,再给一套 macOS / Windows / Linux 都能直接照抄的接法:直连 DeepSeek 官方 API 能跑,走 One API / New API / LiteLLM / Magpie 这类 OpenAI 兼容网关也能跑。
一、实测底座:日志里反复出现的坑
样本是我最近 21 天的本机会话记录:Codex 352 个会话(约 1.8 GB),Claude Code / Claude Desktop 代码会话 1,410 个(约 3.5 GB)。其中提到 DeepSeek 的分别有 284 个和 770 个,量足够说明这不是偶发问题。
反复出现的报错,归下来就三类:
| 断层 | 日志里的真实报错 | 根因 |
|---|---|---|
| 协议 / 有状态接口 | 400 unsupported_input_item:Item references need stored responses | Codex 走 Responses 协议,长会话压缩(compact)会引用之前存过的响应;很多兼容端点只支持无状态调用 |
400 Thinking mode does not support this tool_choice | Agent 类客户端会强制指定 tool_choice,DeepSeek 思考模式不接受 | |
多轮工具调用后 400(reasoning_content 未回传) | DeepSeek 文档要求:带 tools 的请求必须把之前每轮的 reasoning_content 原样回传;网关在 Anthropic ⇄ OpenAI 格式互转时容易丢掉它 | |
command 的两重坑 | MCP 握手 Connection closed、spawn npx ENOENT、command not found | GUI 应用不加载你终端的 Shell 初始化,PATH 里没有 Homebrew / nvm / uv 的目录 |
MCP error -32602 / -32603(参数类型不对)、-32001 Request timed out | 模型把 object 参数传成了 string;推理型任务超过客户端默认超时 | |
| 上下文分裂 | 没有报错,但最贵 | 网页 DeepSeek、终端 Codex、桌面 Claude 来回复制背景,每切一次丢一半约束 |
下面逐个拆。
1. 协议断层:「兼容 OpenAI」不等于「兼容 Codex 用到的全部特性」
最典型的是 Codex 的压缩。Codex 走 Responses 协议,上下文快满时先发一个 compact 请求,里面会带 item_reference 引用之前存储过的响应。很多号称「支持 Responses」的线路只做了无状态调用,一碰就是 400 unsupported_input_item。网关再把它包装成 5xx,客户端重试几次后整段会话卡死。完整排查我写在《Codex 长会话卡在 Failed to run pre-sampling compact》。
Claude Code 这一侧,问题出在工具调用细节:
- Agent 会强制模型调用某个工具(
tool_choice指定为某个工具或required),DeepSeek 思考模式直接拒绝:Thinking mode does not support this tool_choice。 - DeepSeek 官方文档写得很清楚:请求里带
tools时,之前所有轮次的reasoning_content都必须回传,否则返回 400;不带tools时则不需要回传,传了也会被忽略。经过网关做 Anthropic ⇄ OpenAI 格式转换时,这个字段很容易被丢掉。
还有一条是体感,不是报错:订阅账号自带的能力,走网关就拿不到。 同一套工作流,直接登录官方账号跑,往往比经网关转发更稳。网关只能转协议,转不了账号特性。
结论:普通对话能通,不代表压缩、强制工具调用、思考链回传这些「长会话后半段才触发」的功能能通。主力工具的底层模型,尽量走原生线路。
2. command 的两重坑
第一重:MCP 配置里的 command。
Claude Desktop、Codex 桌面版这类 GUI 应用启动 MCP 服务器时,不会执行你的 ~/.zshrc / ~/.zprofile / ~/.bashrc。我遇到过两个很隐蔽的情况:
~/.zprofile第一行是eval "$(brew shellenv)"。非登录 Shell 不执行它,/opt/homebrew/bin就进不了PATH,于是bun、gh、psql明明装了却报 command not found。- 另一个目录里放了一个旧版
node,排在 nvm 前面,把 nvm 的版本遮住了。MCP 用的是旧版,直接启动失败。
在 GUI 里,这些问题统一表现为:MCP 列表里服务器显示失败,日志里是 spawn npx ENOENT 或握手阶段 Connection closed。
根治办法只有一个:command 一律写绝对路径。 我现在 Claude Desktop 里的本地 MCP,command 全部写成 node / uvx 的绝对路径,之后再没出过这类问题。macOS 版 Claude Desktop 的日志会打印 Using MCP server command: ... with path: [...],能直接看到它实际用的是哪个可执行文件、搜了哪些目录。
还有一个常见坑:stdio 模式下,stdout 就是 JSON-RPC 通道。 服务器里随手 print() / console.log() 一句,客户端就会解析失败或断开。官方教程专门强调过:日志只能写 stderr。
第二重:CLI / slash command 跨模型不一致。
/compact、/goal、/plan 这类命令是客户端功能,背后绑定的是原厂协议的某个接口或行为约定。换了底层模型,命令还在,背后那一步可能已经不成立了,比如上面的压缩。用户看到的只是「命令不好使了」。
3. 上下文分裂税
这是最贵、又最容易被忽略的一项:网页里问 DeepSeek,终端里让 Codex 改,桌面上让 Claude 总结。每次切换都要重新贴背景,约束丢一半,结论还要手动搬回来。
我会话记录里很多「如果上下文太长就开新 session 继续」「先接上现有上下文」这样的指令,本质上都是在给分裂的上下文打补丁。
二、收敛架构:Claude Desktop 一个主上下文
最后收敛成这样(见文首架构图):
- Claude Desktop = 唯一主控入口:管全局意图、多轮上下文、文件和工具编排。所有子任务的结果都回到这一个会话里。
- DeepSeek = 推理产能,有两种接法:
- A. 推理走网关:Claude Desktop 官方支持「第三方推理(3P)」模式,可以把推理指向任何实现了 Anthropic Messages API 的网关(LiteLLM、Portkey、自建代理等),DeepSeek 挂在网关后面。我现在就是这种形态。
- B. 自建 DeepSeek MCP:主模型不动,把 DeepSeek 封装成几个专职工具,比如长文和日志提炼、方案二审、带
session_id的连续追问。Claude 自己决定什么时候外包给它,结果回流到同一个会话。不想动主模型的人,B 最轻,也最不容易撞上协议断层。
- Codex = 只管仓库:改代码、跑测试、提 PR。用原生线路,长会话最稳。不把 DeepSeek 硬塞进它的底层。
为什么 B 不容易撞协议坑?因为 MCP 服务器调 DeepSeek 用的是最朴素的 Chat Completions:不带 tools,不需要回传 reasoning_content,也没有 tool_choice 和压缩。 前面三类断层,在这条链路上基本都绕开了。
三、10 分钟模板:自建 DeepSeek MCP(通用版)
3.1 准备
- Python 3.10+,安装 uv。
- 一个 DeepSeek API Key,或者你的网关地址和网关 Key。
uv init deepseek-mcp && cd deepseek-mcp
uv add "mcp[cli]" openai
注意版本:官方 Python SDK 2.x 把
FastMCP改名成了MCPServer(from mcp.server import MCPServer)。网上大量教程还是 1.x 写法,直接照抄会报No module named 'mcp.server.fastmcp'。下面代码按 2.x 写,并注明了 1.x 怎么改。
3.2 服务器代码:deepseek_mcp.py
"""deepseek_mcp.py —— 把 DeepSeek(或任意 OpenAI 兼容网关)封装成 MCP 工具,给 Claude Desktop 当外挂大脑。
环境变量:
OPENAI_BASE_URL 默认 https://api.deepseek.com;也可填 One API / New API / LiteLLM / Magpie 等网关地址(通常以 /v1 结尾)
OPENAI_API_KEY DeepSeek 官方 Key 或网关 Key
DS_FAST_MODEL 默认 deepseek-flash
DS_DEEP_MODEL 默认 deepseek-v4-pro
DS_THINKING_PARAM 网关不认 thinking 参数时设为 off
"""
import logging
import os
import sys
import uuid
from collections import OrderedDict
from openai import AsyncOpenAI
from mcp.server import MCPServer # mcp 2.x;若你锁在 mcp<2,改成 from mcp.server.fastmcp import FastMCP as MCPServer
# stdio 模式下 stdout 是 JSON-RPC 管道:所有日志只能走 stderr
logging.basicConfig(stream=sys.stderr, level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("deepseek-mcp")
API_KEY = os.environ.get("OPENAI_API_KEY") or os.environ.get("DEEPSEEK_API_KEY")
if not API_KEY:
log.warning("OPENAI_API_KEY / DEEPSEEK_API_KEY 未设置,工具调用会返回鉴权错误")
client = AsyncOpenAI(
base_url=os.environ.get("OPENAI_BASE_URL", "https://api.deepseek.com"),
api_key=API_KEY or "missing-key", # 空值会让 SDK 在启动时直接抛错,导致握手 Connection closed
timeout=float(os.environ.get("DS_TIMEOUT", "180")),
)
FAST_MODEL = os.environ.get("DS_FAST_MODEL", "deepseek-flash")
DEEP_MODEL = os.environ.get("DS_DEEP_MODEL", "deepseek-v4-pro")
SEND_THINKING = os.environ.get("DS_THINKING_PARAM", "on") != "off"
MAX_MESSAGES = int(os.environ.get("DS_MAX_MESSAGES", "40")) # 每个会话最多保留多少条历史
MAX_SESSIONS = 50
mcp = MCPServer("deepseek")
SESSIONS: "OrderedDict[str, list[dict]]" = OrderedDict()
async def _chat(messages: list[dict], deep: bool) -> str:
extra = {}
if SEND_THINKING:
# DeepSeek 默认开思考;快活儿显式关掉,省时间省 token
extra["extra_body"] = {"thinking": {"type": "enabled" if deep else "disabled"}}
resp = await client.chat.completions.create(
model=DEEP_MODEL if deep else FAST_MODEL, messages=messages, **extra
)
# 只取最终答案;不带 tools 的请求里 reasoning_content 无需回传
return resp.choices[0].message.content or ""
@mcp.tool()
async def ask_deepseek(prompt: str, session_id: str = "", system: str = "", deep: bool = False) -> str:
"""把一个子任务交给 DeepSeek。传入上次返回的 session_id 可在同一子会话里连续追问;deep=True 用推理模型。"""
sid = session_id or uuid.uuid4().hex[:8]
history = SESSIONS.setdefault(sid, [])
SESSIONS.move_to_end(sid)
while len(SESSIONS) > MAX_SESSIONS:
SESSIONS.popitem(last=False)
messages = ([{"role": "system", "content": system}] if system else []) + history
messages.append({"role": "user", "content": prompt})
try:
answer = await _chat(messages, deep)
except Exception as e: # 把错误原样交还给 Claude,让它决定重试还是换路
log.exception("deepseek call failed")
return f"[deepseek error] {type(e).__name__}: {e}"
history += [{"role": "user", "content": prompt}, {"role": "assistant", "content": answer}]
del history[:-MAX_MESSAGES]
log.info("session=%s messages=%d", sid, len(history))
return f"{answer}\n\n[session_id: {sid}]"
@mcp.tool()
async def digest(text: str, focus: str = "关键结论、数字、报错和待办") -> str:
"""长文、日志、网页正文提炼:只返回与 focus 相关的要点,不把原文塞进主对话。"""
prompt = f"只提取与「{focus}」相关的信息,分条输出,保留原始数字和报错原文,不要编造:\n\n{text}"
try:
return await _chat([{"role": "user", "content": prompt}], deep=False)
except Exception as e:
log.exception("digest failed")
return f"[deepseek error] {type(e).__name__}: {e}"
@mcp.tool()
async def second_opinion(plan: str, context: str = "") -> str:
"""让推理模型对方案做对抗式二审:找漏洞、反例和更省的替代方案。"""
prompt = (
"你是严格的评审。请逐条指出下面方案的风险、遗漏和错误假设,给出反例,最后给出你会怎么改。\n"
f"[背景]\n{context}\n\n[方案]\n{plan}"
)
try:
return await _chat([{"role": "user", "content": prompt}], deep=True)
except Exception as e:
log.exception("second_opinion failed")
return f"[deepseek error] {type(e).__name__}: {e}"
@mcp.tool()
def reset_session(session_id: str) -> str:
"""清空某个子会话的历史。"""
SESSIONS.pop(session_id, None)
return f"session {session_id} cleared"
if __name__ == "__main__":
mcp.run(transport="stdio")
几个设计点:
OPENAI_BASE_URL一换就能切线路:默认直连https://api.deepseek.com;换成 One API / New API / LiteLLM / Magpie 的地址(一般以/v1结尾)就走网关,代码一行不改。- 快慢分档:默认
deepseek-flash并显式关掉思考;需要深推理时deep=True,用deepseek-v4-pro并打开思考。模型名都可以用环境变量覆盖,网关里的自定义模型名也照填。 - 思考参数可关:有些网关不认
thinking字段,设DS_THINKING_PARAM=off即可。 - 轻量会话缓存:
ask_deepseek返回session_id,Claude 下次带上它,就能在同一个子会话里追问,不用重贴背景。只保留最近 40 条、最多 50 个会话,重启即清空,不落盘。 - 日志只写 stderr,错误原样返回给 Claude,让它自己决定重试还是换路。
我用 MCP 官方客户端、官方 Inspector CLI 和本地模拟的 OpenAI 兼容端点跑过一遍:4 个工具都能被发现;不填 Key 时服务器照常启动,调用时把 401 原样返回,不会在握手阶段崩成 Connection closed;同一 session_id 的第二次请求带上了前一轮历史;deep=True 时请求会切到推理模型并打开思考。
3.3 接进 Claude Desktop:command 一律写绝对路径
先查绝对路径:
# macOS / Linux
which uv # 例:/Users/<you>/.local/bin/uv 或 /opt/homebrew/bin/uv
cd deepseek-mcp && pwd
# Windows
where.exe uv # 例:C:\Users\<you>\.local\bin\uv.exe
cd deepseek-mcp; (Get-Location).Path
配置文件位置:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
macOS / Linux:
{
"mcpServers": {
"deepseek": {
"command": "/ABSOLUTE/PATH/TO/uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/deepseek-mcp", "run", "deepseek_mcp.py"],
"env": {
"OPENAI_BASE_URL": "https://api.deepseek.com",
"OPENAI_API_KEY": "<YOUR_DEEPSEEK_OR_GATEWAY_KEY>"
}
}
}
}
Windows(JSON 里反斜杠要写两个):
{
"mcpServers": {
"deepseek": {
"command": "C:\\Users\\<you>\\.local\\bin\\uv.exe",
"args": ["--directory", "C:\\path\\to\\deepseek-mcp", "run", "deepseek_mcp.py"],
"env": {
"OPENAI_BASE_URL": "https://api.deepseek.com",
"OPENAI_API_KEY": "<YOUR_DEEPSEEK_OR_GATEWAY_KEY>"
}
}
}
}
走网关时,只改 env:
"env": {
"OPENAI_BASE_URL": "<YOUR_GATEWAY_URL>/v1",
"OPENAI_API_KEY": "<YOUR_GATEWAY_KEY>",
"DS_FAST_MODEL": "<网关里的快模型名>",
"DS_DEEP_MODEL": "<网关里的推理模型名>"
}
改完要彻底退出 Claude Desktop 再打开:macOS 用 Cmd+Q;Windows 要在系统托盘里右键退出。只关窗口不会生效。
Windows 上如果别的 MCP 用的是
npx,记得npx实际是npx.cmd。直接写"command": "npx"容易ENOENT,常见写法是"command": "cmd","args": ["/c", "npx", "-y", "<package>"],或者同样换成绝对路径。
3.4 Codex 对照:同一个服务器也能挂进 Codex
~/.codex/config.toml:
[mcp_servers.deepseek]
command = "/ABSOLUTE/PATH/TO/uv"
args = ["--directory", "/ABSOLUTE/PATH/TO/deepseek-mcp", "run", "deepseek_mcp.py"]
startup_timeout_sec = 30
tool_timeout_sec = 300 # 深推理慢,给足时间,避免 Request timed out
[mcp_servers.deepseek.env]
OPENAI_BASE_URL = "https://api.deepseek.com"
OPENAI_API_KEY = "<YOUR_DEEPSEEK_OR_GATEWAY_KEY>"
这样 Codex 的主模型保持原生线路,需要便宜的二审或日志提炼时,它也能调 DeepSeek。底层不换,协议坑就不会出现。
3.5 上线前自检
先不经过任何客户端,直接用官方 Inspector 看能不能列出工具:
npx @modelcontextprotocol/inspector --cli /ABSOLUTE/PATH/TO/uv --directory /ABSOLUTE/PATH/TO/deepseek-mcp run deepseek_mcp.py --method tools/list
能列出 ask_deepseek / digest / second_opinion / reset_session,再带上 Key 真调一次(-e 传环境变量):
npx @modelcontextprotocol/inspector --cli -e OPENAI_API_KEY=<YOUR_KEY> /ABSOLUTE/PATH/TO/uv --directory /ABSOLUTE/PATH/TO/deepseek-mcp run deepseek_mcp.py --method tools/call --tool-name ask_deepseek --tool-arg prompt=你好
都通了,再去 Claude Desktop 里试一句:「用 deepseek 的 second_opinion 审一下这个方案」。
四、可选路线 A:Claude Desktop 推理整体走网关
如果你本来就想让 Claude Desktop 的主模型也走自己的网关(团队统一计费、混用多家模型),官方有正式支持,叫 Claude Desktop on 3P:
- 菜单 Help → Troubleshooting → Enable Developer Mode;
- Developer → Configure Third-Party Inference…;
- Inference provider 选 Gateway,填 Gateway base URL、Gateway API key、鉴权方式(Bearer 或 x-api-key)。
硬性要求:网关要实现 POST /v1/messages,并支持流式和工具调用。GET /v1/models 可选;没有的话需要手动设置 inferenceModels。LiteLLM、Portkey 或自建代理都可以,DeepSeek 挂在网关后面。DeepSeek 官方也提供了 Anthropic 格式端点(https://api.deepseek.com/anthropic)。
走 A 要清楚两点:
- 前面说的
tool_choice/reasoning_content问题仍然存在。网关最好能按请求类型路由:强制工具调用的请求关掉思考,或者路由到能处理它的模型。 - 3P 模式下没有 Claude.ai 登录,订阅账号的专属能力用不了。会话存在本机。
我的建议:个人用户优先选 B,主模型原生 + DeepSeek 外挂,最稳。已经有成熟网关、要统一计费的,再上 A。两者可以叠加。
五、分工决策表
| 任务 | 放哪 | 理由 |
|---|---|---|
| 定方向、拆任务、多轮讨论、最终拍板 | Claude Desktop 主模型 | 需要完整上下文和最强判断力 |
| 长文 / 日志 / 网页正文提炼 | DeepSeek MCP digest | 量大、规则明确,不必让主模型逐字读原文 |
| 方案二审、找反例 | DeepSeek MCP second_opinion(deep=True) | 让另一个模型找漏洞,便宜又能避开同一模型的盲区 |
| 批量结构化生成(标题、摘要、分类、改写) | DeepSeek MCP ask_deepseek + session_id | 高并发、低成本,同一子会话保持口径一致 |
| 改仓库代码、跑测试、提 PR | Codex(原生线路) | 长会话 + 压缩 + 沙箱,最依赖原生协议 |
| 跨会话要记住的事实 | Memory 类 MCP 或项目文档 | 不靠长上下文硬撑,开新会话也能接上 |
成本上,我的原则是:主模型的 token 花在判断上,体力活的 token 交给 DeepSeek。 各家 DeepSeek 套餐和渠道的实际单价差异,我在《同样 10 美元,三家 DeepSeek 套餐各能跑多少 token》里算过,这里不重复。
六、排障速查
| 现象 | 原因 | 解法 |
|---|---|---|
MCP 列表里服务器失败,日志 spawn uv/npx/node ENOENT | GUI 不继承终端 PATH | command 写绝对路径(which / where.exe 查) |
终端能跑,GUI 里 command not found,或用了旧版 node | Shell 初始化只在登录 Shell 执行;别的目录里的旧二进制排在前面 | 绝对路径;检查 which -a node 的顺序 |
握手阶段 Connection closed | 进程启动即崩溃,或 stdout 输出了非 JSON-RPC 内容 | 看 mcp-server-<名字>.log;去掉所有 print / console.log,日志改写 stderr |
握手失败,服务器日志里是 OpenAIError: Missing credentials | 新版 OpenAI SDK 在 Key 为空时会在启动阶段直接抛错 | 在 env 里传 Key;或像模板一样先给占位值,调用时再报错 |
No module named 'mcp.server.fastmcp' | 装的是 SDK 2.x | 改成 from mcp.server import MCPServer,或锁定 mcp<2 |
工具返回 [deepseek error] AuthenticationError | Key 没传进去 | 检查 env 拼写;改完要彻底退出客户端再开 |
MCP error -32001: Request timed out | 深推理超过客户端默认超时 | Codex 调大 tool_timeout_sec;重活拆小;先用快模型 |
MCP error -32602 / -32603 参数校验失败 | 模型把 object 传成了 string | 工具参数尽量用简单类型(str / bool),像本文模板这样 |
400 Thinking mode does not support this tool_choice | 强制工具调用 + 思考模式 | 不要把 DeepSeek 当 Agent 底座;或在网关里对这类请求关掉思考 |
| 多轮工具调用后 400 | reasoning_content 没回传 | 带 tools 的请求必须原样回传;MCP 模板不带 tools,不受影响 |
Codex 压缩失败 unsupported_input_item | 线路不支持 stored response | Codex 底层走原生线路;DeepSeek 只通过 MCP 用 |
| 改了配置没生效 | 只关了窗口 | macOS 用 Cmd+Q;Windows 在托盘里退出 |
日志位置:macOS ~/Library/Logs/Claude/mcp*.log,Linux ~/.config/Claude/logs/。mcp.log 记录连接情况,mcp-server-<名字>.log 记录该服务器的 stderr。
写在最后
DeepSeek 好用,但它最适合当产能,不适合当你主力工具的底座。底座要稳,协议要原生;产能要便宜,接口要朴素。中间用 MCP 这根标准管子连起来,主上下文只留一个。
想看我之前怎么把一堆 MCP 收成一条链路、以及 Claude Desktop 只能自动写入本地命令型服务器的细节,可以看《Magpie、Chrome DevTools MCP 与 Playwright:我把 9 个 MCP 收成了一条链路》。
口径:会话数和报错类型来自我 2026-10-16 至 11-06 的本机 Codex / Claude 会话日志(只做关键词统计,项目名、路径和密钥均已略去);MCP 模板已用官方 Python SDK 2.x 客户端 + 本地模拟端点验证工具发现、会话续接和快慢模型切换,未消耗真实 DeepSeek 额度;DeepSeek 模型名、思考参数以 2026-11-06 官方文档为准,后续可能调整。
COMMENTS
读者评论