Claude Code安装配置实战：Windows下接入Anthropic兼容网关与自定义模型

从"环境里有没有 Node.js"到"端到端测试返回 OK"，一次完整走通，顺带记录一个只有自建网关才会遇到的模型名陷阱。

前言

很多团队会把大模型能力收口到自建网关里统一分发，开发者手上的工具只要支持 ANTHROPIC_BASE_URL 之类的环境变量，就能指向内部网关。

Claude Code CLI 就是这么个工具。本文还原一次真实的 Windows 环境安装配置过程：装 CLI、接自建网关、配自定义模型、跑通测试，以及处理那个只在自建网关场景才会暴露的 [1m] 后缀问题。

文中所有网关地址、模型名、用户目录、文件路径均已做脱敏替换，实际使用时换成你自己的即可。

一、环境准备：Node.js 版本够不够

Claude Code 对 Node 的要求是 ≥ 18。先确认：

node --version
npm --version

本次实测环境是 v24.14.0 / 11.9.0，远高于下限，不需要重装 Node.js。

如果你本机版本低于 18，去 Node.js 官网下 LTS 安装包即可，装完记得重开终端让 PATH 生效。

二、安装 Claude Code

一条命令全局安装：

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

安装成功的输出形如 changed 2 packages in 4s。验证一下：

claude --version
# 2.1.263 (Claude Code)

踩坑点：这个安装耗时可能到几十秒，如果在 AI 助手或 CI 里执行，容易被判定"超时跳过"。跳过了也没关系——再执行一次就行，或者干脆自己开个终端跑，命令是幂等的。

三、接入自建网关：改 settings.json

Claude Code 的用户级配置文件在：

C:\Users\<你的用户名>\.claude\settings.json

文件默认不存在，直接新建。核心是在 env 里塞三项：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
    "ANTHROPIC_MODEL": "your-model-name",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_AUTH_TOKEN_HERE"
  }
}

三项各自的作用：

凭据这一项建议留占位符，由使用者自己填。 配置文件里写死 token 容易随文档流传出去，把 YOUR_AUTH_TOKEN_HERE 当成"待填清单"反而更安全。

四、测试：一条 headless 命令验证全链路

不用进交互界面，一条命令就能验证"网关 + 认证 + 模型"整条链路：

claude -p "Reply with exactly: OK" --output-format text

返回 OK 就说明通了。

4.1 那个[1m]后缀警告

实测中，返回 OK 的同时还夹了一条警告：

[claude-code:unrecognized_model] {"model":"your-model-name[1m]","query_source":"generate_session_title"}

原因是：Claude Code 在自动生成会话标题这个后台任务里，会给模型名追加 [1m] 后缀（1m = 100 万上下文）。官方端点认这个后缀，自建网关通常不认，于是报 unrecognized_model。

影响范围：只有"自动标题生成"会失败，正常对话完全不受影响。

注意：排查时容易顺手把 ANTHROPIC_MODEL 也改成带 [1m] 的样子，想着"和报错里的名字对齐"。不要这么做——配置项里就该写干净的 your-model-name，后缀是 CLI 内部自己加的，写进去只会让主对话也挂。

五、启动与常用命令

会话内常用的斜杠命令：/help、/clear、/model、/exit。

建议习惯：cd 到项目根目录再启动。Claude Code 的上下文是围绕当前工作目录建的，在错误目录里启动，它能看到的代码就不对。

六、复盘：这件事的推进顺序

回看整个过程，其实是一条很标准的"配置类任务"推进线，值得提炼成套路：

1. 先确认环境，再动手装——版本不满足就先解决版本，别装完再返工；
2. 装完立刻验证——--version 是成本最低的确认；
3. 配置与凭据分离——配置可以代劳，凭据必须本人填；
4. 用最小命令做端到端验证——Reply with exactly: OK 这种原子化测试，能把"是网关错、认证错还是模型错"压缩成一次判断；
5. 遇到警告先划分影响面——判断"影响 A 不影响 B"比"消除警告"更重要，别为了消警告改坏正确配置；
6. 最后输出教程——把过程固化下来，下一个人不用再走一遍。

七、结论

• Node.js ≥ 18 即可，本机版本够就别折腾重装。
• npm install -g @anthropic-ai/claude-code 全局安装，用 claude --version 验证。
• 自建网关只需配 settings.json 里的 env 三项，凭据留占位符由使用者自填。
• claude -p "Reply with exactly: OK" --output-format text 是最省事的端到端测试。
• [1m] 后缀导致的 unrecognized_model 只影响自动会话标题，不要为此修改 ANTHROPIC_MODEL。
• cd 到项目目录再启动，否则上下文拿到的代码是错的。

到此这篇关于Claude Code安装配置实战：Windows下接入Anthropic兼容网关与自定义模型的文章就介绍到这了,更多相关Claude Code安装配置实战内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！

最新评论