企业官网建设流程全解析

终端里敲一行命令，让模型自己去读文件、改代码、跑测试、看报错、再改一遍——这种干活方式我第一次接触时确实有点上头。Claude Code 就属于这一类工具里做得比较克制的一个：它没有花哨的界面，本质是一个跑在命令行里的编码 agent，用自然语言驱动文件读写和 shell 执行，把"改代码"这件事从"我告诉你怎么改"变成了"你自己看着办，改完给我看 diff"。但真要在自己机器上把它跑顺，尤其还要接上 DeepSeek 这类国内可直接调用的模型，中间要过的坎比想象中多——地域可用性的边界、Node 环境的版本地狱、协议格式对不上、工具调用返回一堆解析错误，我基本一个没落下。

这篇记录就是把这些坑按顺序捋一遍：先讲清楚这东西的运行链路和适用边界，再讲合规前提下的可用性判断，然后是安装配置的完整步骤，重点放在DeepSeek 接入这块——因为协议差异和模型映射是最容易让人卡一整天的地方。最后附一份排查速查表和我自己用下来觉得最有价值的几条操作习惯。不管你是在终端里折腾 AI 编码工具的老手，还是刚听说这玩意儿想试一把的新手，应该都能从里面抄到点东西。

1. 先搞清楚这东西到底在干什么

1.1 终端型编码助手和 IDE 插件的本质差别

很多人第一次听说 Claude Code，会下意识把它归类成"又一个代码补全插件"。这两者的差别其实挺大。IDE 插件的工作模式是被动响应：你光标停在哪，它给你补一段，你不敲键盘它就不动。终端型 agent 的工作模式是主动执行：你给它一句"把 utils 目录下所有日期格式化改成统一时区"，它会自己去找文件、读内容、判断改哪几行、批量写入、再跑一遍测试看有没有挂掉，挂了就自己回滚重来。

这个差别带来的直接影响是：它的能力上限取决于模型能不能稳定地做多轮工具调用，而不是取决于补全质量有多高。一个只会补全的模型在这个场景下几乎没用，因为它不敢改文件；而一个奖励模型很强的推理模型，在这里反而可能因为"想太多"而调用一堆多余的工具，把上下文撑爆。

我在实际使用中总结的判断标准很简单：如果你日常工作是"写新代码"为主，IDE 插件的性价比更高；如果你的日常是"改存量代码、排查报错、批量重构、写脚本"，那终端 agent 的价值就体现出来了，因为它真的会去执行而不是只给你建议。

1.2 一次请求背后其实有三段链路

要理解后面所有的坑，得先把这条链路拆开看。你在终端敲下一句话之后，发生的是这么三件事：

1. 客户端侧：把当前工作目录的文件结构、你指定的文件内容、上几轮的对话历史、系统提示词，打包成一个结构化的请求体；
2. 协议侧：这个请求体按照 Anthropic Messages API 的格式序列化，带上认证头，发到配置的端点；
3. 模型侧：服务端解析请求，模型生成回复，回复里可能包含普通文本，也可能包含tool_use块（比如"我要读某个文件"），客户端拿到后执行工具、把结果塞回去，再发一轮。

这三段里，任何一段的格式对不上，整个流程就会断。地域问题卡在第一段和第三段之间（能不能连上端点），安装问题卡在第一段（客户端都起不来），DeepSeek 接入问题卡在第二段（协议格式不兼容）。分清楚卡在哪一段，排查效率会高一个数量级。

1.3 什么情况下值得上手，什么情况下可以先等等

说句实在话，这类工具不是所有人都需要。我的判断是这样的：

另外提醒一句：这东西会真实地修改你磁盘上的文件。第一次用务必在一个有 git 版本控制的仓库里跑，或者干脆新建一个空目录做实验。我见过有人直接在没提交的工作目录里让它"清理一下无用代码"，结果一轮下来改了四十多个文件，git diff都没法看。

