企业官网建设流程全解析

1. 先把需求和边界想清楚

在 Windows 上部署 Claude Code 并接入 DeepSeek API，这件事本身不复杂，复杂的是中间那几层容易被忽略的衔接：命令行为什么装了却敲不出来、环境变量为什么设了却不生效、接口为什么通了却一直卡在工具调用上。我前后在三台不同配置的 Windows 机器上折腾过这套组合——一台 Win10 21H2 的旧本、一台 Win11 的开发机、一台公司发的锁了权限的办公机——踩的坑几乎不重样。所以下面写的不是"照抄官网三步走"的那种教程，而是把每一步背后的原因、以及出错时你该往哪个方向找，都摊开讲。

Claude Code 是 Anthropic 推出的命令行编程助手，它不是一个聊天窗口，而是一个能直接读写你本地文件、执行 shell 命令、跑测试、看 git 差异的"编程执行体"。它默认走 Anthropic 自家的模型服务，但你完全可以把后端换成别家的 API——DeepSeek 提供了 Anthropic 兼容格式的端点，只要把四个环境变量指过去，Claude Code 就会以为自己在跟原来的服务说话。这套组合的价值很直接：保留 Claude Code 那套成熟的工程化交互（项目记忆、文件编辑、命令执行、差异预览），同时把模型成本压下来一大截。适合谁？适合手上有一堆本地项目、想让 AI 真正参与到"改代码"而不是"聊代码"这一步的 Windows 开发者，也适合之前只在网页端用过对话式编程助手、想试试命令行形态的人。基础要求不高：会开终端、会改环境变量、能看懂报错信息，就够了。

1.1 Claude Code 到底是个什么东西

很多人第一次听到这个名字，会以为它是某个 IDE 插件。不是。它本质上是一个跑在终端里的循环执行器：接收你的一句自然语言，把它拆成若干步，每一步可能是"读某个文件""搜索某个关键词""执行某条命令""写入某段代码"，然后把结果再喂回模型，继续下一步，直到任务收敛或者你打断它。这个循环结构决定了它对模型的工具调用能力要求很高——模型必须能准确地输出结构化的工具调用请求，而不是只会吐文字。

理解这一点非常关键，因为后面所有的兼容性问题，八成以上都出在工具调用这一层。文字对话能不能通，只是第一关；工具调用能不能被正确解析，才是决定这套组合好不好用的分水岭。我在早期版本上就遇到过模型能正常聊天、但一旦让它改文件就开始"原地打转"的情况——它反复说要改，但生成的调用结构不符合预期，客户端解析失败，于是重试，如此往复。这类现象后面会专门讲排查思路。

另外一点要提前建立认知：Claude Code 本身不带模型。它是个空壳客户端，模型能力和计费全在你配置的那个 API 账号上。所以"部署 Claude Code"这个说法其实不太准确，准确的说法是"部署客户端 + 配好后端"，两件事分开做，出问题时也分开查。

1.2 为什么要把模型换成 DeepSeek

最直接的原因是账单。同一段代码修改任务，用高阶模型跑一次和用性价比模型跑一次，成本可能差一个数量级。Claude Code 这种形态特别费 token——它每次循环都要把项目上下文、文件内容、历史对话重新塞一遍，一个中等规模的重构任务，累计几万到几十万 token 是常态。如果你按高阶模型的价格跑，一天下来心跳会加速。

第二个原因是延迟和链路。命令行工具对响应速度的体感比网页端敏感得多，因为它是一步接一步串行执行的，每一步多等两秒，十步就是二十秒。把后端换到物理距离更近、链路更短的服务上，整个交互的"跟手感"会有明显差别。

第三个原因是模型特性匹配。DeepSeek 系列在代码理解和中文语境下的指令遵循上表现不错，尤其是处理中文注释、中文需求描述时，比一些纯英文语料训练的模型更少出现"理解偏了"的情况。而 Claude Code 的提示词体系本身是英文的，两者结合后，你用中文提需求、它用英文思考、再输出中文结果，这个链路实际跑下来是通的。

当然也有代价，后面会详细讲：上下文窗口小一些、复杂多步工具调用的成功率略低一些、超长任务的规划能力弱一些。知道边界在哪，用起来才不会失望。

