先说结论把 DeepSeek 接进 Claude Code不是简单地在环境变量里填一个 base_url 和一个 API key 就能完事的。我第一次这么干的时候Claude Code 回了我一个干干净净的 404当时我还以为是 key 填错了翻来覆去排查了两个小时最后才发现卡住我的根本不是 key而是协议。这篇文章把我从配置失败到最终跑通的完整思路、报错分析和参考实现都整理出来了给同样想在 Claude Code 里用 DeepSeek 的人一条可以照着走的路径。如果你已经在用 Claude Code想把默认模型换成 DeepSeek 试试或者因为成本原因想找一个替代模型那么这篇文章正好对你有用。1. 换模型这件事本质是让两个协议完成握手1.1 Claude Code 到底在用什么接口说话Claude Code 这个工具默认情况下只认一套自家生态的接口协议。它发请求的时候走的不是大家最常见的 Chat Completions 风格而是类似 /v1/messages 这个路径。请求体大概是这个样子curl -X POST https://api.example.com/v1/messages \ -H x-api-key: $KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-xxx, max_tokens: 4096, messages: [ { role: user, content: [ {type: text, text: 帮我写一个快速排序} ] } ] }注意看几个细节请求头里带了 anthropic-versioncontent 字段是一个数组数组里每个元素都有 type。响应更是完全不同的风格走的是 SSE 流式返回事件类型叫 message_start、content_block_delta、message_delta 这些。Claude Code 就是靠这些事件来识别“模型开始说话”“模型说了一段话”“模型说完了”的。这就是 Claude Code 出门必带的“原生协议”它在设计时只打算和讲同一套协议的模型服务通信。1.2 DeepSeek 的接口习惯DeepSeek 官方 API 走的是另一套风格路径是 /chat/completions请求体里 content 是普通字符串而不是块数组。同样是“帮我写一个快速排序”DeepSeek 那边长这样curl https://api.deepseek.com/chat/completions \ -H Authorization: Bearer $KEY \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [ {role: user, content: 帮我写一个快速排序} ], stream: false }两者字段长得有点像但细节完全不是一个体系。我列个表对比一下这是整个折腾过程中最核心的认知对比维度Claude Code 调用模型时DeepSeek API请求路径/v1/messages/chat/completions认证方式x-api-key 头Authorization: Bearer请求体 content 格式数组块结构字符串系统提示词独立 system 字段messages 数组里用 system 角色流式返回content_block_delta / message_deltachoices[0].delta.content工具调用格式tool_use 内容块tool_calls 数组这种感觉特别像一个从国内买的电器带到另一个国家用插头制式不一样插座对不上。你不是没电你是插不进去。1.3 base_url 并不是万能入口很多人包括一开始的我有一个误解觉得 Claude Code 既然支持配置 ANTHROPIC_BASE_URL那我只要把这个地址指向 DeepSeek 的服务器再把 key 换成 DeepSeek 的 key不就完事了吗不是的。这个 base_url 替换能力设计初衷是让你把请求转发到另一个同样讲 Claude Code 原声协议的网关服务而不是让你直接连一个讲完全不同方言的 API。你可以把 base_url 想象成快递的转运地址你能改的是“送到哪个仓库”但你没法让快递公司突然改说另一种语言来录单。所以直连 DeepSeek 的结果通常是路径 404、格式 400、或者认证 401五花八门但都不是 key 的问题。搞清楚这一点之后整个问题就从“配置问题”变成了“协议翻译问题”。2. 第一次直连的失败现场三个典型报错2.1 最容易发生的404 route not found我最开始的做法非常简单粗暴配置了三件套环境变量export ANTHROPIC_BASE_URLhttps://api.deepseek.com export ANTHROPIC_API_KEYsk-your-deepseek-key export ANTHROPIC_MODELdeepseek-chat然后满心欢喜地运行 claude结果还没开始对话就崩了报错内容大意是 404 Not Found后面还跟着一句 route not found。这个报错其实特别直白Claude Code 拿着它固定的 /v1/messages 路径去请求 https://api.deepseek.com/v1/messages而 DeepSeek 的服务器根本没有这个路由自然就 404 了。这个 404 和 key 一点关系都没有纯粹是 DeepSeek 服务器看了半天发现这个地址它压根不提供服务。2.2 被误导后的常见错400 invalid messages format在群里问了一圈之后有同行跟我说“你别把 base_url 直接指向根域名你加上 /v1 试试DeepSeek 的接口都是带 /v1 前缀的。”于是我把 ANTHROPIC_BASE_URL 改成 https://api.deepseek.com/v1再跑。这次错误变成了 400信息大体是 invalid request body 或者 message format not supported。原因很简单即便 DeepSeek 服务器收到了请求它期待的是 content 是字符串结果 Claude Code 发过来的是 content 数组里面还有 type 字段。两边字段对不上DeepSeek 自然就不认。这说明一个残酷的事实就算你千辛万苦把路径搞对了请求体格式还是对不上协议这层墙依然挡在中间。2.3 存在感很强的401 invalid api key还有一个报错非常容易遇到就是 401 Unauthorized。我在排查过程中一度把 key 放到各种位置试有几次是把 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 混着写或者把 base_url 不小心留成了默认值结果请求根本没发往 DeepSeek而是回到默认服务那边去做认证了人家一看这个 key 不是自己签发的直接给 401。这个错误给我的启发是认证错误不一定意味着 key 失效更多时候意味着请求落到了你没想到的服务器上。所以看到 401 的时候别急着换 key先确认请求到底发到哪儿去了。2.4 还有一类一直卡住或者静默失败除了直接报错之外还有一类比较隐蔽的现象Claude Code 界面看着像正常启动了但你一说话它就一直在转圈或者等很久之后告诉你“请求超时”。这类问题通常和流式响应格式有关Claude Code 在等它认识的 SSE 事件如果对面的服务返回的流式事件它不认得它就会一直等下去。这个问题我先埋个坑后面第五节会专门细说。3. 排查链路从“怀疑 key”到“确认协议不兼容”3.1 先用 DeepSeek 原生接口验证 key被三个报错轮番折磨之后我开始冷静下来把 Claude Code 暂时放一边先用最原始的方式验证 key 到底有没有问题。这一步其实很简单直接用 curl 调 DeepSeek 的 /chat/completions 接口发一个最简单的请求curl https://api.deepseek.com/chat/completions \ -H Authorization: Bearer $DEEPSEEK_KEY \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [{role: user, content: 11等于几}], stream: false }如果这一步能正常返回 choices 里的内容那就说明API key 是有效的网络是通的账户余额是够的。我把这个步骤叫“最小可用验证”。任何模型接进来第一步都应该先做这种事而不是直接丢到上层工具里猜。3.2 再用 Claude Code 原生风格请求同一个地址key 验证通过之后下一步就是故意让 Claude Code 风格请求去撞 DeepSeek 的接口。我用同样的 key但是换成 Claude Code 的请求格式curl -X POST https://api.deepseek.com/v1/messages \ -H x-api-key: $DEEPSEEK_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: deepseek-chat, max_tokens: 100, messages: [ {role: user, content: [{type: text, text: 11等于几}]} ] }结果毫无悬念不是 404 就是 400。这一步把问题彻底隔离出来了key 没问题问题出在“Claude Code 说一套话DeepSeek 听不懂”。我不再怀疑配置细节而是确定需要一个中间翻译层。3.3 抓客户端日志确认实际请求地址排查过程中我建议一定要开启 Claude Code 的调试日志或者用 verbose 模式启动。通过日志可以看到它真正发出去的 URL 是什么、请求体是什么、响应又是什么。很多“玄学报错”在日志面前都会原形毕露比如你以为请求发到了 DeepSeek其实它发去了默认地址你以为传的是正确的 key其实读的是另一个环境变量的值。我把这三步走完以后问题的边界就非常清楚了key 是好的网络是通的只是 Claude Code 和 DeepSeek 之间缺一个协议翻译器。接下来的工作就一句话把 /v1/messages 的请求翻译成 /chat/completions 的请求再把响应翻译回去。4. 解决本地起一个只有几百行的协议转换代理4.1 为什么自建而不是改客户端有人会问能不能直接改 Claude Code 的源码或者通过插件强制它用 DeepSeek 的原生接口我的回答是不要这么做。Claude Code 迭代很快每次升级都会覆盖你的改动而且很多逻辑是内部封装好的你改了也不一定能稳定工作。与其研究怎么让客户端“迁就”DeepSeek不如在客户端和服务之间插一个本地小代理让代理两头各说各话。这个方案的好处是对 Claude Code 来说它看到的是一个“讲原声协议的模型服务”完全不知道背后发生了什么对 DeepSeek 来说它看到的是一个“用 Chat Completions 风格调它的普通客户端”。两边都不需要改动我只维护中间这层翻译而且这层翻译是可重复复用的以后想接 DeepSeek 的任何模型都方便。4.2 消息格式转换的代码实现我用的是 Python 的 FastAPI 框架加上 httpx 做异步转发。选择 Python 是因为这类文本转换代码写起来快异步流式支持也成熟。代码不复杂核心就三块接收 Claude Code 格式请求、转换成 DeepSeek 格式、把响应流式翻译回去。先建一个 proxy.py下面是参考实现import json import os import httpx from fastapi import FastAPI, Request from fastapi.responses import JSONResponse, StreamingResponse app FastAPI() DEEPSEEK_BASE os.getenv(DEEPSEEK_BASE, https://api.deepseek.com) DEEPSEEK_KEY os.getenv(DEEPSEEK_KEY, ) MODEL os.getenv(DEEPSEEK_MODEL, deepseek-chat) def convert_content(content): if isinstance(content, str): return content if isinstance(content, list): parts [] for block in content: if block.get(type) text and block.get(text): parts.append(block[text]) return \n.join(parts) if parts else return def convert_messages(payload): messages [] if payload.get(system): messages.append({role: system, content: payload[system]}) for msg in payload.get(messages, []): role msg.get(role, user) text convert_content(msg.get(content)) if messages and messages[-1][role] role: merged (messages[-1][content] \n text).strip() messages[-1][content] merged else: messages.append({role: role, content: text}) return messages def build_openai_payload(payload): openai_payload { model: MODEL, messages: convert_messages(payload), stream: True, max_tokens: min(payload.get(max_tokens, 4096), 8000), } if payload.get(temperature) is not None: openai_payload[temperature] payload[temperature] return openai_payload def sse_event(event, data): return fevent: {event}\ndata: {json.dumps(data)}\n\n async def event_stream(resp): # 告诉 Claude Code 事件开始 yield sse_event(message_start, { type: message_start, message: { id: msg_local_1, type: message, role: assistant, model: MODEL, content: [], stop_reason: None, stop_sequence: None, }, }) yield sse_event(content_block_start, { type: content_block_start, index: 0, content_block: {type: text, text: }, }) async for line in resp.aiter_lines(): if not line.startswith(data:): continue data line[len(data:):].strip() if not data or data [DONE]: break try: chunk json.loads(data) except Exception: continue choices chunk.get(choices, []) if not choices: continue delta choices[0].get(delta, {}) text delta.get(content) if not text: continue yield sse_event(content_block_delta, { type: content_block_delta, index: 0, delta: {type: text_delta, text: text}, }) # 结束事件Claude Code 靠这个判断任务完成 yield sse_event(message_delta, { type: message_delta, delta: {stop_reason: end_turn, stop_sequence: None}, }) yield sse_event(content_block_stop, {type: content_block_stop, index: 0}) yield sse_event(message_stop, {type: message_stop}) app.post(/v1/messages) async def proxy_messages(request: Request): payload await request.json() openai_payload build_openai_payload(payload) headers { Authorization: fBearer {DEEPSEEK_KEY}, Content-Type: application/json, } async with httpx.AsyncClient(timeout180) as client: req client.build_request( POST, f{DEEPSEEK_BASE}/chat/completions, headersheaders, jsonopenai_payload, ) resp await client.send(req, streamTrue) if resp.status_code ! 200: body await resp.aread() return JSONResponse( status_coderesp.status_code, content{type: error, message: body.decode()}, ) return StreamingResponse(event_stream(resp), media_typetext/event-stream)这段代码里有个细节值得单独说convert_messages 里我把连续相同 role 的消息合并了。这是因为 Claude Code 的历史对话里经常出现连续两条 user 消息或者连续两条 assistant 消息而 DeepSeek 这类服务对消息交替顺序要求比较严格连续相同角色通常会被拒。这个坑我在第五节还会再提但代码里先处理掉了。4.3 SSE 事件流怎么“翻译”才不会让客户端转圈很多人写转换代理的时候只想着“把请求体转一下”却忽略了响应流。实际上 Claude Code 对响应流的事件类型非常敏感它不认 OpenAI 风格的 choices[0].delta.content它只认 content_block_delta 这类事件。我在这段代码里补全了完整的事件序列message_start 表示开始content_block_start 表示第一个内容块中间反复发 content_block_delta 携带文本增量最后发 message_delta 设置 stop_reason 为 end_turn再发 content_block_stop 和 message_stop 告诉客户端“我说完了”。这个顺序不是可有可无的。你哪怕少了一个 content_block_stopClaude Code 都可能认为这一次回答还没结束表现为对话框一直在转圈最后超时。这个知识点是我调试时最花时间的部分先放这里提醒你后面还会展开。4.4 启动代理并回填环境变量代码保存为 proxy.py 之后先设置代理侧的密钥export DEEPSEEK_KEYsk-your-deepseek-key export DEEPSEEK_MODELdeepseek-chat然后启动服务uvicorn proxy:app --host 127.0.0.1 --port 8080接着回到 Claude Code 那边把环境变量改成指向本地代理export ANTHROPIC_BASE_URLhttp://127.0.0.1:8080 export ANTHROPIC_API_KEYsk-local-proxy-placeholder这里 ANTHROPIC_API_KEY 随便填一个非空字符串就行因为真实密钥已经固化在代理的 DEEPSEEK_KEY 里了代理不会拿 Claude Code 传过来的 key 去请求 DeepSeek。改完之后重新运行 claude再发一句话测试。我这边的实测结果是第一句“你好”就能正常返回流式输出也恢复了正常。那一刻的感觉就像你终于找到了一个对的转换插头所有电器的电都通了。5. 跑通之后一个个冒出来的实战细节5.1 连续相同角色消息导致 400第一次跑通纯对话后我兴高采烈地开始正式用。结果没过几轮又碰到 400 invalid request。打开代理日志一看传给 DeepSeek 的 messages 数组里出现了连续两条 user 消息。原因是 Claude Code 在多轮对话的时候会插入大量系统上下文偶尔还会在同一轮里拼接多条用户输入这些消息在转成 Chat Completions 风格之后就会出现 role 连续重复。好在上面代码里的 merge 逻辑正是为了处理这个场景如果当前消息和上一条角色相同就拼进上一条而不是新增条目。这样既满足了 DeepSeek 对交替顺序的要求也不会丢失文本内容。这个处理建议原封不动保留不要嫌麻烦删掉。5.2 工具调用暂时失能哪些功能会变形这是我要重点提醒的地方上面那个代理只处理了 text 内容块Claude Code 在正常工作中非常依赖 tool_use。比如它要读写文件、执行终端命令、调用 MCP 工具这些能力全都是通过模型返回 tool_use 内容块来驱动的。当代理把 tool_use 块全部忽略之后Claude Code 就失去了“动手做事”的能力只剩纯文本聊天。比如你说“帮我看看当前目录有哪些文件并写个脚本来备份”它可能只会回答你“我建议你这样做”而不会真的去执行。这倒不能说配置失败了但至少功能打了折扣。要做到完整支持工具调用你需要在格式转换层里处理 tool_calls 和 tool_use 的双向映射在请求里把 Anthropic 格式的 tool_use 块转成 OpenAI 格式的 tool_calls在响应里把 OpenAI 的 tool_calls 再转回 Anthropic 的 tool_use 块。这一步比简单文本转换复杂不少属于进阶工作。我的建议是先把文本对话用稳定再按需补工具调用。我自己的实践是先通过一个中间思路绕开了这个问题把 DeepSeek 当作“会聊天的副驾驶”主驾驶依然是官方模型。这样既不会浪费模型能力也不会在关键开发任务上卡壳。5.3 模型名、max_tokens、temperature 的映射策略Claude Code 默认发过来的 model 字段是官方模型名比如 claude-sonnet-4-xxx这个值不能直接传给 DeepSeek所以我在代理里用 DEEPSEEK_MODEL 环境变量强制覆盖了模型名。这样最省心你只改代理的配置不用管 Claude Code 那边传什么名字。max_tokens 也值得留意。Claude Code 有时会传一个比较大的值而 DeepSeek 这边对单次输出上限有自己的约束传得超过上限可能直接报错。稳妥的做法是在代理层做个裁剪我上面用了 min(payload.get(max_tokens, 4096), 8000)意思是原始值最大不超过 8000。你如果用的是 deepseek-chat也可以再调小一些。temperature 则完全看场景。Claude Code 默认请求里不一定每次都带 temperature如果没有就不传如果带了就原样映射过去。不过 deepseek-reasoner 这类侧重推理的模型对 temperature 这类生成参数的容忍度可能不一样遇到参数相关的 400 报错时先试试把 temperature 在代理层去掉。5.4 代理日志与并发超时最后补一个运维向的建议本地代理一定要打日志。你不知道 Claude Code 什么时候会发来什么奇怪请求把请求体、响应状态码、耗时、错误信息全部打出来排查问题能省一半时间。另外 Claude Code 的某些操作会并发发起多个请求比如你在编辑器里选中一段代码让它解释同时它还在后台做代码补全分析。所以代理必须支持并发。我上面用的是异步框架加异步客户端天然支持并发线程模型不会互相阻塞。如果用的是同步框架并发一上来就会出现排队表现为“单个请求都不慢但整体卡得要命”。超时时间也建议设长一点因为 DeepSeek 在长上下文推理时首 token 返回可能需要一点时间。我把 httpx 的超时默认设成 180 秒实测基本够用。6. 不想维护代理的人的备选路径6.1 使用现成的 Anthropic 兼容网关如果你不想自己维护代理代码市面上也有一些现成的网关服务本身提供了 Claude Code 原生协议兼容的 /v1/messages 端点你在后台把模型映射成 DeepSeek 的 deepseek-chat然后直接把 ANTHROPIC_BASE_URL 指向它就行。这种方案的最大优点是省事配置十几分钟就能跑通不用关心协议转换细节。缺点也很明显你的每一次对话内容、代码片段、上下文都要经过第三方的服务数据安全上需要自己判断是否接受另外多了一层转发延迟一般会比本地代理高一些而且部分网关会按请求量额外收费。我的态度是如果只是尝鲜或者验证可行性用现成网关快速跑一把完全没问题如果打算长期高频使用特别是处理的是公司内部代码那还是建议用本地代理至少请求不出本机数据边界是可控的。6.2 用两套配置目录做模型隔离还有一个非常实用的技巧不要让 Claude Code 的全局配置里只有一个模型底座。你完全可以准备两套环境变量配置一套指向官方模型一套指向本地代理接 DeepSeek然后根据项目或任务切换。比如日常写代码使用官方模型跑脑暴、写文案、做代码 review 预审这类偏生成的任务就切换到 DeepSeek 配置。做法很简单给每个配置写一个独立的启动脚本或者按项目目录设置不同的环境变量文件。在哪个目录启动就用哪个模型。这样既能享受 DeepSeek 成本低的优势又不至于因为工具调用功能弱而影响主流程。6.3 我的建议这条建议说给准备长期用的人本地代理这层翻译逻辑迟早会从“能用”走向“好用”。你可以在代理层继续加功能比如模型名自动映射、请求日志落盘、多 key 轮询、限流控制甚至把多个模型的协议转换统一到这里。经过这次折腾我的看法变了Claude Code 接第三方模型的真正难点从来不是填一个 key而是协议翻译层是否足够稳、足够完整。能意识到这一层你的配置才算真正搭对了方向。最后再说一点个人体会。我在这个过程中踩得最深的一个坑就是对 401 和 404 的误判。前者让我一度怀疑是 key 被风控了后者让我反复检查网络结果都不是。现在的我遇到类似配置问题会先问一句请求到底发去哪了对面真能听懂吗把这个根本问题想明白很多看似玄学的报错都会变得特别直白。希望这篇记录也能帮你在配置 DeepSeek 的路上少走两小时弯路。
先说结论把 DeepSeek 接进 Claude Code不是简单地在环境变量里填一个 base_url 和一个 API key 就能完事的。我第一次这么干的时候Claude Code 回了我一个干干净净的 404当时我还以为是 key 填错了翻来覆去排查了两个小时最后才发现卡住我的根本不是 key而是协议。这篇文章把我从配置失败到最终跑通的完整思路、报错分析和参考实现都整理出来了给同样想在 Claude Code 里用 DeepSeek 的人一条可以照着走的路径。如果你已经在用 Claude Code想把默认模型换成 DeepSeek 试试或者因为成本原因想找一个替代模型那么这篇文章正好对你有用。1. 换模型这件事本质是让两个协议完成握手1.1 Claude Code 到底在用什么接口说话Claude Code 这个工具默认情况下只认一套自家生态的接口协议。它发请求的时候走的不是大家最常见的 Chat Completions 风格而是类似 /v1/messages 这个路径。请求体大概是这个样子curl -X POST https://api.example.com/v1/messages \ -H x-api-key: $KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-xxx, max_tokens: 4096, messages: [ { role: user, content: [ {type: text, text: 帮我写一个快速排序} ] } ] }注意看几个细节请求头里带了 anthropic-versioncontent 字段是一个数组数组里每个元素都有 type。响应更是完全不同的风格走的是 SSE 流式返回事件类型叫 message_start、content_block_delta、message_delta 这些。Claude Code 就是靠这些事件来识别“模型开始说话”“模型说了一段话”“模型说完了”的。这就是 Claude Code 出门必带的“原生协议”它在设计时只打算和讲同一套协议的模型服务通信。1.2 DeepSeek 的接口习惯DeepSeek 官方 API 走的是另一套风格路径是 /chat/completions请求体里 content 是普通字符串而不是块数组。同样是“帮我写一个快速排序”DeepSeek 那边长这样curl https://api.deepseek.com/chat/completions \ -H Authorization: Bearer $KEY \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [ {role: user, content: 帮我写一个快速排序} ], stream: false }两者字段长得有点像但细节完全不是一个体系。我列个表对比一下这是整个折腾过程中最核心的认知对比维度Claude Code 调用模型时DeepSeek API请求路径/v1/messages/chat/completions认证方式x-api-key 头Authorization: Bearer请求体 content 格式数组块结构字符串系统提示词独立 system 字段messages 数组里用 system 角色流式返回content_block_delta / message_deltachoices[0].delta.content工具调用格式tool_use 内容块tool_calls 数组这种感觉特别像一个从国内买的电器带到另一个国家用插头制式不一样插座对不上。你不是没电你是插不进去。1.3 base_url 并不是万能入口很多人包括一开始的我有一个误解觉得 Claude Code 既然支持配置 ANTHROPIC_BASE_URL那我只要把这个地址指向 DeepSeek 的服务器再把 key 换成 DeepSeek 的 key不就完事了吗不是的。这个 base_url 替换能力设计初衷是让你把请求转发到另一个同样讲 Claude Code 原声协议的网关服务而不是让你直接连一个讲完全不同方言的 API。你可以把 base_url 想象成快递的转运地址你能改的是“送到哪个仓库”但你没法让快递公司突然改说另一种语言来录单。所以直连 DeepSeek 的结果通常是路径 404、格式 400、或者认证 401五花八门但都不是 key 的问题。搞清楚这一点之后整个问题就从“配置问题”变成了“协议翻译问题”。2. 第一次直连的失败现场三个典型报错2.1 最容易发生的404 route not found我最开始的做法非常简单粗暴配置了三件套环境变量export ANTHROPIC_BASE_URLhttps://api.deepseek.com export ANTHROPIC_API_KEYsk-your-deepseek-key export ANTHROPIC_MODELdeepseek-chat然后满心欢喜地运行 claude结果还没开始对话就崩了报错内容大意是 404 Not Found后面还跟着一句 route not found。这个报错其实特别直白Claude Code 拿着它固定的 /v1/messages 路径去请求 https://api.deepseek.com/v1/messages而 DeepSeek 的服务器根本没有这个路由自然就 404 了。这个 404 和 key 一点关系都没有纯粹是 DeepSeek 服务器看了半天发现这个地址它压根不提供服务。2.2 被误导后的常见错400 invalid messages format在群里问了一圈之后有同行跟我说“你别把 base_url 直接指向根域名你加上 /v1 试试DeepSeek 的接口都是带 /v1 前缀的。”于是我把 ANTHROPIC_BASE_URL 改成 https://api.deepseek.com/v1再跑。这次错误变成了 400信息大体是 invalid request body 或者 message format not supported。原因很简单即便 DeepSeek 服务器收到了请求它期待的是 content 是字符串结果 Claude Code 发过来的是 content 数组里面还有 type 字段。两边字段对不上DeepSeek 自然就不认。这说明一个残酷的事实就算你千辛万苦把路径搞对了请求体格式还是对不上协议这层墙依然挡在中间。2.3 存在感很强的401 invalid api key还有一个报错非常容易遇到就是 401 Unauthorized。我在排查过程中一度把 key 放到各种位置试有几次是把 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 混着写或者把 base_url 不小心留成了默认值结果请求根本没发往 DeepSeek而是回到默认服务那边去做认证了人家一看这个 key 不是自己签发的直接给 401。这个错误给我的启发是认证错误不一定意味着 key 失效更多时候意味着请求落到了你没想到的服务器上。所以看到 401 的时候别急着换 key先确认请求到底发到哪儿去了。2.4 还有一类一直卡住或者静默失败除了直接报错之外还有一类比较隐蔽的现象Claude Code 界面看着像正常启动了但你一说话它就一直在转圈或者等很久之后告诉你“请求超时”。这类问题通常和流式响应格式有关Claude Code 在等它认识的 SSE 事件如果对面的服务返回的流式事件它不认得它就会一直等下去。这个问题我先埋个坑后面第五节会专门细说。3. 排查链路从“怀疑 key”到“确认协议不兼容”3.1 先用 DeepSeek 原生接口验证 key被三个报错轮番折磨之后我开始冷静下来把 Claude Code 暂时放一边先用最原始的方式验证 key 到底有没有问题。这一步其实很简单直接用 curl 调 DeepSeek 的 /chat/completions 接口发一个最简单的请求curl https://api.deepseek.com/chat/completions \ -H Authorization: Bearer $DEEPSEEK_KEY \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [{role: user, content: 11等于几}], stream: false }如果这一步能正常返回 choices 里的内容那就说明API key 是有效的网络是通的账户余额是够的。我把这个步骤叫“最小可用验证”。任何模型接进来第一步都应该先做这种事而不是直接丢到上层工具里猜。3.2 再用 Claude Code 原生风格请求同一个地址key 验证通过之后下一步就是故意让 Claude Code 风格请求去撞 DeepSeek 的接口。我用同样的 key但是换成 Claude Code 的请求格式curl -X POST https://api.deepseek.com/v1/messages \ -H x-api-key: $DEEPSEEK_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: deepseek-chat, max_tokens: 100, messages: [ {role: user, content: [{type: text, text: 11等于几}]} ] }结果毫无悬念不是 404 就是 400。这一步把问题彻底隔离出来了key 没问题问题出在“Claude Code 说一套话DeepSeek 听不懂”。我不再怀疑配置细节而是确定需要一个中间翻译层。3.3 抓客户端日志确认实际请求地址排查过程中我建议一定要开启 Claude Code 的调试日志或者用 verbose 模式启动。通过日志可以看到它真正发出去的 URL 是什么、请求体是什么、响应又是什么。很多“玄学报错”在日志面前都会原形毕露比如你以为请求发到了 DeepSeek其实它发去了默认地址你以为传的是正确的 key其实读的是另一个环境变量的值。我把这三步走完以后问题的边界就非常清楚了key 是好的网络是通的只是 Claude Code 和 DeepSeek 之间缺一个协议翻译器。接下来的工作就一句话把 /v1/messages 的请求翻译成 /chat/completions 的请求再把响应翻译回去。4. 解决本地起一个只有几百行的协议转换代理4.1 为什么自建而不是改客户端有人会问能不能直接改 Claude Code 的源码或者通过插件强制它用 DeepSeek 的原生接口我的回答是不要这么做。Claude Code 迭代很快每次升级都会覆盖你的改动而且很多逻辑是内部封装好的你改了也不一定能稳定工作。与其研究怎么让客户端“迁就”DeepSeek不如在客户端和服务之间插一个本地小代理让代理两头各说各话。这个方案的好处是对 Claude Code 来说它看到的是一个“讲原声协议的模型服务”完全不知道背后发生了什么对 DeepSeek 来说它看到的是一个“用 Chat Completions 风格调它的普通客户端”。两边都不需要改动我只维护中间这层翻译而且这层翻译是可重复复用的以后想接 DeepSeek 的任何模型都方便。4.2 消息格式转换的代码实现我用的是 Python 的 FastAPI 框架加上 httpx 做异步转发。选择 Python 是因为这类文本转换代码写起来快异步流式支持也成熟。代码不复杂核心就三块接收 Claude Code 格式请求、转换成 DeepSeek 格式、把响应流式翻译回去。先建一个 proxy.py下面是参考实现import json import os import httpx from fastapi import FastAPI, Request from fastapi.responses import JSONResponse, StreamingResponse app FastAPI() DEEPSEEK_BASE os.getenv(DEEPSEEK_BASE, https://api.deepseek.com) DEEPSEEK_KEY os.getenv(DEEPSEEK_KEY, ) MODEL os.getenv(DEEPSEEK_MODEL, deepseek-chat) def convert_content(content): if isinstance(content, str): return content if isinstance(content, list): parts [] for block in content: if block.get(type) text and block.get(text): parts.append(block[text]) return \n.join(parts) if parts else return def convert_messages(payload): messages [] if payload.get(system): messages.append({role: system, content: payload[system]}) for msg in payload.get(messages, []): role msg.get(role, user) text convert_content(msg.get(content)) if messages and messages[-1][role] role: merged (messages[-1][content] \n text).strip() messages[-1][content] merged else: messages.append({role: role, content: text}) return messages def build_openai_payload(payload): openai_payload { model: MODEL, messages: convert_messages(payload), stream: True, max_tokens: min(payload.get(max_tokens, 4096), 8000), } if payload.get(temperature) is not None: openai_payload[temperature] payload[temperature] return openai_payload def sse_event(event, data): return fevent: {event}\ndata: {json.dumps(data)}\n\n async def event_stream(resp): # 告诉 Claude Code 事件开始 yield sse_event(message_start, { type: message_start, message: { id: msg_local_1, type: message, role: assistant, model: MODEL, content: [], stop_reason: None, stop_sequence: None, }, }) yield sse_event(content_block_start, { type: content_block_start, index: 0, content_block: {type: text, text: }, }) async for line in resp.aiter_lines(): if not line.startswith(data:): continue data line[len(data:):].strip() if not data or data [DONE]: break try: chunk json.loads(data) except Exception: continue choices chunk.get(choices, []) if not choices: continue delta choices[0].get(delta, {}) text delta.get(content) if not text: continue yield sse_event(content_block_delta, { type: content_block_delta, index: 0, delta: {type: text_delta, text: text}, }) # 结束事件Claude Code 靠这个判断任务完成 yield sse_event(message_delta, { type: message_delta, delta: {stop_reason: end_turn, stop_sequence: None}, }) yield sse_event(content_block_stop, {type: content_block_stop, index: 0}) yield sse_event(message_stop, {type: message_stop}) app.post(/v1/messages) async def proxy_messages(request: Request): payload await request.json() openai_payload build_openai_payload(payload) headers { Authorization: fBearer {DEEPSEEK_KEY}, Content-Type: application/json, } async with httpx.AsyncClient(timeout180) as client: req client.build_request( POST, f{DEEPSEEK_BASE}/chat/completions, headersheaders, jsonopenai_payload, ) resp await client.send(req, streamTrue) if resp.status_code ! 200: body await resp.aread() return JSONResponse( status_coderesp.status_code, content{type: error, message: body.decode()}, ) return StreamingResponse(event_stream(resp), media_typetext/event-stream)这段代码里有个细节值得单独说convert_messages 里我把连续相同 role 的消息合并了。这是因为 Claude Code 的历史对话里经常出现连续两条 user 消息或者连续两条 assistant 消息而 DeepSeek 这类服务对消息交替顺序要求比较严格连续相同角色通常会被拒。这个坑我在第五节还会再提但代码里先处理掉了。4.3 SSE 事件流怎么“翻译”才不会让客户端转圈很多人写转换代理的时候只想着“把请求体转一下”却忽略了响应流。实际上 Claude Code 对响应流的事件类型非常敏感它不认 OpenAI 风格的 choices[0].delta.content它只认 content_block_delta 这类事件。我在这段代码里补全了完整的事件序列message_start 表示开始content_block_start 表示第一个内容块中间反复发 content_block_delta 携带文本增量最后发 message_delta 设置 stop_reason 为 end_turn再发 content_block_stop 和 message_stop 告诉客户端“我说完了”。这个顺序不是可有可无的。你哪怕少了一个 content_block_stopClaude Code 都可能认为这一次回答还没结束表现为对话框一直在转圈最后超时。这个知识点是我调试时最花时间的部分先放这里提醒你后面还会展开。4.4 启动代理并回填环境变量代码保存为 proxy.py 之后先设置代理侧的密钥export DEEPSEEK_KEYsk-your-deepseek-key export DEEPSEEK_MODELdeepseek-chat然后启动服务uvicorn proxy:app --host 127.0.0.1 --port 8080接着回到 Claude Code 那边把环境变量改成指向本地代理export ANTHROPIC_BASE_URLhttp://127.0.0.1:8080 export ANTHROPIC_API_KEYsk-local-proxy-placeholder这里 ANTHROPIC_API_KEY 随便填一个非空字符串就行因为真实密钥已经固化在代理的 DEEPSEEK_KEY 里了代理不会拿 Claude Code 传过来的 key 去请求 DeepSeek。改完之后重新运行 claude再发一句话测试。我这边的实测结果是第一句“你好”就能正常返回流式输出也恢复了正常。那一刻的感觉就像你终于找到了一个对的转换插头所有电器的电都通了。5. 跑通之后一个个冒出来的实战细节5.1 连续相同角色消息导致 400第一次跑通纯对话后我兴高采烈地开始正式用。结果没过几轮又碰到 400 invalid request。打开代理日志一看传给 DeepSeek 的 messages 数组里出现了连续两条 user 消息。原因是 Claude Code 在多轮对话的时候会插入大量系统上下文偶尔还会在同一轮里拼接多条用户输入这些消息在转成 Chat Completions 风格之后就会出现 role 连续重复。好在上面代码里的 merge 逻辑正是为了处理这个场景如果当前消息和上一条角色相同就拼进上一条而不是新增条目。这样既满足了 DeepSeek 对交替顺序的要求也不会丢失文本内容。这个处理建议原封不动保留不要嫌麻烦删掉。5.2 工具调用暂时失能哪些功能会变形这是我要重点提醒的地方上面那个代理只处理了 text 内容块Claude Code 在正常工作中非常依赖 tool_use。比如它要读写文件、执行终端命令、调用 MCP 工具这些能力全都是通过模型返回 tool_use 内容块来驱动的。当代理把 tool_use 块全部忽略之后Claude Code 就失去了“动手做事”的能力只剩纯文本聊天。比如你说“帮我看看当前目录有哪些文件并写个脚本来备份”它可能只会回答你“我建议你这样做”而不会真的去执行。这倒不能说配置失败了但至少功能打了折扣。要做到完整支持工具调用你需要在格式转换层里处理 tool_calls 和 tool_use 的双向映射在请求里把 Anthropic 格式的 tool_use 块转成 OpenAI 格式的 tool_calls在响应里把 OpenAI 的 tool_calls 再转回 Anthropic 的 tool_use 块。这一步比简单文本转换复杂不少属于进阶工作。我的建议是先把文本对话用稳定再按需补工具调用。我自己的实践是先通过一个中间思路绕开了这个问题把 DeepSeek 当作“会聊天的副驾驶”主驾驶依然是官方模型。这样既不会浪费模型能力也不会在关键开发任务上卡壳。5.3 模型名、max_tokens、temperature 的映射策略Claude Code 默认发过来的 model 字段是官方模型名比如 claude-sonnet-4-xxx这个值不能直接传给 DeepSeek所以我在代理里用 DEEPSEEK_MODEL 环境变量强制覆盖了模型名。这样最省心你只改代理的配置不用管 Claude Code 那边传什么名字。max_tokens 也值得留意。Claude Code 有时会传一个比较大的值而 DeepSeek 这边对单次输出上限有自己的约束传得超过上限可能直接报错。稳妥的做法是在代理层做个裁剪我上面用了 min(payload.get(max_tokens, 4096), 8000)意思是原始值最大不超过 8000。你如果用的是 deepseek-chat也可以再调小一些。temperature 则完全看场景。Claude Code 默认请求里不一定每次都带 temperature如果没有就不传如果带了就原样映射过去。不过 deepseek-reasoner 这类侧重推理的模型对 temperature 这类生成参数的容忍度可能不一样遇到参数相关的 400 报错时先试试把 temperature 在代理层去掉。5.4 代理日志与并发超时最后补一个运维向的建议本地代理一定要打日志。你不知道 Claude Code 什么时候会发来什么奇怪请求把请求体、响应状态码、耗时、错误信息全部打出来排查问题能省一半时间。另外 Claude Code 的某些操作会并发发起多个请求比如你在编辑器里选中一段代码让它解释同时它还在后台做代码补全分析。所以代理必须支持并发。我上面用的是异步框架加异步客户端天然支持并发线程模型不会互相阻塞。如果用的是同步框架并发一上来就会出现排队表现为“单个请求都不慢但整体卡得要命”。超时时间也建议设长一点因为 DeepSeek 在长上下文推理时首 token 返回可能需要一点时间。我把 httpx 的超时默认设成 180 秒实测基本够用。6. 不想维护代理的人的备选路径6.1 使用现成的 Anthropic 兼容网关如果你不想自己维护代理代码市面上也有一些现成的网关服务本身提供了 Claude Code 原生协议兼容的 /v1/messages 端点你在后台把模型映射成 DeepSeek 的 deepseek-chat然后直接把 ANTHROPIC_BASE_URL 指向它就行。这种方案的最大优点是省事配置十几分钟就能跑通不用关心协议转换细节。缺点也很明显你的每一次对话内容、代码片段、上下文都要经过第三方的服务数据安全上需要自己判断是否接受另外多了一层转发延迟一般会比本地代理高一些而且部分网关会按请求量额外收费。我的态度是如果只是尝鲜或者验证可行性用现成网关快速跑一把完全没问题如果打算长期高频使用特别是处理的是公司内部代码那还是建议用本地代理至少请求不出本机数据边界是可控的。6.2 用两套配置目录做模型隔离还有一个非常实用的技巧不要让 Claude Code 的全局配置里只有一个模型底座。你完全可以准备两套环境变量配置一套指向官方模型一套指向本地代理接 DeepSeek然后根据项目或任务切换。比如日常写代码使用官方模型跑脑暴、写文案、做代码 review 预审这类偏生成的任务就切换到 DeepSeek 配置。做法很简单给每个配置写一个独立的启动脚本或者按项目目录设置不同的环境变量文件。在哪个目录启动就用哪个模型。这样既能享受 DeepSeek 成本低的优势又不至于因为工具调用功能弱而影响主流程。6.3 我的建议这条建议说给准备长期用的人本地代理这层翻译逻辑迟早会从“能用”走向“好用”。你可以在代理层继续加功能比如模型名自动映射、请求日志落盘、多 key 轮询、限流控制甚至把多个模型的协议转换统一到这里。经过这次折腾我的看法变了Claude Code 接第三方模型的真正难点从来不是填一个 key而是协议翻译层是否足够稳、足够完整。能意识到这一层你的配置才算真正搭对了方向。最后再说一点个人体会。我在这个过程中踩得最深的一个坑就是对 401 和 404 的误判。前者让我一度怀疑是 key 被风控了后者让我反复检查网络结果都不是。现在的我遇到类似配置问题会先问一句请求到底发去哪了对面真能听懂吗把这个根本问题想明白很多看似玄学的报错都会变得特别直白。希望这篇记录也能帮你在配置 DeepSeek 的路上少走两小时弯路。