2. 地域可用性：先把边界讲清楚

2.1 为什么会碰到"用不了"这件事

标题里提到的"地域限制"，本质上是一个服务可用性问题，而不是技术问题。任何在线服务都有它的服务范围约定，官方条款里写得很清楚：在哪些区域提供服务、账号注册需要什么条件、违规使用会有什么后果。这不是什么可以"技术性绕开"的东西，而是使用前的前置判断。

我碰到这个问题的场景很典型：装好了，配置也写了，一敲命令返回一个不太友好的错误码，第一反应是"是不是我配置写错了"，来回折腾两小时，最后发现根本不是配置问题。这种时间浪费最冤枉。

所以我的建议是：动手之前先确认端点可达性。方法很简单，别急着装客户端，先用最朴素的方式测一下——用curl直接对你要用的 API 端点发一个最小请求，看返回什么。

# 用一个最小请求探测端点可达性，只看 HTTP 状态码和返回体 curl -s -o /dev/null -w "HTTP %{http_code}\n" \ -X POST "https://<你的服务端点>/v1/messages" \ -H "content-type: application/json" \ -H "x-api-key: <你的密钥>" \ -d '{"model":"<模型名>","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

返回 200 或 400（参数问题）说明链路是通的；返回超时、连接重置、或者 403 带区域相关字样，那问题就不在你的配置上了，往下折腾是纯浪费时间。

2.2 合规前提下真正可行的三条路径

确认了服务可用性的边界之后，可行的方案其实就三条，按推荐程度排序：

第一条：直接使用在本地可访问的模型服务端点。这是最干净的路径。国内有不少模型服务商提供标准 API，注册、充值、调用全程无障碍，延迟还低。缺点是需要做一层协议适配（后面第 4 章会详细讲），但这是一次性成本，配好就不用管了。

第二条：使用支持 Anthropic 协议的兼容端点。部分服务商或自建网关会直接暴露一个/v1/messages兼容接口，请求体格式和官方一致，只要把ANTHROPIC_BASE_URL指过去就能用，客户端侧一行代码都不用改。这是最省事的方案，缺点是模型能力和官方有差异，工具调用的稳定性需要自己实测。

第三条：本地部署开源模型。适合对数据完全不出内网有硬性要求的场景。用 Ollama、vLLM 这类运行时把模型拉起来，再套一层协议转换，整个链路都在本机。代价是硬件门槛——想在本地跑出能稳定做多轮工具调用的效果，显存需求不低，而且首字延迟和吞吐跟云端 API 不是一个量级。

我把这三条路径的取舍整理成了一张表，你可以对着自己的情况选：

2.3 账号与数据的几条底线

这一段我想单独强调，因为踩过坑的人不少。

密钥不要写进代码仓库。环境变量、.env文件（并且加进.gitignore）、系统级配置文件，这三种方式按场景选，但绝对不能直接写进settings.json然后提交上去。我见过不止一次有人把密钥推到公开仓库，几分钟内就被扫号脚本刷走额度。

不要在受控环境里让它自由执行命令。这类 agent 有 shell 执行权限，理论上你让它跑什么它就跑什么。生产环境、包含敏感凭据的目录、有数据库连接串的配置文件，都不适合直接开权限模式跑。我的做法是给它单独开一个工作副本目录，跑完再人工 review 一遍 diff 合并回去。

注意隐私边界。你发给模型的代码、报错栈、配置片段都会离开本机。公司的核心业务代码、包含个人信息的数据文件，使用前先确认清楚内部规定。这个不是技术问题，但比任何技术问题都重要。

提示：如果只是想验证效果，用一个开源项目的公开代码跑，既能看到真实表现，又没有任何数据风险，是最稳妥的起步方式。

3. 安装与环境配置：从零到跑通第一条命令

3.1 运行时环境准备，版本是第一道坎

