从"环境里有没有 Node.js"到"端到端测试返回 OK"，一次完整走通，顺带记录一个只有自建网关才会遇到的模型名陷阱。
前言
很多团队会把大模型能力收口到自建网关里统一分发，开发者手上的工具只要支持 ANTHROPIC_BASE_URL 之类的环境变量，就能指向内部网关。
Claude Code CLI 就是这么个工具。本文还原一次真实的 Windows 环境安装配置过程：装 CLI、接自建网关、配自定义模型、跑通测试，以及处理那个只在自建网关场景才会暴露的 [1m] 后缀问题。
文中所有网关地址、模型名、用户目录、文件路径均已做脱敏替换，实际使用时换成你自己的即可。
一、环境准备：Node.js 版本够不够
Claude Code 对 Node 的要求是 ≥ 18。先确认：
bash
node --version
npm --version本次实测环境是 v24.14.0 / 11.9.0，远高于下限，不需要重装 Node.js。
如果你本机版本低于 18，去 Node.js 官网下 LTS 安装包即可，装完记得重开终端让 PATH 生效。
二、安装 Claude Code
一条命令全局安装：
bash
npm install -g @anthropic-ai/claude-code安装成功的输出形如 changed 2 packages in 4s。验证一下：
bash
claude --version
# 2.1.263 (Claude Code)踩坑点：这个安装耗时可能到几十秒，如果在 AI 助手或 CI 里执行，容易被判定"超时跳过"。跳过了也没关系------再执行一次就行，或者干脆自己开个终端跑，命令是幂等的。
三、接入自建网关：改 settings.json
Claude Code 的用户级配置文件在：
C:\Users\<你的用户名>\.claude\settings.json文件默认不存在，直接新建。核心是在 env 里塞三项：
json
{
"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 命令验证全链路
不用进交互界面，一条命令就能验证"网关 + 认证 + 模型"整条链路：
bash
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 内部自己加的，写进去只会让主对话也挂。
五、启动与常用命令
| 用法 | 命令 |
|---|---|
| 进入交互式对话 | 先 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到项目目录再启动，否则上下文拿到的代码是错的。
你所在的团队有没有自建模型网关？接入 AI 编程工具时踩过哪些坑，欢迎在评论区交流。