1.3 方案选型：两条接入路线的取舍

市面上能走通的路，本质上就两条。

我建议先走 A。它只依赖环境变量，不引入任何额外进程，出问题时排查面很窄。等 A 路线跑顺了，如果还想接别家的服务，再上 B 路线。很多人一上来就搞 B，结果调不通时分不清是转换层写错了还是客户端配置错了，白白耗掉半天。

还有一条我不推荐但确实存在的路线：用 WSL 跑 Linux 版。它在某些场景下确实更贴近官方设计，代价是文件系统跨了一层，项目文件放在/mnt/c/下时 I/O 慢得让人难受，而且 Windows 侧的工具链和 WSL 侧的工具链要各维护一套。除非你本来就在 WSL 里开发，否则原生 Windows + Git Bash 这条路更省事。

2. Windows 环境准备：那些官网一句话带过的东西

环境准备这块，官方文档通常只有两三行，但实际卡住新手的恰恰是这里。Windows 和 macOS、Linux 最大的差别在于：它默认没有 bash，而 Claude Code 的很多内部操作（比如执行 shell 命令、处理路径）是围绕 bash 语义设计的。所以"装个 Node.js 就完事"这个认知是错的，你至少还需要一个 bash 环境。

我在一台全新装的 Win11 上完整走过一遍流程，从零到敲出claude命令，纯手工操作大概花了二十分钟，其中一半时间花在等安装包和重启终端上。下面按顺序拆开讲。

2.1 Node.js 与 npm 的正确装法

先说版本。Claude Code 要求 Node.js 18 以上，我实测用 20 LTS 和 22 LTS 都没问题，18.x 也能跑但个别依赖会告警。不要用太老的 16.x，npm 的某些行为不一致，装包阶段就可能失败。

安装方式我推荐直接用官方安装包（.msi），而不是用 nvm-windows 或 chocolatey。原因很实际：这台机器上你大概率还要跑别的 Node 项目，但 Claude Code 是全局安装的命令行工具，用系统级 Node 最不容易出"换了个 Node 版本命令就找不到了"的问题。如果你确实需要多版本共存，那用 nvm-windows 也行，但要注意全局包是跟着具体版本走的，切换版本后需要重装一遍。

安装时有一个选项要注意： installer 里有个 "Automatically install the necessary tools" 的勾选项，它会把 Python、Visual Studio Build Tools 一起装上，体积好几个 G。如果你不打算编译原生模块，这一项可以不勾，能省下大量时间和磁盘。Claude Code 的依赖里没有必须现场编译的部分，跳过没问题。

装完之后打开一个新的终端窗口，验证：

node -v npm -v

两个命令都要能输出。如果提示"不是内部或外部命令"，说明 PATH 没刷新，关掉所有终端窗口重开一个，还不行就重启。Windows 的环境变量在进程启动时读取，已经打开的终端不会自动感知变化，这是新手最常踩的第一个坑。

2.2 Git for Windows 为什么是必需品

这一条很多人会忽略。Claude Code 在 Windows 上需要一个可用的 bash，而 Git for Windows 自带 Git Bash，正好补上这个缺口。你不需要真的用 git 命令，但那个 bash.exe 是刚需。

去 Git 官网下载 Windows 版安装包，一路下一步即可，注意安装选项里有一页是"Adjusting your PATH environment"，默认选项（Git from the command line and also from 3rd-party software）就行，它会把 git 加到 PATH 里。另一页 "Choosing the default editor used by Git"，如果你的机器上没装 vim 也没有 VS Code，把它改成 Notepad，否则某些场景下会弹出一个你完全不会操作的编辑器，卡在那里不知道怎么办。

装完验证：

git --version where bash

where bash应该输出类似C:\Program Files\Git\bin\bash.exe的路径。如果输出的是C:\Windows\System32\bash.exe，那是 WSL 的 bash，路径不对，需要显式指定。这时候可以设一个环境变量告诉 Claude Code 去哪儿找：

[Environment]::SetEnvironmentVariable("CLAUDE_CODE_GIT_BASH_PATH", "C:\Program Files\Git\bin\bash.exe", "User")