Claude Code 是一个 Node 包，这意味着你机器上的 Node 版本直接决定了它能不能跑起来。官方要求大致是 Node 18 以上，但我实测下来建议直接上 Node 20 LTS 或 22 LTS，原因有两个：

一是老版本 Node 对某些 ESM 特性的支持不完整，启动时会报一些莫名其妙的语法错误，看起来像是包坏了，其实是运行时太老；二是 20 以上版本自带的新版 npm 在处理全局安装的权限和路径问题时表现稳定得多。

如果你机器上已经有 Node 但版本不确定，先看一眼：

node -v npm -v which node # Windows 用 where node

版本低于 18 的话，别去折腾升级系统自带的 Node，直接用版本管理器装一个新的。macOS / Linux 上用 nvm，Windows 上用 nvm-windows 或者 fnm，都是成熟方案：

# 以 nvm 为例，装一个 LTS 版本并切过去 nvm install 20 nvm use 20 nvm alias default 20 # 设为默认，避免每次开新终端都要切

这里有个很常见的坑：用 nvm 切了版本，但新开一个终端标签页又回到老版本了。原因是nvm use只对当前 shell 会话生效，必须设置alias default才是永久的。我当初因为这个原因，装完之后在 A 终端能跑、B 终端报错，来回折腾了半小时。

还有一个 Windows 特有的问题：如果之前用官方安装包装过 Node，再装 nvm-windows，两者的路径可能打架。正确顺序是先卸载干净再装管理器。

3.2 安装方式与版本管理

环境就绪之后，安装本身很简单：

npm install -g @anthropic-ai/claude-code

-g是全局安装，装完就能在任何目录下用claude命令。如果这一步报权限错误（EACCES），不要直接上sudo——用sudo装全局包会导致后续升级、卸载都出现权限混乱，而且用sudo跑 agent 本身就很危险。

正确做法有两个，选其一：

# 方案一：把 npm 全局目录指到用户目录下，一劳永逸 npm config set prefix "$HOME/.npm-global" export PATH="$HOME/.npm-global/bin:$PATH" # 写进 ~/.zshrc 或 ~/.bashrc # 方案二：用 nvm 管理 Node，全局包天然在用户目录下，不会有权限问题

我个人更推荐方案二，因为 nvm 顺带把 Node 版本切换也解决了，一次性投入后续省心。

装完验证一下：

claude --version

能打印出版本号就说明客户端这一段通了。如果提示command not found，八成是PATH没生效，source一下配置文件或者重开终端就行。

关于升级：这类工具迭代很快，我的做法是每两周手动检查一次，而不是开自动更新。原因是新版本偶尔会改配置项的名称或者行为，自动更新之后某天早上突然跑不起来，排查成本反而更高。手动升级至少你知道"刚才动了什么"。

npm outdated -g --depth=0 # 看看有没有新版本 npm update -g @anthropic-ai/claude-code

3.3 环境变量体系：几个变量决定它连到哪

这是整个配置里最核心的部分。Claude Code 的行为基本由一组环境变量控制，搞懂这几个，后面接任何模型都是同一套逻辑。

这里有两个高频误区，我几乎每次帮人排查都能碰到：

误区一：BASE_URL结尾的路径写错。有的服务商端点是https://host/v1，有的是https://host/anthropic，还有的要求你写到https://host/v1/messages的上一级。写错了返回 404，但报错信息通常很含糊，看起来像认证失败。最稳的验证方法还是 2.1 节那个curl，直接把完整路径拼上去测，能返回结构化 JSON 就说明路径对了。

误区二：ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN同时设置。有些实现里后者会覆盖前者，有些会报冲突。我现在的习惯是只设一个，遇到认证失败先换另一个试试，比瞎猜快得多。

配置的落盘位置也有讲究。临时测试直接export在当前 shell 里；长期使用写进~/.zshrc或~/.bashrc；如果要按项目隔离，用direnv在项目目录下放一个.envrc，进出目录自动切换，这个方案在多项目并行的时候特别好使。

