一句话结论:别把 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 responsesCodex 走 Responses 协议,长会话压缩(compact)会引用之前存过的响应;很多兼容端点只支持无状态调用
400 Thinking mode does not support this tool_choiceAgent 类客户端会强制指定 tool_choice,DeepSeek 思考模式不接受
多轮工具调用后 400(reasoning_content 未回传)DeepSeek 文档要求:带 tools 的请求必须把之前每轮的 reasoning_content 原样回传;网关在 Anthropic ⇄ OpenAI 格式互转时容易丢掉它
command 的两重坑MCP 握手 Connection closed、spawn npx ENOENT、command not foundGUI 应用不加载你终端的 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:

  1. 菜单 Help → Troubleshooting → Enable Developer Mode;
  2. Developer → Configure Third-Party Inference…;
  3. 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高并发、低成本,同一子会话保持口径一致
改仓库代码、跑测试、提 PRCodex(原生线路)长会话 + 压缩 + 沙箱,最依赖原生协议
跨会话要记住的事实Memory 类 MCP 或项目文档不靠长上下文硬撑,开新会话也能接上

成本上,我的原则是:主模型的 token 花在判断上,体力活的 token 交给 DeepSeek。 各家 DeepSeek 套餐和渠道的实际单价差异,我在《同样 10 美元,三家 DeepSeek 套餐各能跑多少 token》里算过,这里不重复。

六、排障速查

现象原因解法
MCP 列表里服务器失败,日志 spawn uv/npx/node ENOENTGUI 不继承终端 PATHcommand 写绝对路径(which / where.exe 查)
终端能跑,GUI 里 command not found,或用了旧版 nodeShell 初始化只在登录 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] AuthenticationErrorKey 没传进去检查 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 底座;或在网关里对这类请求关掉思考
多轮工具调用后 400reasoning_content 没回传带 tools 的请求必须原样回传;MCP 模板不带 tools,不受影响
Codex 压缩失败 unsupported_input_item线路不支持 stored responseCodex 底层走原生线路;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 官方文档为准,后续可能调整。