这个变量不是所有版本都需要，但设上没坏处，能避免一类很隐蔽的启动失败。我遇到过一台机器，启动后直接退出，没有任何错误提示，查了很久才发现是 bash 路径解析到了错误的位置。

2.3 终端选择与字符编码设置

终端我建议用Windows Terminal，而不是老的 cmd 或者 PowerShell 独立窗口。原因有三：它支持多标签、支持 UTF-8 显示中文路径不乱码、可以给 Git Bash 单独配一个 profile。Win11 自带，Win10 可以去商店装。

字符编码是个容易被忽略的细节。Claude Code 输出里会带一些框线字符和进度提示，如果终端编码不是 UTF-8，屏幕上会是一堆问号和方块，虽然不影响功能，但你根本看不清它在干什么。在 Windows Terminal 里默认就是 UTF-8，不需要额外设置。如果坚持用老 cmd，先执行：

chcp 65001

这行把当前代码页切成 UTF-8，只对当前窗口有效。要永久生效比较麻烦，不建议折腾，换终端更省事。

还有一点：不要用管理员权限的终端跑 Claude Code。它会执行模型生成的 shell 命令，虽然模型本身有安全约束，但用管理员权限跑等于把所有防护都拆了。日常开发用普通权限，遇到需要提权的操作单独开窗口做。

3. 安装 Claude Code 并让命令真正可用

环境备齐之后，安装本身只有一行命令。但从"装完"到"能敲出来"之间，Windows 上还有一道坎：全局 npm 包的路径默认在一个用户目录下，这个目录往往不在 PATH 里。这是绝大多数"装完提示找不到命令"的根因。

3.1 全局安装与 npm 前缀规划

标准安装命令：

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

装的过程大概几十秒到两分钟，取决于网络。如果卡在某个包上下载不动，可以换国内镜像源：

npm config set registry https://registry.npmmirror.com

装完之后先别急着敲claude，先看看它装到哪了：

npm config get prefix npm root -g

npm root -g会告诉你全局包的实际目录，比如C:\Users\你的用户名\AppData\Roaming\npm\node_modules。那么可执行文件（.cmd 包装脚本）就在上一级，也就是C:\Users\你的用户名\AppData\Roaming\npm。这个目录必须在 PATH 里，否则你在任何地方敲claude都会提示找不到。

我建议显式设置一下 prefix，把它固定到一个没有空格、没有中文的路径，比如D:\dev\npm-global：

npm config set prefix "D:\dev\npm-global"

然后再执行安装。这么做的好处是：以后所有全局包都在一个你完全掌控的目录里，备份、迁移、清理都方便；而且避开了用户目录名带中文或空格导致的路径解析问题——我见过用户名是中文的机器，某些工具在处理含中文的路径时会出各种诡异错误。

3.2 环境变量 PATH 的落地配置

设置 PATH 有两种方式。图形界面：Win + R 输入sysdm.cpl，高级 → 环境变量 → 用户变量里找到 Path → 编辑 → 新建 → 粘贴你的全局 npm 目录。命令行方式（PowerShell，需要普通权限即可）：

$oldPath = [Environment]::GetEnvironmentVariable("Path", "User") $newPath = $oldPath + ";D:\dev\npm-global" [Environment]::SetEnvironmentVariable("Path", $newPath, "User")

注意这里用的是SetEnvironmentVariable而不是setx。setx有个坑：它会把超过 1024 字符的值截断，PATH 长了就会丢内容，导致一堆原本正常的命令突然失效。这个坑我踩过一次，花了半小时才反应过来是 PATH 被截断了。

改完之后必须重开终端，已经开着的窗口读的还是旧 PATH。重开后验证：

where claude claude --version

where能定位到路径、--version能输出版本号，这一步才算真正过了。

3.3 首次启动与最小验证

第一次运行claude，它会做一轮初始化：检查配置文件目录（默认在C:\Users\你的用户名\.claude）、确认几项基础设置。这个阶段如果它提示你登录 Anthropic 账号，先别管，因为我们一会儿要用环境变量把后端切走。直接 Ctrl+C 退出即可。

有一个诊断命令值得记住：

claude doctor