# ~/.zshrc 里追加，长期生效 export ANTHROPIC_BASE_URL="https://<你的端点>/v1" export ANTHROPIC_AUTH_TOKEN="<你的密钥>" export ANTHROPIC_MODEL="<主模型名>" export ANTHROPIC_SMALL_FAST_MODEL="<小模型名>"

注意：改完配置文件一定要source ~/.zshrc或者重开终端，否则变量不会生效。这个低级错误我犯过不止一次，每次都先怀疑配置写错，最后发现是没 source。

3.4 项目级配置和会话级配置怎么分工

除了环境变量，Claude Code 还有两层配置文件，很多人搞不清楚该往哪写。

第一层是全局配置，在用户主目录下的.claude/目录里。这里放的是跨项目通用的东西：默认模型、权限白名单、MCP 服务注册。改一次全局生效。

第二层是项目级配置，核心是项目根目录下的CLAUDE.md。这个文件的内容会被自动注入到每一轮对话的上下文里，相当于给 agent 的一份项目说明书。它的作用比很多人想的大——你在这里写清楚"这个项目用 pnpm 不用 npm""测试命令是pnpm test:unit""不要动legacy/目录下的代码"，模型在后续所有操作里都会遵守。

我的建议是每个项目都跑一次初始化命令，让它自己扫一遍仓库生成初稿，然后人工修一遍：

cd /path/to/your/project claude # 进入交互界面后输入 /init

生成的CLAUDE.md通常会包含项目结构、技术栈、常用命令。但它写的东西不一定准，尤其是单测命令和构建命令，经常是从package.json里猜的。我每次都会人工核对一遍，把跑不通的命令删掉，再补几条自己踩过坑的约束。这份文件写好了，后面能省掉大量重复解释。

3.5 第一次跑通的验证清单

配置完之后别急着上真实项目，按这个顺序验证一遍，能省下大量后续排查时间：

1. claude --version有输出，说明客户端正常；
2. claude进入交互界面不报错，说明基础配置能被读取；
3. 输入一句简单指令比如"列出当前目录下的文件"，能看到工具调用和结果，说明工具链通了；
4. 让它读一个具体文件并总结内容，能准确回答，说明上下文注入正常；
5. 让它改一个小文件（比如给某个函数加一行注释），然后用git diff确认改动符合预期，说明写权限正常。

这五步全过，才算真正跑通。任何一步失败都先停在这里排查，不要带着问题往下接模型，否则后面出问题你分不清是配置的锅还是模型的锅。

4. 接入 DeepSeek：协议差异才是真正的拦路虎

4.1 两种 API 协议到底差在哪

这一段是整篇文章的技术核心，值得花点篇幅讲透。

Claude Code 说的是Anthropic Messages API这门"语言"，而 DeepSeek 官方 API 说的是OpenAI Chat Completions API这门"语言"。两者都是 HTTP + JSON，看起来差不多，但结构上有几处关键差异，任何一处对不上都会导致解析失败。

看这张表就知道，差异最大的是工具调用这一块。而终端型编码 agent 恰恰重度依赖工具调用——读文件、写文件、执行命令全靠它。所以如果你只是把BASE_URL指过去，请求能发出去但模型一调用工具，客户端解析就崩了，表现为"模型在胡说八道"或者直接抛 JSON 解析异常。

这就是为什么"直连"方案在多数情况下行不通，必须要有一层协议转换。

4.2 直连方案和它的适用边界

先把话说清楚：如果你的服务端点本身就暴露了 Anthropic 兼容接口，那就不需要转换层，直接改环境变量就行，这是最理想的情况。

export ANTHROPIC_BASE_URL="https://<兼容端点>/v1" export ANTHROPIC_AUTH_TOKEN="<密钥>" export ANTHROPIC_MODEL="<端点声明的模型名>"

