很多人第一次在 Windows 上装 Claude Code装完之后兴冲冲地敲命令结果第一句话就卡住了要么是终端报一堆看不懂的路径错误要么是请求发出去之后一直转圈要么干脆返回一个 401 或者 404。问题往往不在于 Claude Code 本身难装而在于一个被绝大多数教程一笔带过的关键事实——Claude Code 说的是 Anthropic 的 Messages 协议方言而 DeepSeek 的开放接口说的是 OpenAI 的 Chat Completions 方言两者之间天生缺了一层翻译。这篇内容就是我把自己在 Windows 上把这条链路完整跑通的整个过程拆开来讲从 Node 环境底座怎么铺到 Claude Code 怎么装怎么验再到中间那层协议转换网关怎么写怎么配最后把实测中踩到的六类故障按照排查顺序一个个摆出来。适合两类人看一类是想省钱、想用国产模型的能力又不想放弃 Claude Code 这套终端工作流的人另一类是已经把工具装上了但死活连不通、正在怀疑人生的朋友。1. 先把链路想清楚Claude Code 与 DeepSeek 之间缺的那一层动手之前不把这条链路的拓扑画清楚后面一定会陷入“改了环境变量没反应、换了密钥还是报错”的循环里。我见过太多人上来就复制粘贴一串setx命令然后发现报错信息跟教程对不上就彻底蒙了。所以这一节先把“谁跟谁说话、说的话长什么样”这件事讲透。1.1 两个工具各自说哪种“方言”Claude Code 本质是一个跑在终端里的客户端程序它的工作方式是读取你本地项目的文件、理解你的自然语言指令、然后通过 HTTP 请求把上下文发给一个远端的模型服务拿到回复后再决定要不要改文件、跑命令。它对外发请求时用的是一套固定的报文结构顶层有model、max_tokens、system、messages、tools、stream这些字段其中system是一个独立的顶层字段messages里的内容块content block是数组形式每个块带type标记比如{type:text,text:...}。这套结构是 Anthropic Messages API 的规范。DeepSeek 提供的开放接口则是 OpenAI 风格的请求体里messages是一个扁平数组每条消息的content直接就是字符串系统提示要作为一条role: system的消息塞进这个数组里工具调用走的是tools加function嵌套的写法。两套结构的字段名有重合但嵌套层级和语义完全不同。这两套东西长得像、名字像、连messages这个键名都一样所以很多人会误以为改个地址就能通。实际上字段结构的差异只是第一层第二层是流式响应的数据块格式不一样——一边是content_block_delta事件一边是chat.completion.chunk增量第三层是工具调用的参数拼装方式不一样。这三层差异叠加起来就是“直连必然失败”的根因。1.2 为什么直连一定失败一个具体的报错推演我把最常见的直连尝试复现一遍你会看得很清楚。假设你在 Windows 的 PowerShell 里设了两个变量把请求地址指向 DeepSeek 的接口把密钥填进去然后启动 Claude Code 发一句话。会发生什么第一步Claude Code 会向这个地址发一个 POST 请求路径是/v1/messages。DeepSeek 那边对外暴露的对话路径是/chat/completions于是你收到一个 404报错信息大概是路径不存在。这时候很多人会去改基础地址加个/v1或者去掉/v1结果陷入路径拼接的泥潭客户端自己会补/v1/messages你在基础地址里再加一段/v1最后拼出来一个/v1/v1/messages。第二步假设你侥幸把路径对上了Claude Code 发过去的报文体里有system顶层字段和数组化的content。DeepSeek 的接口解析器看到messages数组里某条消息的content是个数组而不是字符串通常会直接报参数校验失败或者更糟——静默忽略返回一个空回复让你以为是模型在偷懒。第三步就算前面都过了流式返回的数据块结构对不上Claude Code 的解析器认不出这些事件的类型界面就卡在那里转圈直到超时。提示判断自己是不是卡在“协议不匹配”而不是“网络不通”有个很简单的办法——看错误码。401/403 是身份问题404 是路径问题400 配上一堆字段名基本就是报文结构问题。这三种错误背后的处理动作完全不同别混着改。1.3 三种可选架构的取舍对比认识到缺一层转换之后方案其实有三条路各有各的代价我把自己试过的三种列成表你可以按自己的场景挑。方案做法优点代价适合谁A. 自建轻量网关本地跑一个小服务收 Anthropic 格式、转 OpenAI 格式、转发给 DeepSeek完全可控改字段方便日志清晰出问题能一眼看到原始报文需要自己写代码工具调用那部分要处理想搞明白原理、需要长期用的人B. 用现成的转换中间件装一个开源的协议转换服务配置化启动上手快工具调用、流式大多已经处理好配置文件字段多版本更新快遇到问题要读源码只想尽快跑通、不想写代码的人C. 直接用原生兼容层找那种本身就同时支持两种协议的服务最少组件灵活性差模型映射、超时、重试都不好细调临时试用我个人的选择是 A 起步、稳定之后转 B。原因很实际A 方案在你第一次跑通的时候能让你看见完整的请求报文和响应报文这对后面排查各种稀奇古怪的问题价值极大等链路天天在用、不想再维护代码了再换成配置化的中间件。这里要特别提醒一句不管你选哪条路那个转换层最好只监听本机不要暴露到公网。它手里握着你的密钥暴露出去就是给自己挖坑。2. Windows 侧的环境底座Node、终端与 Git Bash 三件套链路想清楚了接下来是环境。Windows 上跑这类终端工具环境问题占了故障总量的一半以上而且表现出很强的欺骗性——报错信息指向的地方往往不是真正出问题的地方。2.1 Node 版本与 npm 全局目录的坑Claude Code 是通过 npm 分发的所以第一步是 Node。版本上不要图省事用系统里那个几年前装的旧版本至少要用到 18 以上的 LTS 线条件允许直接上 20 或 22 的 LTS。判断办法很简单开个终端敲node -v看看输出的主版本号。真正的坑在全局安装目录。Windows 上 npm 默认把全局包装到用户目录下的AppData\Roaming\npm这个路径里带空格的可能性不大但如果你的用户名是中文或者你把 npm 的前缀改到过某个带空格的盘符路径后面执行命令时就会遇到各种“找不到命令”或者“路径解析失败”。我的做法是先把全局前缀查出来看一眼npm config get prefix npm root -g如果输出的路径里含空格或中文就换一个干净的位置比如D:\dev\npm-global改完记得把这个路径加进系统的 PATH 环境变量然后重开一个终端。这一步做完再执行npm install -g anthropic-ai/claude-code。安装过程中如果卡在某个包上不动先别急着怀疑网络八成是 npm 的缓存目录权限问题。清理一下缓存重来npm cache clean --force。安装完成后敲claude --version能打印出版本号才算过第一关。注意安装完一定要新开一个终端窗口再验证。已经打开的终端读的是启动时的 PATH 快照不会感知到新加的路径这个细节每年都要坑掉一批人。2.2 终端选择PowerShell 还是 Git BashClaude Code 在 Windows 上对终端环境是有偏好的。它内部会用到一些类 Unix 的命令来做文件检索和内容匹配所以最省心的组合是装一个 Git for Windows然后用它自带的 Git Bash 来跑。Git Bash 里那些grep、find、ls的行为跟工具预期一致出问题的概率最低。PowerShell 能不能用能新版已经做了不少适配但你会遇到两类额外麻烦一是执行策略某些脚本会被拦下来二是路径分隔符和引号转义规则不一样同样的参数在 PowerShell 里会被吃掉一部分。如果你确实想在 PowerShell 里用先把执行策略调一下Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned我自己的习惯是双轨制日常用 Windows Terminal 开一个 Git Bash 标签页专门跑 Claude Code需要做系统层面的操作再切 PowerShell。这样两边的优势都能拿到也不用在引号转义上反复消耗精力。还有个小细节值得提一下Git Bash 里中文输入法的候选框位置有时会飘输入中文指令时容易误触。解决办法不是改工具而是习惯上先用英文写指令、需要中文描述的地方用引号包起来减少切换频率。2.3 编码与换行符这两个隐形杀手这两个问题平时不显山不露水一旦发作就是“功能全对但结果全错”的类型非常难受。编码问题Windows 默认的控制台代码页可能不是 UTF-8Claude Code 读到中文文件内容时会变成一堆问号或者乱码然后它基于乱码去改文件结果就可想而知了。在 Git Bash 里通常还好在 cmd 里就必须先执行chcp 65001。更彻底的办法是在系统的“区域设置”里把“Beta 版使用 Unicode UTF-8 提供全球语言支持”打开但这会影响一些老软件的显示属于全局改动谨慎一点。换行符问题Git 默认可能把行尾转成 CRLF而工具生成的文件用 LF。这会导致两件事——一是每次 Claude Code 改完文件git diff显示整个文件全变了看起来像改了几百行其实只改了一行二是某些解析器对 CRLF 敏感报出莫名其妙的语法错误。解决办法是在项目根目录放一个.gitattributes* textauto eollf这两条设置做完后面很多“玄学问题”根本不会出现。我宁愿在开头花二十分钟把这些地基铺平也不想在深夜对着一个乱码的报错信息猜三个小时。3. 安装 Claude Code 并验证它真的能跑环境底座铺好之后安装本身其实很快真正考验耐心的是“验证”这一步。我见过太多人装完就急着接 DeepSeek结果根本不知道原生状态下工具能不能跑出问题了就分不清是安装的问题还是协议的问题。所以务必先把原生这条链路验通——哪怕你没有原生的密钥也要用“能发出请求、能收到明确错误”作为通过的标志。3.1 安装命令与首次启动的交互全局安装完成后第一次在项目目录里敲claude会进入一个交互式的初始化流程。它会问你几个问题包括主题偏好、是否信任当前目录等等。这里有两个点要注意。第一是“信任目录”这个环节。Claude Code 会读取和修改当前工作目录下的文件所以它会要求你确认信任。如果你选错了、或者在一个不合适的目录里启动了它后面它可能会拒绝执行某些操作表现出来像是权限不足。正确做法是先cd到你真正要干活的项目根目录再启动。不要在用户主目录或者盘符根目录启动那等于把整个磁盘交给它。第二是首次启动会创建一个配置目录在 Windows 上是用户目录下的.claude文件夹。里面会有settings.json、会话记录、以及可能的项目级配置。这个目录后面我们会反复用到先记住它的位置ls -la ~/.claude如果你之前装过旧版本、想彻底重来删掉这个目录里除settings.json之外的内容基本就能回到干净状态。但删之前把settings.json备份一下里面可能有你调过的配置。3.2 用 --version 与最小对话确认链路验证分三层一层比一层严格。第一层claude --version能打印版本号。这只说明可执行文件在 PATH 里别的什么都说明不了。第二层claude --help能正常输出帮助信息。这一步能验证它的依赖是否完整——如果缺了什么运行时的库通常在这一步就会崩给你看。第三层也是最关键的一层在一个空目录里发一句最简单的话看它能不能走完整个请求-响应循环。这时候如果还没配置任何模型服务你会收到一个身份验证相关的错误。收到这个错误其实是好事说明安装、启动、报文组装、网络发送这几个环节都是通的问题只在最后一步的身份。这就是我前面说的“能收到明确错误即通过”的含义。如果第三层卡在转圈、没有任何输出那说明问题出在更前面要么是终端环境有问题要么是某个依赖命令缺失。这时候去看它的详细日志通常会在.claude目录下或者终端里打印出具体的失败原因。3.3 权限模式与 .claude 目录结构Claude Code 有一套权限模式决定了它能不能自动改文件、能不能自动执行命令。默认模式下每次改文件或跑命令都会问你一次这在刚开始用的时候很容易让人烦但它其实是保护机制。模式大致分几档最保守的一档只读不改中间一档允许自动改文件但执行命令还是要确认再往上一档是每次操作都确认但可以批量批准最激进的一档是完全放行。我的建议是日常开发用中间那档跑批处理或者明确的重复性任务时临时放宽做完立刻调回来。完全放行这一档只在你能确保当前目录里没有重要文件、且任务边界清晰的情况下用别养成习惯。目录结构方面除了用户级的~/.claude项目根目录下还可以放一个CLAUDE.md这是给它看的项目说明。还有.claude/settings.json可以做项目级配置覆盖。这两个东西后面在第七节会详细展开先知道它们存在就行。4. 搭一层协议转换网关把 Anthropic 请求翻成 OpenAI 格式这是整篇内容里技术含量最高的一节也是把“装上了”变成“能用了”的分水岭。我用 Node 写一个最小可用的转换服务来讲因为它跟 Claude Code 用的是同一个运行时你不用再装一套 Python 环境部署成本最低。4.1 网关要做哪几件事在写代码之前先列清楚职责不然很容易写成一坨。第一件事路径改写。客户端发过来的是/v1/messages上游要的是/v1/chat/completions网关必须做这个映射。第二件事报文结构转换。把顶层的system字段抽出来变成messages数组里的第一条role: system消息把数组形式的content块拍平成字符串把max_tokens做上限裁剪。第三件事工具定义转换。客户端传的tools是 Anthropic 的格式每个工具有name、description、input_schema上游要的是{type:function,function:{name:...,description:...,parameters:...}}。这一层不做模型就没法调用工具表现出来就是“它只会聊天不会改文件”。第四件事流式响应转换。上游返回的是data: {...}的增量块网关要把choices[0].delta.content提取出来重新包装成客户端认识的事件序列。第五件事反向的工具调用转换。模型返回的工具调用结果要重新包装成 Anthropic 的tool_use块。这五件事里前两件是跑通对话的最小集合后三件是让它真正好用的必要条件。我建议先做前两件把链路打通看到模型回复了再补后三件。这种分阶段的方式比一次性写完然后调试一整天要高效得多。4.2 部署与配置文件逐字段说明新建一个目录初始化项目装一个依赖mkdir api-gateway cd api-gateway npm init -y npm install express然后写一个最小的服务骨架// server.js import express from express; const app express(); app.use(express.json({ limit: 32mb })); const UPSTREAM https://api.deepseek.com/v1/chat/completions; const API_KEY process.env.DEEPSEEK_API_KEY; function convert(body) { const messages []; if (body.system) { const sys Array.isArray(body.system) ? body.system.map(s s.text || ).join(\n) : String(body.system); if (sys.trim()) messages.push({ role: system, content: sys }); } for (const m of body.messages || []) { if (typeof m.content string) { messages.push({ role: m.role, content: m.content }); } else if (Array.isArray(m.content)) { const text m.content .filter(c c.type text) .map(c c.text) .join(\n); messages.push({ role: m.role, content: text }); } } return { model: deepseek-chat, messages, max_tokens: Math.min(body.max_tokens || 4096, 8192), stream: Boolean(body.stream) }; } app.post(/v1/messages, async (req, res) { const payload convert(req.body); const upstream await fetch(UPSTREAM, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${API_KEY} }, body: JSON.stringify(payload) }); if (!payload.stream) { const data await upstream.json(); const text data.choices?.[0]?.message?.content ?? ; return res.json({ id: msg_local, type: message, role: assistant, content: [{ type: text, text }], stop_reason: end_turn }); } // 流式部分见下文说明 res.setHeader(Content-Type, text/event-stream); res.setHeader(Cache-Control, no-cache); // 这里做增量转译把上游 delta 重新包装成客户端事件 }); app.listen(8787, 127.0.0.1, () { console.log(gateway on http://127.0.0.1:8787); });启动时把密钥作为环境变量传进去注意不要把它写死在代码里更不要提交到任何版本库DEEPSEEK_API_KEY你的密钥 node server.js几个字段的取舍理由说清楚max_tokens我做了 8192 的裁剪因为客户端有时候会传一个很大的值上游会直接拒绝model我固定成对话模型后面 4.3 会讲怎么按需切换监听地址写死127.0.0.1而不是默认的所有网卡是为了避免同局域网里其他机器访问到它。流式那部分我只留了注释这里给个实现思路读上游的响应流按行切分每行去掉data:前缀遇到[DONE]就结束解析出的 JSON 里取choices[0].delta.content如果有内容就往外写一个event: content_block_delta加上对应的数据块最后补一个message_stop事件。这一块要小心半包问题——一行数据可能被拆到两次 chunk 里所以需要一个缓冲区攒够完整的行再处理。4.3 模型映射表请求里的模型名怎么落到 deepseek-chat客户端发过来的model字段可能是它自己的一套命名你需要一张映射表把它落到上游认识的模型名上。客户端传入的意图映射到上游说明主力对话与代码生成deepseek-chat通用对话模型日常改代码够用需要长链推理的复杂任务deepseek-reasoner会输出思考过程耗时更长、计费更高小模型用于摘要、标题生成deepseek-chat上游没有对应的小模型只能复用主力模型未知模型名deepseek-chat兜底策略避免因为名字不认识直接报错这张表看着简单但有两个坑要提。第一个是“大小模型分离”这一行Claude Code 内部有一类调用是用来做轻量任务的比如给会话起标题、判断上下文是否需要压缩这类调用如果也走主力模型你的账单会莫名其妙地多出一截。虽然上游没有小模型可用但你可以在网关里对这类请求做限制——比如把max_tokens压到很小或者干脆返回一个固定内容不真的发请求。第二个坑是推理模型的行为差异。它返回的报文里除了正文还有一段推理内容如果你不做处理直接透传客户端可能会把它当成正文显示出来看起来像是模型在自言自语。网关里要把这部分剥离掉只保留最终答案。5. 环境变量与 settings.json让配置可复现、可切换前面把网关跑起来了现在是让 Claude Code 指向它。这一步看起来只是设两个环境变量的事但设在哪里、怎么设直接决定了你后面是顺畅还是天天折腾。5.1 setx 与 $env: 的区别和副作用Windows 上设环境变量有几种方式行为完全不同。setx是持久化写入用户或系统环境变量写完之后只对新开的进程生效当前这个终端窗口读不到。很多人敲完setx就在同一个窗口里启动工具发现没生效然后又敲一遍折腾半天。正确姿势是setx之后关掉窗口重开。$env:NAME value是 PowerShell 里的临时设置只影响当前会话窗口一关就没了。这个适合调试快速试一个值验证通过再落成持久化。在 Git Bash 里则是export NAMEvalue同样是会话级。我的习惯是所有调试阶段用会话级变量试通了再统一写进settings.json见 5.2尽量不用setx。原因是setx会把值散落在系统的各个角落时间一长你自己都不记得改过哪些排查问题时全是干扰项。需要设的变量主要有这几个export ANTHROPIC_BASE_URLhttp://127.0.0.1:8787 export ANTHROPIC_AUTH_TOKENlocal-any-string export ANTHROPIC_MODELdeepseek-chatANTHROPIC_BASE_URL指向本地网关。ANTHROPIC_AUTH_TOKEN这里填什么都行因为真正的密钥在网关那一侧客户端这一侧只是需要一个非空值来通过校验。这一点很多人搞错了把真密钥填在这里然后又在网关里填一遍出问题时根本分不清是哪边的密钥错了。注意基础地址不要带/v1客户端自己会拼。带了就会变成/v1/v1/messages得到 404。5.2 用 settings.json 固化配置会话级变量适合调试但每次开新窗口都要重新设一遍很烦。持久化的正确位置是~/.claude/settings.json里的env字段。{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:8787, ANTHROPIC_AUTH_TOKEN: local-any-string, ANTHROPIC_MODEL: deepseek-chat, API_TIMEOUT_MS: 600000, CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192 } }这几个字段的作用值得单独说一下。API_TIMEOUT_MS是请求超时默认值不大接国产模型时如果遇到长任务很容易在中途被掐断设成十分钟比较稳妥。CLAUDE_CODE_MAX_OUTPUT_TOKENS控制单次回复的最大输出长度设太小会导致生成长文件时被截断设太大又会让上游拒绝8192 是个比较安全的中间值。改完这个文件需要重启客户端才生效。另外注意 JSON 不能有注释、不能有尾逗号这是最常见的低级错误——一个多余的逗号会让整个配置文件被静默忽略你会以为设置没生效其实是文件根本没被读进去。项目级的配置放在项目根目录的.claude/settings.json它的优先级高于用户级。这个机制非常有用你可以在某个特定项目里覆盖模型或者超时而不影响其他项目。5.3 多套配置切换的目录技巧用久了你会发现不同场景需要不同配置。写业务代码希望用快一点的模型啃复杂算法希望用推理模型做文档整理又希望限制输出长度省钱。每次都手动改配置文件太笨了。我的做法是准备几个配置文件然后做一个切换脚本。在用户目录下放settings.deepseek-chat.json、settings.deepseek-reasoner.json切换时用一行命令覆盖过去cp ~/.claude/settings.deepseek-reasoner.json ~/.claude/settings.json再写个 alias 或者小脚本包一层敲一个短命令就切完了。这个技巧看着土但它带来的实际收益是你不会因为懒得改配置而一直用错模型不会因为切换成本高而把该省钱的地方也用了贵模型。还有一层更细的控制在网关侧。你的网关其实可以根据请求里的某些特征做路由比如请求里带的模型名、或者消息长度、或者是否包含工具定义来决定转发到哪个上游模型。这样客户端完全不用改配置路由逻辑集中在网关一处维护后期调整起来方便得多。我就是这么干的客户端永远只写一个模型名网关内部按消息长度和是否带工具做分发。6. 实测中遇到的六类故障与排查顺序这一节是我踩过的坑的完整记录。我会按“从外到内”的顺序排因为排查的核心原则就是先确认最外层通不通再往里一层层剥千万别一上来就怀疑最里层的代码逻辑。6.1 401/403先分清是密钥问题还是协议问题看到 401 或 403第一反应是密钥错。但接了网关之后这里有两个密钥客户端到网关的、网关到上游的。必须分清是哪一段出的问题。排查动作看网关的日志。如果网关压根没收到请求说明问题在客户端到网关这一段检查ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN有没有生效。如果网关收到了请求但转发后返回 401那就是上游密钥的问题检查网关进程启动时的环境变量有没有正确注入。一个很容易忽略的点密钥首尾有没有多余的空格或换行。从网页上复制密钥时经常会把换行符一起带进去肉眼完全看不出来但校验一定失败。我现在的习惯是复制完先粘到记事本里看一眼长度或者用echo $KEY | wc -c数一下字符数对不对。6.2 404 与 /v1 路径的重复拼接前面提过一次但值得再强调因为它出现频率太高了。客户端的规则是基础地址 /v1/messages。所以你设的基础地址实际请求路径结果http://127.0.0.1:8787/v1/messages正确http://127.0.0.1:8787//v1/messages通常正确http://127.0.0.1:8787/v1/v1/v1/messages404http://127.0.0.1:8787/api/api/v1/messages看你网关怎么路由排查手段很直接在网关里把收到的req.path打印出来一眼就能看到真实路径是什么不用猜。6.3 卡在转圈不动超时与流式响应这个症状最折磨人因为没有任何错误信息就是一个光标在那闪。原因通常有三个。第一网关的流式转换没写对上游数据来了但没往客户端写或者写的事件格式客户端不认识客户端就一直等一个永远不会来的结束信号。第二超时设置太短长任务被掐断。第三上游返回了内容但被网关吞掉了比如解析 JSON 时抛了个异常又被 catch 住忽略了。排查顺序先在网关里加日志把上游返回的每个数据块原样打印出来确认数据确实到了网关。再确认网关往外写的事件格式。最后确认客户端有没有收到结束事件。这三步做完问题基本就定位了。我遇到过一次特别隐蔽的网关往外写流的时候没有正确设置响应头导致某些中间环节做了缓冲数据攒着不发客户端看起来就是一直不动。加上Cache-Control: no-cache和Connection: keep-alive之后就好了。6.4 中文乱码与路径含空格乱码这个症状很有辨识度文件内容变成了问号或者中文注释在模型回复里变成了一堆符号。源头通常是两处。一是终端的代码页不是 UTF-8前面 2.3 讲过。二是网关转发时没指定字符集导致上游按默认编码解析。在请求头里明确写上Content-Type: application/json; charsetutf-8能解决大部分情况。路径含空格的问题表现更奇怪读文件时报“文件不存在”但你去目录里看明明存在。原因是空格把参数切开了。解决办法是给路径加引号或者在 Windows 上养成把项目放在不含空格的路径下的习惯比如D:\work\myproject而不是D:\我的项目\新 项目。6.5 工具调用失败的典型表现症状是模型能聊天你问它什么它都能答但你让它改文件、跑命令它就只会说“好的我来修改”然后什么都不做。根因几乎一定是工具定义没有正确转换。客户端传的tools结构网关没转成上游认识的格式上游就认为这次请求没有工具可用模型自然只能动嘴。排查方法在网关里把req.body.tools打印出来看看有没有。有的话看转换后的 payload 里有没有。如果转换后丢了就是映射逻辑的问题。还有一个更隐蔽的情况工具定义转过去了但模型返回的工具调用结果没被正确转回来表现是客户端收到了结果但不知道怎么执行界面就停在半路。这一块我建议单独写几个测试用例把“有工具定义”“无工具定义”“模型返回工具调用”“客户端回传工具结果”这四种情况都覆盖到调试起来比在真实场景里瞎猜快得多。6.6 上下文超限与费用失控这两个问题不是“坏了”是“用得不舒服”但同样影响体验。上下文超限的表现是对话进行到一定长度后突然报错提示超出模型能处理的范围。原因是 Claude Code 会尽量把整个会话历史都带上会话一长就爆了。应对办法是在会话变长时主动开新会话或者调小它能读取的上下文窗口。更聪明的做法是在项目根目录的CLAUDE.md里写清楚“重要信息请写入文件”让它自己承担记忆管理的责任。费用失控更隐蔽。你会发现在某些任务上花销是平时的好几倍。原因通常是一是每次都把大量文件内容塞进上下文二是小模型请求其实走了主力模型三是推理模型被用在了不需要推理的地方。控制办法就是前面说的三层——网关侧限制max_tokens、小模型请求做特殊处理、按任务类型切换模型。7. 让它真正好用几个把效率拉起来的设置链路通了、故障排完了最后这一步是把“能用”变成“好用”。工具的价值不在于它能不能跑而在于它跑起来之后能不能真的减少你手上的工作量。7.1 CLAUDE.md 与项目上下文在项目根目录放一个CLAUDE.md这是投入产出比最高的一件事。它相当于给这个工具的一份项目交接文档里面写清楚这个项目的技术栈是什么、目录结构怎么组织的、有哪些约定俗成的规范、哪些文件不要动、构建和测试命令是什么。一个实用的模板大概长这样# 项目说明 ## 技术栈 前端 React 18 Vite后端 Node 20 Express数据库用文件型存储。 ## 目录约定 - src/componentsUI 组件一个文件一个组件 - src/api接口层所有请求集中在这里 - src/utils纯函数工具禁止引入 React 依赖 ## 硬性规则 - 不要修改 package-lock.json - 不要动 migrations 目录下的历史文件 - 所有新增函数必须有 JSDoc 注释 ## 常用命令 - 开发npm run dev - 测试npm test - 构建npm run build写这个文件的价值在于你不用在每次会话里重复解释背景模型一上来就知道边界在哪。我实测下来的差别很明显没有这个文件的时候它经常会在不该改的地方动手或者用错框架的写法有了之后第一次输出就基本在轨道上。维护上也有个经验这个文件不要写得太长。超过两三百行之后它占掉的上下文本身就变成了负担。真正关键的信息才放进去其他的让它在过程中自己发现。7.2 小模型路由省钱前面提过一次这里展开讲具体怎么做。Claude Code 内部有几类调用是“辅助性”的给会话生成标题、判断上下文是否需要压缩、做一些轻量的意图分类。这类调用对质量要求不高但频率很高。如果它们也走主力模型你的开销会凭空多出一截。做法是在网关里加一层判断。判断依据可以是请求里的max_tokens很小、或者消息里没有工具定义、或者 sys提示的内容命中某些关键词。命中的请求要么把max_tokens压到极低要么直接返回一个预设的短回复根本不发到上游。function isLightTask(body) { const hasTools Array.isArray(body.tools) body.tools.length 0; const tiny (body.max_tokens || 0) 256; return !hasTools tiny; }这个判断不一定百分百准但错了也没大损失——最多是辅助任务用了好模型或者反过来一个轻任务拿到了降级结果。多跑几天看日志慢慢调阈值就行。7.3 长任务的会话管理跑长任务时最常见的失败模式不是模型能力不够而是上下文被撑爆或者中途断连。我的几个习惯。第一把大任务拆成能被单次会话承载的小块每块做完就让它把结论写进文件然后开新会话接着做靠文件来传递状态而不是靠会话历史。第二重要的中间结果立刻落盘别指望它记在对话里任何一次意外中断都会让你从头再来。第三长任务开始前先在settings.json里把超时调大前面说的十分钟是针对长任务的短任务反而应该调小一点这样卡住了能快速失败而不是傻等。还有一点是心态上的这类工具在长任务里会有“越跑越偏”的倾向前面几轮回合还很准确后面开始自己发明需求。所以每完成一个阶段我都会让它复述一遍当前状态和下一步计划确认没跑偏再继续。这个动作花不了几十秒但能省掉后面大量的返工。最后分享一个我在实际使用中体会最深的一点这套东西真正的门槛从来不是“装不上”而是“不知道自己在装什么”。把客户端、协议、转换层、上游服务这四者的关系在脑子里画清楚九成的报错你自己就能推出原因画不清楚就算照着教程一步步抄通了下次换个环境还是得从头再来一遍。所以我在写网关那段代码的时候特意分了阶段先跑通对话再加工具就是为了让这个过程本身变成一次理解而不是一次复制。