它会打印当前环境的关键信息：Node 版本、安装路径、配置文件位置、检测到的 shell、网络连通性等。出任何问题，先跑这个。它给出的信息比你自己一条条试要快得多，尤其是判断"是环境问题还是配置问题"的时候。

如果你想在一个干净的项目里试，可以建个空目录进去跑：

mkdir D:\dev\sandbox && cd D:\dev\sandbox claude

在空目录里它不会读到乱七八糟的项目文件，行为最可预测。

4. 接入 DeepSeek：环境变量与配置文件的完整写法

这一节是整篇的核心。原理其实一句话能说完：Claude Code 从几个环境变量里读后端地址和密钥，你把这几个变量指向 DeepSeek 的兼容端点，它就走那条路。但每个变量的含义、取值边界、优先级，值得展开讲清楚，因为配错了往往表现为"能连上但结果诡异"这种难查的症状。

4.1 兼容端点的原理与验证顺序

服务方提供的 Anthropic 兼容端点，做的事情是在协议层做适配：接收 Anthropic 格式的请求体（包含model、messages、tools、system等字段），在内部转换成自家模型的调用格式，再把结果按 Anthropic 的响应结构返回，包括流式事件的顺序、工具调用的字段名。只要这层映射做得完整，客户端是完全无感的。

验证顺序我建议这样走，从下往上：

1. 先确认密钥可用。用最简单的 curl 打一次，看返回是不是 200，是不是正常的 JSON。这一步排除密钥问题。
2. 再确认端点路径。兼容端点的路径通常带一个后缀，比如/anthropic，少写这一段会 404，多写一个斜杠有时也会 404。
3. 最后才上客户端。客户端报的错往往被包装过，不如裸请求直接。

裸请求示例（PowerShell 里 curl 是别名，用curl.exe更保险）：

curl.exe https://api.deepseek.com/anthropic/v1/messages ^ -H "content-type: application/json" ^ -H "x-api-key: 你的密钥" ^ -H "anthropic-version: 2023-06-01" ^ -d "{\"model\":\"deepseek-chat\",\"max_tokens\":64,\"messages\":[{\"role\":\"user\",\"content\":\"说一句你好\"}]}"

能拿到带content数组的 JSON，说明服务端这层是通的。拿不到就先把错误码贴出来查，别往下走。

4.2 四组核心环境变量的含义与取值

几个细节必须说清楚，每一条都对应我踩过的坑。

ANTHROPIC_BASE_URL不要带尾部的/v1或/v1/messages。客户端会在后面按需拼接路径，你多写一段就变成/anthropic/v1/v1/messages，直接 404。这个错误我第一次配的时候犯了，报错信息只说"请求失败"，完全看不出是路径问题。

ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY是两个不同的变量，前者发的是Authorization: Bearer xxx，后者发的是x-api-key: xxx。有些兼容端点只认其中一种。如果配了API_KEY报 401，换成AUTH_TOKEN试试，反之亦然。这个差异文档里经常不写，只能靠试。

ANTHROPIC_SMALL_FAST_MODEL容易被忽略，但很实用。Claude Code 在后台有一堆"小活"——给会话起个标题、判断你的输入是不是要退出、压缩上下文摘要等等。这些活不需要强模型，用便宜的同款模型就行，甚至可以指到一个更轻量的模型上省钱。不配这个变量的话，它可能回落到默认模型名，而那个名字在你的服务方可能不存在，导致后台任务静默失败。

还有一个可选但很有用的：API_TIMEOUT_MS。默认超时对长任务来说可能偏短，尤其是让它读一堆文件再思考的时候。设成600000（10 分钟）能少掉很多莫名其妙的"请求超时"。

4.3 三种配置方式的取舍

方式一：临时会话级（PowerShell）

$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" $env:ANTHROPIC_AUTH_TOKEN="sk-你的密钥" $env:ANTHROPIC_MODEL="deepseek-chat" $env:ANTHROPIC_SMALL_FAST_MODEL="deepseek-chat" claude

只对当前窗口有效，关掉即失效。适合临时切一下试试，或者你有多个密钥想按需切换。缺点是每次开新窗口都得重贴一遍。