判断端点是不是真兼容，别信文档，实测：

curl -s -X POST "https://<端点>/v1/messages" \ -H "content-type: application/json" \ -H "x-api-key: <密钥>" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model":"<模型名>", "max_tokens":64, "messages":[{"role":"user","content":"reply with the word ok"}] }' | head -c 500

返回体里如果有content数组、stop_reason字段，那就是真兼容。如果返回choices、finish_reason，说明它其实是 OpenAI 格式换了层皮，你还需要转换。

这个测试非常重要，能帮你省掉半天时间。我第一次接的时候就是没测，直接开会话，结果一直报错，还以为是密钥问题，换了三次密钥才反应过来是协议不对。

4.3 路由转换层：结构、思路和一份可跑的骨架

如果端点确实只支持 OpenAI 格式，那就必须自己搭一层转换。思路很直白：本地起一个小服务，对外暴露/v1/messages，收到 Anthropic 格式的请求后转成 OpenAI 格式发给上游，拿到响应再转回来。

社区里有现成的转换路由工具可以直接用，但自己写一个好处是可控——出了问题能改，能加日志，能针对特定模型的怪癖做兜底。下面给一个能跑起来的骨架，用 Python + FastAPI：

from fastapi import FastAPI, Request from fastapi.responses import JSONResponse, StreamingResponse import httpx, json, os UPSTREAM = os.environ["UPSTREAM_BASE_URL"] # 上游 OpenAI 兼容端点 UPSTREAM_KEY = os.environ["UPSTREAM_API_KEY"] MODEL_MAP = json.loads(os.environ.get("MODEL_MAP", "{}")) # Anthropic 模型名 -> 上游模型名 app = FastAPI() def to_openai(body: dict) -> dict: msgs = [] if body.get("system"): sys = body["system"] msgs.append({"role": "system", "content": sys if isinstance(sys, str) else sys[0]["text"]}) for m in body.get("messages", []): c = m["content"] if isinstance(c, str): msgs.append({"role": m["role"], "content": c}) continue # 内容块数组：拆成文本 / tool_use / tool_result texts, tool_calls, tool_results = [], [], [] for blk in c: if blk["type"] == "text": texts.append(blk["text"]) elif blk["type"] == "tool_use": tool_calls.append({ "id": blk["id"], "type": "function", "function": {"name": blk["name"], "arguments": json.dumps(blk["input"], ensure_ascii=False)} }) elif blk["type"] == "tool_result": tool_results.append(blk) for tr in tool_results: content = tr.get("content") msgs.append({"role": "tool", "tool_call_id": tr["tool_use_id"], "content": content if isinstance(content, str) else json.dumps(content, ensure_ascii=False)}) if texts or tool_calls: item = {"role": m["role"], "content": "".join(texts) or None} if tool_calls: item["tool_calls"] = tool_calls msgs.append(item) out = { "model": MODEL_MAP.get(body.get("model"), body.get("model")), "messages": msgs, "max_tokens": body.get("max_tokens", 4096), } if body.get("tools"): out["tools"] = [{"type": "function", "function": {"name": t["name"], "description": t.get("description", ""), "parameters": t.get("input_schema", {"type": "object", "properties": {}}) }} for t in body["tools"]] return out @app.post("/v1/messages") async def messages(req: Request): body = await req.json() payload = to_openai(body) async with httpx.AsyncClient(timeout=300) as cli: r = await cli.post(f"{UPSTREAM}/chat/completions", json=payload, headers={"Authorization": f"Bearer {UPSTREAM_KEY}"}) data = r.json() choice = data["choices"][0]["message"] blocks = [] if choice.get("content"): blocks.append({"type": "text", "text": choice["content"]}) for tc in choice.get("tool_calls") or []: blocks.append({"type": "tool_use", "id": tc["id"], "name": tc["function"]["name"], "input": json.loads(tc["function"]["arguments"] or "{}")}) stop = data["choices"][0].get("finish_reason") return JSONResponse({ "id": data.get("id", "msg_local"), "type": "message", "role": "assistant", "model": payload["model"], "content": blocks or [{"type": "text", "text": ""}], "stop_reason": {"tool_calls": "tool_use", "stop": "end_turn", "length": "max_tokens"}.get(stop, "end_turn"), "usage": {"input_tokens": data.get("usage", {}).get("prompt_tokens", 0), "output_tokens": data.get("usage", {}).get("completion_tokens", 0)}, })

