从"环境里有没有 Node.js"到"端到端测试返回 OK"，一次完整走通，顺带记录一个只有自建网关才会遇到的模型名陷阱。
前言
很多团队会把大模型能力收口到自建网关里统一分发，开发者手上的工具只要支持 ANTHROPIC_BASE_URL 之类的环境变量，就能指向内部网关。
Claude Code CLI 就是这么个工具。本文还原一次真实的 Windows 环境安装配置过程：装 CLI、接自建网关、配自定义模型、跑通测试，以及处理那个只在自建网关场景才会暴露的 [1m] 后缀问题。
文中所有网关地址、模型名、用户目录、文件路径均已做脱敏替换，实际使用时换成你自己的即可。
一、环境准备：Node.js 版本够不够
Claude Code 对 Node 的要求是 ≥ 18。先确认：
|
1 2 |
node --version npm --version |
本次实测环境是 v24.14.0 / 11.9.0，远高于下限，不需要重装 Node.js。
如果你本机版本低于 18，去 Node.js 官网下 LTS 安装包即可，装完记得重开终端让 PATH 生效。
二、安装 Claude Code
一条命令全局安装：
|
1 |
npm install -g @anthropic-ai/claude-code |
安装成功的输出形如 changed 2 packages in 4s。验证一下：
|
1 2 |
claude --version # 2.1.263 (Claude Code) |
踩坑点：这个安装耗时可能到几十秒，如果在 AI 助手或 CI 里执行，容易被判定"超时跳过"。跳过了也没关系——再执行一次就行，或者干脆自己开个终端跑，命令是幂等的。
三、接入自建网关：改 settings.json
Claude Code 的用户级配置文件在：
|
1 |
C:\Users\<你的用户名>\.claude\settings.json |
文件默认不存在，直接新建。核心是在 env 里塞三项：
|
1 2 3 4 5 6 7 |
{ "env": { "ANTHROPIC_BASE_URL": "https://your-gateway.example.com", "ANTHROPIC_MODEL": "your-model-name", "ANTHROPIC_AUTH_TOKEN": "YOUR_AUTH_TOKEN_HERE" } } |
三项各自的作用：
| 配置项 | 作用 |
|---|---|
| ANTHROPIC_BASE_URL | 把请求打到自建网关，而不是官方端点 |
| ANTHROPIC_MODEL | 指定网关背后的具体模型 |
| ANTHROPIC_AUTH_TOKEN | 认证凭据，由网关方分发 |
凭据这一项建议留占位符，由使用者自己填。 配置文件里写死 token 容易随文档流传出去，把 YOUR_AUTH_TOKEN_HERE 当成"待填清单"反而更安全。
四、测试：一条 headless 命令验证全链路
不用进交互界面，一条命令就能验证"网关 + 认证 + 模型"整条链路：
|
1 |
claude -p "Reply with exactly: OK" --output-format text |
返回 OK 就说明通了。
4.1 那个[1m]后缀警告
实测中，返回 OK 的同时还夹了一条警告：
|
1 |
[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 内部自己加的，写进去只会让主对话也挂。
五、启动与常用命令
| 用法 | 命令 |
|---|---|
| 进入交互式对话 | 先 cd 到项目目录，再运行 claude |
| 一次性提问 | claude "问题" |
| print 模式（非交互，直接输出结果） | claude -p "问题" |
| 继续上一次会话 | claude -c |
| 恢复历史会话 | claude --resume |
会话内常用的斜杠命令：/help、/clear、/model、/exit。
建议习惯：cd 到项目根目录再启动。Claude Code 的上下文是围绕当前工作目录建的，在错误目录里启动，它能看到的代码就不对。
六、复盘：这件事的推进顺序
回看整个过程，其实是一条很标准的"配置类任务"推进线，值得提炼成套路：
- 先确认环境，再动手装——版本不满足就先解决版本，别装完再返工；
- 装完立刻验证——--version 是成本最低的确认；
- 配置与凭据分离——配置可以代劳，凭据必须本人填；
- 用最小命令做端到端验证——Reply with exactly: OK 这种原子化测试，能把"是网关错、认证错还是模型错"压缩成一次判断；
- 遇到警告先划分影响面——判断"影响 A 不影响 B"比"消除警告"更重要，别为了消警告改坏正确配置；
- 最后输出教程——把过程固化下来，下一个人不用再走一遍。
七、结论
- 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 到项目目录再启动，否则上下文拿到的代码是错的。