方式二：用户级永久（推荐）

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL","https://api.deepseek.com/anthropic","User") [Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN","sk-你的密钥","User") [Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL","deepseek-chat","User") [Environment]::SetEnvironmentVariable("ANTHROPIC_SMALL_FAST_MODEL","deepseek-chat","User")

设完重开终端生效。优点是一劳永逸，缺点是密钥会以明文存在用户环境变量里，机器被共用时有风险。如果是个人专用机，这样最省心；如果是共享机器，走方式三。

方式三：项目级配置文件

在项目根目录建.claude/settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic", "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥", "ANTHROPIC_MODEL": "deepseek-chat", "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat", "API_TIMEOUT_MS": "600000" } }

这个文件里的env会作为进程环境变量注入。好处是配置跟着项目走，切项目自动切配置；坏处是千万别把它提交到仓库里。记得在.gitignore里加一行.claude/settings.local.json，密钥写在这份 local 文件里，共享的settings.json只放非敏感配置。

注意：环境变量的优先级是 进程级 > 用户级 > 配置文件。如果你在用户级设了 A 密钥，又在项目文件里写 B 密钥，最后生效的是 A。排查"为什么改了配置没反应"时，先想想是不是被更高优先级的变量盖住了。

4.4 用 settings.json 做项目级托管

配置文件其实能干的不止设环境变量。还能加目录白名单、禁用某些工具、挂 hooks。举个例子，如果你不想让它自动执行 bash 命令（保守用法），可以这样：

{ "permissions": { "allow": ["Read", "Glob", "Grep"], "deny": ["Bash"] } }

这样它只能读文件、搜文件，不能执行命令。适合刚开始不放心、想先观察它行为模式的阶段。等熟悉了再逐步放开。

还有一种常见需求：某个项目想用强一点的模型，另一个项目想省钱。那就分别在各自项目的.claude/settings.json里写不同的ANTHROPIC_MODEL，互不干扰。这比每次手工改环境变量优雅得多。

5. 实测流程：从零到跑通一次完整对话

配置写完，必须靠实际跑一遍来验证。这一节我按自己的操作顺序走一遍，每一步都说明该看什么、看到什么算过。

5.1 验证清单与逐步操作

第一步，确认变量真的进到进程里了。开一个新的 PowerShell，执行：

echo $env:ANTHROPIC_BASE_URL echo $env:ANTHROPIC_MODEL

能回显就说明进程读到了。这一步跳过的人特别多，后面排查时才发现变量压根没生效。

第二步，进项目目录启动。

cd D:\dev\sandbox claude

正常的话会看到一个欢迎界面，底部有个输入框。如果它弹出来让你登录 Anthropic 账号，说明后端地址没读到——它在尝试走默认路径。这时候退出去，回到第一步查变量。

第三步，问一个跟项目无关的问题。

你好，用一句话介绍一下你自己

这一步验证的是纯文本通道。能在几秒内返回，说明网络、鉴权、模型名三样都对。如果报 401，是密钥问题；报 404，是地址路径问题；报"model not found"，是模型名问题；一直转圈不返回，多半是超时或者流式解析卡住。

第四步，问一个跟项目相关的问题。

这个目录里有哪些文件？分别是什么用途？

这一步验证的是工具调用通道：它需要调用列目录和读文件的能力。如果它能正确列出文件，说明工具调用链路通了；如果它只是"说"有文件但列不出来，或者反复重试，说明工具调用返回的格式没被正确解析——这是兼容层最容易出问题的地方。

第五步，让它做一次最小的修改。

在当前目录新建一个 hello.py，内容是打印 1 到 10 的平方

它应该会请求写入权限（首次会问），确认后生成文件。然后你自己type hello.py看一眼内容对不对。

这五步走完，整套链路就算通了。任何一步失败，都定位到了具体层次，不用满世界乱试。

5.2 一次真实的代码修改任务

我用一个真实点儿的场景跑一遍，让你有直观感受。假设有个小项目，里面有个utils.py，函数这么写的：

def calc_total(items): total = 0 for i in items: total += i return total

我输入：

utils.py 里的 calc_total 有个问题：如果 items 里有字符串会直接报错。 帮我加上类型校验，非数字的元素跳过并打印一条警告，同时补一个 pytest 测试把这两种情况都覆盖到。