跑起来之后，客户端侧的配置就变成指向本机：

export ANTHROPIC_BASE_URL="http://127.0.0.1:8787/v1" export ANTHROPIC_AUTH_TOKEN="local-dummy" # 转换层不校验，填个占位符即可 export UPSTREAM_BASE_URL="https://<上游端点>/v1" export UPSTREAM_API_KEY="<上游密钥>" export MODEL_MAP='{"claude-sonnet-4":"deepseek-chat","claude-haiku-4":"deepseek-chat"}'

几个必须提醒的点：

• 上面的骨架只处理了非流式响应。实际使用中流式是刚需，否则长回答要等很久。补流式需要把上游的 SSE 增量逐块转成 Anthropic 的content_block_delta事件，工作量不小，但社区现成工具里基本都实现好了，建议优先用现成的。
• MODEL_MAP这层映射必须有。客户端内部会写死几个模型名（主模型和小模型），你不在转换层做映射，上游会收到一个它不认识的模型标识，直接 400。
• 日志一定要打全。转换层的 bug 是最难排查的一类，因为错误发生在中间，客户端和上游看到的都是"正常"的。把每次请求的入参和出参落盘，出问题直接比对。

4.4 模型映射与成本控制，这里最容易花冤枉钱

接上之后你会发现一个新的问题：钱花得比预期快。

原因是这类 agent 的请求频率远超想象。一次"帮我修个 bug"的任务，背后可能是十几轮工具调用，每轮都要把完整的对话历史重新发一遍。上下文越滚越大，输入 token 消耗是线性甚至超线性增长的。

我的控制策略有三条：

第一，主模型和小模型分开配。小模型负责的是"生成对话标题""总结文件内容""判断该用哪个工具"这类轻活，用最便宜的模型就够。很多人图省事两个变量填同一个模型名，成本直接翻倍还不自知。

第二，主动控制上下文长度。长时间会话之后，历史会变得极长。我的习惯是一个任务一个新会话，做完就退出重开。看起来麻烦，但实际省下的 token 很可观，而且模型在短上下文里的表现也更稳定，不容易"忘记"之前的约束。

第三，善用/clear和项目级的CLAUDE.md分工。通用的项目约束写进CLAUDE.md，它是每轮都注入的，不用你每次重复说；一次性的任务描述放在对话里，做完/clear掉。这样能避免"我每次都要重新解释一遍项目结构"这种重复消耗。

粗算一下：假设一次会话平均 20 轮，每轮输入 8k token，输出 500 token，跑一天 10 个会话，输入侧就是 160 万 token。这个量级下，单价差一倍就是实打实的成本差。所以选模型的时候不要只看能不能跑通，要算清楚单位任务的成本。

4.5 一份可以直接抄的目录结构

最后把配置整理成一个可复用的形态，方便多项目切换：

~/ai-agent/ ├── .envrc # 环境变量，用 direnv 自动加载 ├── router/ │ ├── main.py # 转换层 │ └── requirements.txt └── logs/ └── router.log # 请求日志，排查用 项目A/ ├── .envrc # source ../ai-agent/.envrc 后覆盖项目特定变量 └── CLAUDE.md 项目B/ ├── .envrc └── CLAUDE.md

.envrc的内容大致是：