它会做这些事：先读utils.py，可能在项目里搜一下有没有相关调用方，然后给出一个 diff 预览让我确认，确认后写入文件，接着创建测试文件，最后可能主动跑一次 pytest 看通过与否。整个循环大概十几到几十秒，具体看我给的约束清不清楚。

这里有个体感上的差别要提醒：换成性价比模型后，它对多步骤任务的规划不如高阶模型那么一次到位。上面这个需求其实有三件事（改函数、加警告、写测试），高阶模型通常一趟走完；性价比模型有时会先只改函数，改完停下来等你说下一步。这不是故障，是能力边界。应对办法是把需求拆得更明确，或者直接说"把这三件事都做完再给我看"，用更显式的指令补上规划能力的差距。

5.3 观察用量与成本

跑完之后看看花了多少。Claude Code 里有个/cost命令能看当前会话的 token 用量（具体显示什么取决于服务方是否返回用量字段）。如果兼容端点返回了usage信息，这里会有数。

我从自己的使用记录里总结了一个粗略的量级感：一个"读三四个文件、改一处逻辑、补一个测试"的任务，累计输入 token 通常在一两万到四五万之间，输出在一两千。这个比例很有意思——输入远大于输出。原因就是前面说的循环结构：每一轮都要把之前的上下文重新发一遍。

所以省钱的杠杆不在"让它少说话"，而在"让它少读"。具体怎么控制，第 8 节展开。

6. 备选路线：本地转换服务打通其他 OpenAI 格式服务

如果服务方只提供 OpenAI 格式接口，没有 Anthropic 兼容端点，就得自己架一层转换。这一节给一个最小可用的实现思路，不追求生产级，够跑通就行。

6.1 什么情况下需要它

判断标准很简单：拿第 4.1 节那个 curl 请求打过去，如果返回的是{"error": ...}或者明显不是 Anthropic 的响应结构，就说明没有兼容端点。另一种情况是返回了 200，但content数组里没有tool_use类型的块——那说明工具调用没做映射，实际用起来会一直卡在第 4 步。

这条路线还有一类顺便的好处：可以在转换层做点小手脚，比如统一注入 system 提示、给请求打日志方便排查、按关键词做简单的路由（简单问题走便宜模型，复杂问题走高阶模型）。这些在纯环境变量方案里是做不到的。

6.2 最小可用的转换服务搭建

思路：起一个本地 HTTP 服务，监听一个端口，接收/v1/messages的 POST 请求，把 body 里的 Anthropic 结构转成 OpenAI 的chat/completions结构，转发出去，再把返回流转回 Anthropic 的事件格式。

// server.js —— 最小转换层，仅作思路参考 const http = require('http'); const UPSTREAM = 'https://你的服务方地址/v1/chat/completions'; const API_KEY = '你的密钥'; function toOpenAI(body) { const messages = []; if (body.system) messages.push({ role: 'system', content: body.system }); for (const m of body.messages || []) { if (typeof m.content === 'string') { messages.push({ role: m.role, content: m.content }); } else { const text = m.content .filter(b => b.type === 'text') .map(b => b.text) .join('\n'); messages.push({ role: m.role, content: text }); } } return { model: body.model, messages, stream: false }; } const server = http.createServer(async (req, res) => { if (!req.url.startsWith('/v1/messages')) { res.writeHead(404).end('not found'); return; } let raw = ''; req.on('data', c => (raw += c)); req.on('end', async () => { const body = JSON.parse(raw); const upstreamRes = await fetch(UPSTREAM, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${API_KEY}` }, body: JSON.stringify(toOpenAI(body)) }); const data = await upstreamRes.json(); const text = data.choices?.[0]?.message?.content || ''; res.writeHead(200, { 'content-type': 'application/json' }); res.end(JSON.stringify({ id: 'msg_local', type: 'message', role: 'assistant', content: [{ type: 'text', text }], stop_reason: 'end_turn', usage: { input_tokens: 0, output_tokens: 0 } })); }); }); server.listen(8787, '127.0.0.1', () => { console.log('listening on 127.0.0.1:8787'); });

启动：node server.js，然后把ANTHROPIC_BASE_URL指到http://127.0.0.1:8787。

必须说明的是，上面这个版本只够验证文字通道。它把tools字段直接丢掉了，也没处理流式返回。真实要用，得补两块：一是把 Anthropic 的tools转成 OpenAI 的functions格式，并把返回的tool_calls再转回tool_use块；二是实现 SSE 流式输出，让客户端能边收边显示。这两块是工作量的大头，也是坑最多的部分——字段名一个字母不对，客户端就解析不了。

我踩过的具体坑：OpenAI 的tool_calls[].function.arguments是个JSON 字符串，而 Anthropic 的tool_use.input是个对象。忘了做JSON.parse就会得到一个字符串，客户端根本没法用。反过来，发给上游时要把对象序列化成字符串。这个来回转换写错了，表现就是"模型说它要改文件，但客户端完全没反应"。

建议：如果你只是为了接一个服务跑通，先看看服务方有没有官方兼容端点，有就别自己写。转换层这种东西，写起来半天，调通可能要两天。

7. 常见问题与排查速查表

这一节是血泪总结。按"出问题的层次"分类，比按错误信息分类更好用，因为错误信息经常被包装得面目全非。

7.1 启动类问题：命令找不到、闪退

现象：敲claude提示"不是内部或外部命令"。先where claude，看看有没有输出。没有的话就是 PATH 问题，回到 3.2 节。有输出但版本号不对，说明机器上装了多个版本，where会按顺序列出所有，注意看第一个是哪个。

现象：启动后立刻退出，没有任何提示。九成是 bash 路径问题。设CLAUDE_CODE_GIT_BASH_PATH指向 Git Bash 的bash.exe，重开终端再试。另一个可能是杀毒软件拦截了进程创建——某些安全软件对"程序突然调用 shell"这个行为比较敏感，把它加进白名单即可。

现象：卡在启动画面不动。可能是它在检查更新，网络慢就会卡。等等看，或者断网启动试试（能启动就说明是更新检查的问题）。也可能是配置文件损坏，把C:\Users\你的用户名\.claude整个目录备份后删掉，让它重新初始化。

现象：装了但启动报 Node 版本错误。检查是不是装了多个 Node，命令解析到了老版本。node -v和where node一起看，确认用的是你想用的那个。

7.2 鉴权与模型类问题：401、404、模型不存在

401 Unauthorized。三种可能：密钥打错了（注意首尾空格，复制时经常带一个）、密钥类型不对（AUTH_TOKEN和API_KEY的区别，见 4.2 节）、密钥余额不足或已失效。先拿 curl 裸打一次确认。

404 Not Found。几乎都是地址拼错。检查三处：BASE_URL尾部有没有多余的斜杠；有没有把/v1/messages也写进去；路径后缀（比如/anthropic）有没有漏。我用过的一个服务，端点后缀是/anthropic，但文档里写的位置很不起眼，我照着"通用写法"试了半小时才找到。

400 参数错误。常见原因是max_tokens超过服务方上限。Claude Code 默认请求的输出长度可能比兼容端点的上限大，某些实现会直接拒掉。如果转换层是你自己写的，可以在这里夹一下：max_tokens: Math.min(body.max_tokens, 8192)。

"model not found"。模型名写错了。ANTHROPIC_MODEL和ANTHROPIC_SMALL_FAST_MODEL两个都要检查，后者经常被忘掉，导致主对话正常但后台任务静默失败。

7.3 上下文与工具调用类问题

现象：长任务跑到一半报"上下文超限"。这是接入性价比模型最典型的限制。Claude 系列动辄 200K 上下文，而多数性价比模型的窗口小得多。Claude Code 在有大量文件被读入时会迅速堆高输入长度。应对：用/clear定期清空会话；只让它读必要的文件而不是"把整个项目看一遍"；用.claudeignore排除 node_modules、构建产物、日志目录这类噪声。

现象：它反复说要改文件，但文件始终没变。工具调用解析失败，客户端在重试。先跑claude doctor看有没有工具相关告警，然后检查兼容端点有没有返回tool_use块。如果是走本地转换层，重点查input字段的类型是不是对象而不是字符串。