# 全局部分 export ANTHROPIC_BASE_URL="http://127.0.0.1:8787/v1" export ANTHROPIC_AUTH_TOKEN="local-dummy" export ANTHROPIC_MODEL="claude-sonnet-4" # 转换层会映射成上游真实模型 export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4" # 上游部分（转换层读取） export UPSTREAM_BASE_URL="https://<上游端点>/v1" export UPSTREAM_API_KEY="<密钥>" export MODEL_MAP='{"claude-sonnet-4":"deepseek-chat","claude-haiku-4":"deepseek-chat"}'

这样每个项目目录下放一份.envrc，进出目录自动切换配置，不用手动 export，也不会串环境。这个习惯养成之后，多项目并行基本不会出配置冲突。

5. 常见问题与排查实录

5.1 启动阶段就挂掉：环境和权限类

这一类问题的共同特征是还没发出任何网络请求就失败了，所以排查方向很明确——只看本地环境。

这里我想多说一句关于中文路径的问题。Windows 环境下如果项目放在带中文的目录里，某些依赖读文件路径会出问题，表现为"文件明明存在但读不到"。这个坑很隐蔽，因为错误信息不会提示路径编码，只会说文件不存在。我的做法是所有项目目录一律用英文命名，从根上避免。

5.2 认证和路径类：401、403、404 怎么区分

这三个状态码含义完全不同，但报错信息经常被客户端包装成一句含糊的"请求失败"，需要你自己去看底层返回。

401 / 403：认证问题。依次检查：密钥是不是复制的时候带了空格或换行；密钥是不是过期或者额度用完了；AUTH_TOKEN和API_KEY是不是同时设了导致冲突；请求头字段名对不对（有的端点只认x-api-key，有的只认Authorization: Bearer）。

404：路径问题，最常见。十有八九是BASE_URL的路径后缀写错了。我碰过的情况包括：多写了一个/v1、少写了一个/v1、用了/v1/messages而不是/v1、把末尾的斜杠弄丢了。排查方法就一个：用 curl 逐层拼接测试，从https://host开始，逐步加/v1，看哪一层返回的不是 404。

429：限流。不是你配错了，纯粹是请求频率超了。处理方式要么降并发，要么换个时段，要么升级套餐。这个不需要排查，等一会儿就好。

超时或连接重置：网络层问题。这时候回到第 2 章的可用性判断，用 curl 单独测端点，确认是端点本身不可达还是客户端配置的问题。

5.3 能跑通但结果很怪：模型和提示词层面

这一类是最折磨人的，因为技术上什么都没坏，就是效果不对。

典型表现一：模型反复读同一个文件。原因是文件内容太长，超出了单次上下文预算，模型读了一半就被截断，下一轮又从头读。解决办法是把大文件拆开，或者在CLAUDE.md里明确写"处理大文件时先用 grep 定位关键行，不要整文件读取"。

典型表现二：改代码改到一半停了。可能是max_tokens设得太小，输出被截断；也可能是模型的finish_reason是length而不是正常结束，转换层把这个映射成了错误的stop_reason，客户端以为是正常结束。排查方法是看转换层日志里的原始响应。

典型表现三：模型说"我要执行命令"但命令没跑。这是工具调用格式不匹配的典型症状——模型生成了工具调用意图，但转换层没正确转成 Anthropic 的tool_use块，客户端根本没识别出来，于是当成普通文本显示。回到 4.1 节那张对照表，逐个字段核对。

典型表现四：回答质量突然下降，开始胡说八道。大概率是上下文太长，模型注意力被稀释了。特别是接了上下文窗口较小的模型时，会话跑久了必然出现。我的做法是每 15 到 20 轮主动开新会话，把关键结论写进CLAUDE.md或者一个临时笔记文件里，新会话开头让它读这个文件，比指望它记住几十轮历史靠谱得多。

5.4 工具调用失败专项排查

因为这是接入第三方模型最容易挂的地方，单独列一个流程：