现象：它一直在自我循环，同一个命令跑好几遍。模型对"上一步的结果算不算成功"判断不准，尤其在输出被截断时。可以让它换个说法重来，或者直接告诉它"刚才那步已经成功了，往下走"。这是能力边界问题，不是配置问题，靠调参数解决不了。

现象：中文输出乱码或显示成方块。终端编码问题，换 Windows Terminal 或chcp 65001。

7.4 问题速查表

8. 成本控制与日常使用心得

配置跑通只是开始，用一段时间之后你会发现，真正影响体验的不是"能不能连上"，而是"钱花得值不值、任务干得顺不顺"。这一节聊几个我实际用下来觉得最有价值的习惯。

8.1 token 到底花在哪了

前面提过输入远大于输出。拆开看，输入主要来自三块：系统提示词（固定开销，每轮都有）、项目上下文（读进来的文件内容）、对话历史（前面的所有轮次）。其中项目上下文是最大的变量，也是最容易失控的。让它"看一下这个项目"，它可能一口气读几十个文件，几十万 token 就这么没了，而真正有用的可能只有三个。

我的做法是主动收窄范围。不说什么"看看这个项目"，而是说"看一下src/parser.py里parse_tokens这个函数"。指定到文件和函数级别，输入量能降一个数量级。另一个习惯是长会话定期重开——同一件事聊了二三十轮之后，历史累积的输入开销已经很大了，不如把结论写成一条简短说明，开新会话时直接贴进去。

8.2 CLAUDE.md 与上下文管理

项目根目录放一个CLAUDE.md，这个文件会被自动读取，相当于给模型的"项目说明书"。这是我觉得性价比最高的一个投入——花十分钟写，后面每次交互都能省下大量解释成本。

写什么？不用长。项目是干什么的、目录结构大致怎么分、用什么技术栈、跑测试的命令是什么、有哪些约定俗成的写法（比如错误处理统一用什么方式、日志用哪个库）、有哪些绝对不能碰的目录。这些信息如果能自动带进去，模型就不用每次都问或者每次乱猜。

一个我自己的模板大概长这样：

# 项目说明 ## 技术栈 Python 3.11 + FastAPI + pytest ## 目录 - `app/` 业务代码 - `tests/` 测试，命名规则 test_*.py - `scripts/` 一次性脚本，不需要测试覆盖 ## 约定 - 所有外部调用必须带超时 - 日志统一用 `app.logger`，不要 print - 数据库操作走 repository 层，不要在路由里直接写 SQL ## 禁止 - 不要修改 `migrations/` 下的历史文件 - 不要动 `.env` 和任何配置文件里的密钥

有了这个，你后面说"加个接口"它就大概率按你的约定来，不用每次重申。

8.3 密钥安全与权限边界

最后说几件容易被忽略但后果不小的事。

密钥永远不要硬编码进代码、不要写进会被提交的文件。走环境变量或者.claude/settings.local.json，并且确保这个文件在.gitignore里。如果密钥曾经被提交过，哪怕后来删了，git 历史里还在，去服务方后台轮换一把最省心。

不要用管理员权限跑。工具会执行模型生成的命令，权限越高风险越大。日常开发用普通权限，需要提权的操作自己手动做。

对不熟悉的项目，先从只读权限开始。前面给过permissions的配置示例，先限定Read、Glob、Grep，观察几轮它的行为模式，确认靠谱了再放开Bash和Write。这个习惯在接手别人的代码库时尤其重要——你不知道里面有什么脚本，模型也不知道，万一它觉得"跑一下这个脚本看看"是合理的，后果就不可控了。

还有一点：涉及生产配置、数据库连接串、带有真实数据的文件，用.claudeignore显式排除掉。它读进来的内容会成为上下文的一部分，发到服务方那边去。这一点在接入第三方 API 时尤其要想清楚。

这套组合我用了几个月，最实在的一条体会是：把它当成一个执行力很强但需要明确指令的实习生用，而不是当成一个能猜你想法的搭档。指令越具体、约束越清晰、边界划得越死，跑出来的结果越接近预期。反过来，丢一句模糊的需求进去，然后抱怨它做得不对，那问题多半不在模型上。