1. 先看客户端日志，确认它确实发出了带tools字段的请求。如果请求里压根没工具定义，问题在客户端权限配置或者模型不支持工具调用的判定上。
2. 再看转换层日志，确认工具定义被正确转成了 OpenAI 的tools[].function.parameters格式。input_schema是 JSON Schema，字段名必须严格对应，写错一个字母上游就解析不了。
3. 看上游返回，确认tool_calls数组里有内容。如果模型只返回了文本没返回tool_calls，说明这个模型对工具调用的支持不好，或者提示词没引导它对。
4. 看回传路径，工具执行完之后结果要以role: "tool"加tool_call_id回传。这个tool_call_id必须和上游返回的id完全一致，对不上模型就不知道这是哪个工具的结果。

这个四步排查法我用下来效率最高，基本能在十分钟内定位到具体是哪一层的锅。

5.5 一份可以贴在显示器旁边的速查表

6. 用顺手之后才会懂的几件事

6.1 上下文管理的本质是"交接班"

刚开始用的时候我总觉得上下文越大越好，恨不得把整个仓库都塞进去。用了两个月才想明白：上下文不是越大越好，而是越"准"越好。

模型的注意力是有限资源。你塞进去二十个不相关的文件，它对这个任务的判断力反而会下降。我现在的做法是把它当成一个每天来上班但不记得昨天的同事：每次开工前给一份简明的工作交接单（CLAUDE.md里的项目约束 + 当前任务的一段文字描述），干完一个任务就换人。这比指望它记住三天前的对话靠谱得多。

具体操作上，我会在项目根目录维护一个NOTES.md，记录"当前正在改什么""哪些坑已经踩过""哪些文件不要动"。开新会话时第一句就是"先读 NOTES.md"，三十秒就能让它进入状态。这个习惯看着笨，但实际省下的沟通成本相当可观。

6.2 权限边界要提前划好，不要事后后悔

这类工具默认会每次执行命令前问你一句，很多人嫌烦就去开跳过确认的模式。我不建议，至少不建议在主力工作目录里这么干。

我的做法是分目录：实验目录随便开，出问题最多重来；主力项目目录保持默认的逐次确认，虽然慢一点，但任何一次意外的rm或者git checkout .都能被拦下来。这个慢是值得的，我用它挡下过至少两次误删。

另外一个小技巧：把只读操作批量加进允许列表，比如ls、cat、grep、git status、git diff。这些命令不会有破坏性，放行之后交互流畅度提升明显，而写操作仍然保持确认。这个折中方案我用下来体验最好。

6.3 效率提升的关键在于"描述任务的颗粒度"

最后一个心得，可能比所有配置技巧都重要。

同一套配置，任务描述写得糙和写得细，效果差距能有五倍。我一开始的写法是"帮我修一下这个 bug"，结果它到处乱翻，改了三个不相关的文件。后来改成"在src/api/client.ts的retry函数里，第三次重试之后没有清空计时器，导致内存泄漏，请只修改这一个函数"，一次就成了。

规律是：给它明确的范围（哪个文件哪个函数）、明确的症状（什么现象）、明确的约束（只改哪里）。这三样给全了，它的表现会稳定得多。反过来，如果你是故意想让它探索一下、给点新思路，那就把范围放开，但要做好 review 每一处改动的准备。

这两种模式我都常用，区别只在于我清不清楚自己想要什么。想清楚了就给精确指令，没想清楚就让它先探索再收敛，但探索模式下我绝对不会跳过 diff review。

最后分享一个我用了很久的小技巧：接第三方模型的时候，先在转换层里加一个"调试模式"开关，打开之后把所有请求和响应完整落盘到文件。刚接上的头几天全程开着，遇到任何反常直接翻日志比对原始报文，比在客户端侧猜要快十倍不止。等跑稳定了再关掉，但也别删代码——换个模型或者上游接口升级的时候，你还得把它打开。