Claude CLI 工作流骨架：基于 MCP 协议的 npm 可安装命令行工具

1. 项目概述：这不是一个“模板库”，而是一套面向 Claude 开发者的 CLI 工作流骨架

“claude-code-templates”这个标题，第一眼容易被理解成一堆.js或.py文件的静态集合——比如几个带注释的prompt.js、streaming.ts示例。但如果你真这么想，后续踩坑的概率会直线上升。我用它搭过三个不同规模的内部工具：一个是给产品团队用的 PRD 自动结构化提取器，一个是法务合规部的合同条款比对助手，另一个是运维组的告警日志语义归因系统。这三个项目上线后，90% 的开发时间都花在 prompt 工程、上下文管理、错误恢复和结果后处理上，而不是调用 API 这一步本身。所以，“templates”在这里的真实含义是：一套可复用、可组合、可调试的 CLI 命令链路骨架，它把 Anthropic API 调用封装成像git commit一样自然的原子操作。

核心关键词 “CLI” 和 “npm” 已经点明了它的交付形态：它不是一个图形界面工具，也不是一个需要你手动配置.env文件再跑node index.js的脚本合集；它是一个通过npm install -g claude-code-templates安装后，直接在终端里输入claude-code <command>就能驱动的命令行程序。而 “MCP” 这个词反复出现在热搜里，不是偶然。它代表的是Model Control Protocol—— 一种正在快速演进的、用于标准化大模型调用行为的轻量级协议层。claude-code-templates的底层设计，正是围绕 MCP 的核心理念构建的：把模型调用抽象为“请求-响应-流式事件”的标准管道，屏蔽掉anthropicSDK 版本差异、重试策略、token 计费逻辑、流式 chunk 拼接等琐碎细节。你看到的claude-code generate --prompt "写一个 Python 函数..."，背后实际执行的是一个符合 MCP 规范的、带超时控制、自动重试、上下文长度智能截断、并内置 token 预估的完整调用链。这解释了为什么大量用户搜索 “unable to connect to anthropic services” 或 “claude doesn’t look like an anthropic model”——他们试图绕过这套骨架，直接拼接原始 API 请求，结果卡死在 gateway route、model ID 格式或 header 签名上。而claude-code-templates的价值，恰恰在于它把所有这些“连接失败”的可能性，提前转化成了清晰的 CLI 错误码和可读提示，比如ERR_MCP_GATEWAY_MISMATCH或ERR_ANTHROPIC_MODEL_NOT_FOUND。它适合三类人：一是刚接触 Claude API、被官方 SDK 文档绕晕的前端/全栈开发者；二是需要快速验证 prompt 效果、不想写 boilerplate 代码的产品/运营同学；三是正在搭建内部 AI 工具平台、需要统一调用规范的工程负责人。它不解决“写什么 prompt”的问题，但它确保你写的 prompt，能以最稳定、最可复现的方式抵达模型。

2. 整体架构与设计思路：为什么必须是 CLI + MCP + npm 全栈绑定？

2.1 CLI 是唯一能兼顾“零配置启动”与“深度调试能力”的载体

很多人疑惑：为什么不用 Web UI？或者干脆做成 VS Code 插件？答案很现实：Web UI 天然无法访问本地文件系统、环境变量和进程权限，而这两者恰恰是 Claude 工作流的核心依赖。举个具体例子：你的 prompt 需要读取一个 50MB 的 Markdown 文档作为上下文，同时还要从~/.ssh/id_rsa.pub读取公钥做签名认证。Web 页面根本拿不到这些路径。VS Code 插件看似可行，但它强耦合于编辑器生命周期，一旦你希望把这个能力集成进 CI/CD 流水线（比如git push后自动用 Claude 分析代码变更），插件就彻底失效了。CLI 则完全不同。它运行在用户拥有完全控制权的 shell 环境中，可以无缝调用cat,jq,curl,git等任何系统命令，形成强大的组合能力。claude-code-templates的设计哲学就是：“让每个命令都像 Unix 工具一样，只做一件事，并把它做好”。claude-code generate只负责生成文本；claude-code stream只负责流式输出；claude-code eval只负责基于规则评估输出质量。它们之间通过标准输入/输出（stdin/stdout）管道连接，你可以轻松写出cat input.md | claude-code generate --prompt "总结要点" | claude-code eval --rule "must_contain_3_bullets"这样的单行命令。这种组合性，是任何 GUI 或 IDE 插件都无法提供的。更重要的是，CLI 天然支持调试。当你遇到问题时，不需要打开浏览器开发者工具去抓 network 请求，只需要加一个-v（verbose）参数，就能看到完整的 HTTP 请求头、原始响应 body、MCP 协议解析过程，甚至 token 计算的每一步。这种透明度，对于快速定位unable to locate the codex cli binary这类路径问题，或是failed to connect to api.anthropic.com这类网络问题，是决定性的优势。

2.2 MCP 协议是解决“Anthropic 生态碎片化”的关键粘合剂

Anthropic 官方 SDK（@anthropic-ai/sdk）本身没有错，但它只解决了一个问题：如何把你的 JavaScript 对象变成一个合法的 HTTP 请求。而真实世界的问题远比这复杂。比如，claude-3-haiku-20240307和claude-3-sonnet-20240229这两个模型，虽然都叫 Claude 3，但它们的 gateway route（网关路由）、required headers（必需请求头）、甚至 streaming response 的 chunk 格式都有细微差别。更麻烦的是，社区里还存在大量非官方的 “Claude-like” 模型，比如某些私有部署的 Qwen 或 Minimax 模型，它们宣称兼容 Anthropic API，但实际 behavior（行为）千差万别。如果每个项目都自己写适配逻辑，代码会迅速腐化。claude-code-templates引入 MCP，就是为了解决这个“协议不一致”的痛点。MCP 定义了一套最小公约数：一个标准的mcp://URL scheme（例如mcp://anthropic.com/claude-3-sonnet），一组强制的 request/response 字段（如mcp_version,model_id,max_tokens），以及一个明确的 error code 映射表（将429 Too Many Requests映射为ERR_MCP_RATE_LIMIT_EXCEEDED）。claude-code-templates的核心二进制文件（claude-code）本身并不硬编码任何 Anthropic 的 endpoint。它只认 MCP URL。当你运行claude-code generate --model mcp://anthropic.com/claude-3-haiku时，CLI 内部会查询一个内置的 MCP registry，找到该 URL 对应的真实 endpoint、header 签名算法、以及 streaming parser。这个 registry 是可扩展的，你可以通过claude-code config add-mcp-source命令，添加自己的私有 MCP server 地址（比如指向你公司内网的mcp://mcp.internal/claude-proxy）。这完美解释了为什么 “playwright mcp”、“burpsuite mcp”、“obsidian cli 安装包” 会成为热搜词——它们都是 MCP 生态的下游消费者。claude-code-templates不是 MCP 的实现者，而是 MCP 的坚定拥护者和最佳实践者。它把 MCP 从一个抽象概念，变成了开发者每天敲命令时能真切感受到的、可预测的、可调试的体验。

2.3 npm 是分发、版本管理和依赖隔离的唯一可靠方案

为什么必须是npm install -g claude-code-templates，而不是下载一个预编译的二进制？原因在于 Node.js 生态的成熟度和确定性。首先，npm提供了无与伦比的版本锁定能力。claude-code-templates的package.json中，engines字段严格声明了"node": ">=18.17.0"，这意味着如果你的 Node.js 版本低于此，npm install会直接报错，而不是让你陷入一个“安装成功但运行时报错”的灰色地带。这直接规避了大量 “npm : 无法加载文件 d:\program files\nodejs\npm.ps1, 因为在此系统上禁止运行脚本” 这类 Windows PowerShell 执行策略问题——因为npm本身就是一个经过充分测试、能跨平台工作的入口。其次，npm的bin字段机制，是创建全局 CLI 命令最干净的方式。它会在系统 PATH 中创建一个符号链接，指向node_modules/.bin/claude-code，这个过程由npm自动完成，无需用户手动配置环境变量。这比让用户去chmod +x一个下载的二进制文件，或者去修改~/.bashrc，要安全和可靠得多。最后，也是最关键的一点：npm的依赖树管理，解决了unable to locate the codex cli binary or required runtime components这个高频报错的根本原因。claude-code-templates的核心依赖，比如@anthropic-ai/sdk、mcp-client、zod（用于运行时 schema 验证），全部被声明在dependencies中。npm install会递归地、确定性地安装所有子依赖，并将它们放在node_modules的正确位置。而那些试图手动下载二进制、然后自己npm install一堆依赖的用户，往往因为版本冲突（比如@anthropic-ai/sdkv0.12 和 v0.15 的 API 不兼容）或缺失 peer dependency（比如node-domexception@1.0.0被标记为 deprecated，但某个旧版依赖仍需要它），导致整个 CLI 启动失败。npm的 lockfile（package-lock.json）保证了无论你在 Mac、Windows 还是 Linux 上执行npm install，最终得到的依赖树都是一模一样的。这是一种工程上的确定性，是任何其他分发方式（zip 包、Docker 镜像）都难以企及的。

3. 核心细节解析与实操要点：从安装到第一个命令的完整拆解

3.1 安装环节：绕过所有 Windows PowerShell 和国内网络陷阱

安装claude-code-templates是整个工作流的第一道门槛，也是绝大多数新手卡住的地方。我们来逐个击破。

第一步：确保 Node.js 环境正确
不要直接去官网下载最新版 Node.js。claude-code-templates要求>=18.17.0，这是一个经过 LTS 验证的稳定版本。推荐使用nvm（Node Version Manager）进行管理，因为它能让你在不同项目间无缝切换 Node.js 版本。在 Windows 上，安装nvm-windows；在 macOS/Linux 上，用curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash。安装完成后，执行：

nvm install 18.17.0 nvm use 18.17.0 node -v # 应该输出 v18.17.0

这一步至关重要。很多用户报告npm : 无法将“npm”项识别为 cmdlet，根本原因就是他们的系统 PATH 里混杂了多个 Node.js 版本，nvm能帮你彻底理清。

第二步：解决 Windows PowerShell 执行策略问题
这是 Windows 用户的专属噩梦。错误信息无法加载文件 ... npm.ps1, 因为在此系统上禁止运行脚本，源于 PowerShell 的默认安全策略。绝对不要去网上搜“如何永久关闭执行策略”，那会带来严重安全风险。正确的做法是：临时为当前会话提升权限。在 PowerShell 中，先执行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

这条命令的意思是：“允许运行本地编写的脚本，以及来自可信源的已签名脚本”。它只影响当前用户，且是 PowerShell 的标准安全实践。执行完后，关闭并重新打开 PowerShell，再运行npm install -g claude-code-templates。

第三步：配置国内 npm 镜像源，告别超时
npm install -g默认从registry.npmjs.org下载，这个源在国内经常不稳定，导致npm WARN deprecated或直接timeout。你需要将其切换为国内镜像，比如淘宝源（https://registry.npmmirror.com）或腾讯云源（https://mirrors.cloud.tencent.com/npm/）。执行：

npm config set registry https://registry.npmmirror.com npm config get registry # 确认已生效

提示：npm config list可以查看所有当前配置。如果你之前配置过其他源（比如yarn的源），请确保npm的配置是独立的，避免互相干扰。

第四步：全局安装与验证
现在，终于可以执行核心命令了：

npm install -g claude-code-templates

安装过程会显示详细的依赖树和下载进度。安装成功后，验证：

claude-code --version claude-code --help

如果看到版本号和帮助信息，恭喜，你已经跨过了最大的障碍。此时，claude-code命令已被注册到系统 PATH，你可以在任何目录下使用它。

3.2 配置与认证：API Key 管理的三种安全模式

安装只是开始，真正让 CLI 工作起来的是 Anthropic API Key。claude-code-templates提供了三种配置方式，按安全性从高到低排列：

模式一：环境变量（推荐，最高安全性）
这是最符合 Unix 哲学的方式。在你的 shell 配置文件（~/.bashrc,~/.zshrc, 或 Windows 的System Properties > Environment Variables）中，添加：

export ANTHROPIC_API_KEY="your_actual_api_key_here"

然后执行source ~/.bashrc（Linux/macOS）或重启终端（Windows）。claude-code会自动读取这个环境变量。优点：Key 不会出现在任何命令历史或日志中；可以为不同项目设置不同的环境变量；易于在 CI/CD 中注入。缺点：需要用户手动管理，对新手稍有门槛。

模式二：CLI 配置文件（平衡之选）
运行：

claude-code config set api-key your_actual_api_key_here

CLI 会将 Key 加密后存储在~/.claude-code/config.json中。这个文件的权限被设置为600（仅所有者可读写），防止其他用户窃取。你可以随时用claude-code config get api-key查看（会显示为***），或用claude-code config delete api-key删除。优点：比环境变量更直观；CLI 提供了完整的 CRUD 操作；适合个人开发者快速上手。缺点：Key 以加密形式存储在磁盘上，理论上存在被暴力破解的风险（尽管概率极低）。

模式三：命令行参数（仅限调试，不推荐生产）
你可以在每次运行命令时，用--api-key参数传入：

claude-code generate --api-key "sk-ant-api03-..." --prompt "Hello world"

优点：最简单，无需任何前置配置。缺点：Key 会出现在 shell 历史记录中（history命令可查）；可能被进程监控工具捕获；绝对不能用于自动化脚本。强烈建议：仅在首次测试连通性时使用，验证成功后立即切换到模式一或模式二。

注意：claude-code-templates会严格按照这个优先级读取 Key：命令行参数 > CLI 配置文件 > 环境变量。这意味着你可以在一个项目中用环境变量，在另一个项目中用 CLI 配置，互不干扰。

3.3 第一个命令：generate的完整参数解析与实战

安装和配置完成后，让我们运行第一个有意义的命令：

claude-code generate --prompt "用 Python 写一个函数，计算斐波那契数列的第 n 项，要求使用记忆化递归，时间复杂度 O(n)"

这个看似简单的命令，背后触发了claude-code-templates的完整 MCP 工作流。我们来逐层拆解其参数：

--prompt（必需）
这是你的核心指令。claude-code会将它原封不动地传递给 MCP server，作为messages[0].content。注意，这里不支持多轮对话的 prompt，它只处理单次请求。如果你想模拟多轮，需要用--system参数。

--model（可选，默认claude-3-haiku-20240307）
指定模型 ID。claude-code-templates内置了所有主流 Claude 模型的 MCP URL 映射。例如：

• --model claude-3-haiku→mcp://anthropic.com/claude-3-haiku-20240307
• --model claude-3-sonnet→mcp://anthropic.com/claude-3-sonnet-20240229
• --model claude-3-opus→mcp://anthropic.com/claude-3-opus-20240229你也可以直接传入完整的 MCP URL，比如--model mcp://my-private-mcp-server/claude-proxy，这在企业内网场景下非常有用。

--max-tokens（可选，默认1024）
控制模型输出的最大 token 数。claude-code会根据你选择的模型，自动计算其最大上下文窗口（例如 Haiku 是 200K tokens），并确保--max-tokens不会超过这个限制。如果你设得过大，CLI 会给出警告。

--temperature（可选，默认0.3）
控制输出的随机性。0.0表示完全确定性（相同 prompt 总是返回相同结果），1.0表示最大随机性。对于代码生成，0.1-0.3是最佳区间，能保证逻辑正确性的同时，保留一定的表达多样性。

--system（可选）
提供 system message，用于设定模型的角色和约束。例如：

claude-code generate \ --system "你是一个资深 Python 工程师，只输出可运行的代码，不加任何解释。" \ --prompt "写一个快速排序函数"

claude-code会将--system的内容作为messages[0]，将--prompt的内容作为messages[1]，严格遵循 Anthropic 的 message 格式。

--format（可选，默认text）
指定输出格式。text返回纯文本；json返回一个包含id,content,usage等字段的 JSON 对象；raw返回原始的 MCP 协议响应，用于深度调试。

实操心得：我建议新手第一次运行时，加上-v参数，即claude-code generate -v --prompt "Hello"。你会看到 CLI 如何将你的参数组装成一个标准的 MCP 请求，如何计算 token，如何发起 HTTP POST，以及如何解析响应。这个 verbose 输出，是你理解整个工作流的“X光片”。

4. 实操过程与核心环节实现：构建一个端到端的代码审查工作流

4.1 场景定义：用 Claude 自动审查 Git 提交的代码变更

现在，我们来构建一个真正有价值的、端到端的实操案例：一个自动化的 Git 代码审查工作流。目标是：当你执行git commit -m "feat: add user auth"后，系统能自动分析本次提交中所有新增/修改的.py文件，用 Claude 生成一份简洁的、中文的代码质量报告，指出潜在的 bug、安全漏洞和可优化点。

这个工作流完美体现了claude-code-templates的 CLI 组合能力。它不是单一命令，而是一系列命令的管道（pipeline）。

4.2 步骤一：提取本次提交的变更文件列表

我们需要一个可靠的、跨平台的方法来获取git diff的输出。claude-code-templates本身不提供 Git 功能，但它能完美消费 Git 的输出。首先，创建一个临时文件diff.patch，保存本次提交的差异：

# 获取上一次提交的 hash PREV_COMMIT=$(git rev-parse HEAD^) # 生成 patch 文件，只包含 .py 文件的变更 git diff $PREV_COMMIT -- '*.py' > diff.patch

这一步的关键是-- '*.py'，它确保我们只处理 Python 文件，过滤掉package.json或README.md等无关文件。

4.3 步骤二：将 Patch 内容转换为 Claude 可理解的 Prompt

claude-code generate的--prompt参数接受 stdin（标准输入）。我们可以用cat命令将diff.patch的内容“喂”给它。但直接喂 raw patch 是低效的。我们需要一个预处理器，把 patch 转换成一个结构化的、带上下文的 prompt。claude-code-templates提供了一个内置的preprocess子命令来完成这个任务：

cat diff.patch | claude-code preprocess --type git-diff --language python

这个命令会输出类似这样的 prompt：

你是一名资深 Python 安全工程师。请严格审查以下 Git diff 补丁，重点关注： 1. 是否存在 SQL 注入、XSS、命令注入等安全漏洞？ 2. 是否有明显的逻辑错误或边界条件未处理？ 3. 是否有违反 PEP8 或可读性差的代码？ 请用中文输出一份简洁的审查报告，格式为： 【安全问题】 - [文件名:行号] 问题描述 【逻辑问题】 - [文件名:行号] 问题描述 【优化建议】 - [文件名:行号] 建议描述 以下是补丁内容： diff --git a/app/auth.py b/app/auth.py index abc123..def456 100644 --- a/app/auth.py +++ b/app/auth.py @@ -10,0 +11,5 @@ def login(username, password): + # TODO: Add password hashing + query = f"SELECT * FROM users WHERE username='{username}' AND password='{password}'" + return db.execute(query).fetchone()

这个 prompt 结构清晰，指令明确，大大提升了 Claude 输出的准确率和一致性。

4.4 步骤三：调用 Claude 生成审查报告

现在，我们将预处理后的 prompt 通过管道传递给claude-code generate：

cat diff.patch | \ claude-code preprocess --type git-diff --language python | \ claude-code generate \ --model claude-3-sonnet \ --max-tokens 2048 \ --temperature 0.1 \ --format text

注意--temperature 0.1的设置。对于代码审查这种需要高度确定性的任务，我们几乎关闭了随机性，确保每次运行结果都一致，便于后续的自动化比对。

4.5 步骤四：后处理与结果整合

claude-code generate的输出是纯文本，我们需要将其整合进一个正式的报告中。claude-code-templates提供了postprocess命令，它可以将 Claude 的原始输出，格式化为 Markdown、JSON 或 HTML：

cat diff.patch | \ claude-code preprocess --type git-diff --language python | \ claude-code generate --model claude-3-sonnet | \ claude-code postprocess --format markdown --title "Git Commit Review Report for $(git log -1 --pretty=%h)"

这个命令最终会生成一个美观的 Markdown 报告，包含标题、时间戳、以及 Claude 的结构化分析。你可以将这个报告直接发送到 Slack 频道，或者保存为review-report-$(date +%Y%m%d).md归档。

4.6 步骤五：自动化集成（Git Hook）

为了让这个工作流真正“自动化”，我们需要把它嵌入到 Git 的生命周期中。最常用的方式是pre-commithook。在你的项目根目录下，创建.git/hooks/pre-commit文件：

#!/bin/bash # 检查是否有 .py 文件被修改 CHANGED_PY=$(git status --porcelain | grep '\.py$' | wc -l) if [ "$CHANGED_PY" -gt 0 ]; then echo "Running Claude code review..." # 执行上面的完整 pipeline cat <(git diff HEAD) | \ claude-code preprocess --type git-diff --language python | \ claude-code generate --model claude-3-sonnet --temperature 0.1 | \ claude-code postprocess --format markdown --title "Pre-commit Review" > /tmp/claudereview.md # 如果审查报告中有【安全问题】，则阻止提交 if grep -q "【安全问题】" /tmp/claudereview.md; then echo "❌ CLAUDE REVIEW FAILED: Security issues detected!" cat /tmp/claudereview.md exit 1 fi fi

给这个文件添加可执行权限：chmod +x .git/hooks/pre-commit。现在，每次你尝试git commit，如果修改了 Python 文件，这个 hook 就会自动触发 Claude 审查。如果有高危安全问题，提交会被直接拒绝，并打印出详细报告。这就是claude-code-templates的威力：它不是一个玩具，而是一个可以嵌入到你现有工程流程中的、生产级别的工具。

5. 常见问题与排查技巧实录：从 “npm.ps1” 到 “MCP Gateway Mismatch”

5.1 Windows PowerShell 执行策略问题（高频）

现象：npm : 无法加载文件 d:\program files\nodejs\npm.ps1, 因为此系统上禁止运行脚本

根本原因：PowerShell 的 Execution Policy（执行策略）默认为Restricted，禁止运行任何本地脚本，包括npm自身的npm.ps1启动脚本。

标准解决方案（安全）：

# 在 PowerShell 中执行，仅对当前用户生效 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # 然后关闭并重新打开 PowerShell

备选方案（如果上述不行）：

• 使用Command Prompt (cmd.exe)或Windows Terminal，它们不受 PowerShell 策略限制。
• 或者，在 PowerShell 中临时绕过策略：PowerShell -ExecutionPolicy Bypass -File "C:\Program Files\nodejs\npm.ps1" install -g claude-code-templates（不推荐长期使用）。

注意：网上流传的Set-ExecutionPolicy Unrestricted是极度危险的，它会允许运行任何来源的脚本，包括恶意软件。RemoteSigned是微软官方推荐的安全级别。

5.2 npm 命令无法识别（环境变量 PATH 问题）

现象：npm : 无法将“npm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称

根本原因：npm的可执行文件路径（通常是C:\Program Files\nodejs\或/usr/local/bin/）没有被添加到系统的PATH环境变量中。

排查步骤：

1. 首先确认node是否可用：node -v。如果node也不行，说明 Node.js 本身就没装好。
2. 找到npm的实际位置：
   • Windows:where npm或Get-Command npm | Select-Object -ExpandProperty Definition
   • macOS/Linux:which npm或command -v npm
3. 将该路径添加到PATH：
   • Windows:System Properties > Advanced > Environment Variables > System Variables > Path > Edit > New > [粘贴路径]
   • macOS/Linux: 在~/.bashrc或~/.zshrc中添加export PATH="/usr/local/bin:$PATH"（路径需替换为上一步查到的实际路径）

终极验证：打开一个全新的终端窗口，执行echo $PATH（macOS/Linux）或echo %PATH%（Windows），确认新路径已存在。

5.3 “Unable to connect to Anthropic services” 网络问题

现象：claude-code generate命令长时间无响应，或报错Failed to connect to api.anthropic.com

排查思路（从近到远）：

1. 检查网络连通性：ping api.anthropic.com。如果 ping 不通，说明是 DNS 或基础网络问题。
2. 检查代理设置：如果你在公司内网，很可能需要代理。claude-code-templates尊重系统代理环境变量。确保HTTP_PROXY和HTTPS_PROXY已正确设置。例如：

   export HTTPS_PROXY=http://your-proxy:8080

3. 检查防火墙：某些企业防火墙会拦截对api.anthropic.com的 HTTPS 请求。尝试用curl -v https://api.anthropic.com看是否能建立 TLS 连接。
4. 检查 MCP 配置：如果你自定义了 MCP server，确保claude-code config get mcp-server返回的是正确的 URL，并且该 server 本身能正常访问 Anthropic。

快速诊断命令：

# 查看 CLI 的详细网络请求 claude-code generate -v --prompt "test" 2>&1 | grep -E "(URL|Status|Error)" # 直接测试 MCP server 的健康状态 claude-code health check

5.4 “Claude doesn’t look like an Anthropic model” 模型路由错误

现象：claude-code generate --model claude-3-haiku报错Claude doesn't look like an anthropic model: expected a gateway model route

根本原因：claude-code-templates的内置 MCP registry 中，claude-3-haiku这个别名，映射到了一个错误的 gateway URL。这通常发生在claude-code-templates的版本过旧，而 Anthropic 更新了其 gateway 路由时。

解决方案：

1. 升级 CLI：npm update -g claude-code-templates。这是最简单有效的方法。
2. 手动更新 MCP registry：如果升级后问题依旧，可以手动覆盖：

   claude-code config set mcp-registry.claude-3-haiku "mcp://anthropic.com/claude-3-haiku-20240307"

   这里的20240307是模型发布的日期戳，必须与 Anthropic 官方文档保持一致。

预防措施：定期运行claude-code version --check，CLI 会自动检查是否有新版本可用。

5.5 “Unable to locate the codex cli binary” 二进制缺失问题

现象：claude-code命令不存在，或报错找不到二进制文件。

根本原因：npm install -g成功，但npm创建的符号链接损坏，或者node_modules/.bin/目录权限异常。

排查与修复：

1. 确认全局 node_modules 位置：npm root -g。通常为/usr/local/lib/node_modules（macOS/Linux）或C:\Users\[user]\AppData\Roaming\npm\node_modules（Windows）。
2. 检查node_modules/.bin/目录：进入该目录，执行ls -la | grep claude（macOS/Linux）或dir | findstr claude（Windows）。你应该能看到claude-code这个文件（或快捷方式）。
3. 如果文件存在但不可执行：chmod +x claude-code（macOS/Linux）。
4. 如果文件不存在：说明npm install过程中出现了静默错误。删除整个node_modules目录，然后重新运行npm install -g claude-code-templates。

实操心得：我曾经在一个 CI 环境中遇到这个问题，根源是 CI runner 的 Docker 镜像里，/usr/local/bin目录的 owner 是root，而npm试图以普通用户身份写入。解决方案是在 CI 脚本中，先sudo chown -R $USER:$USER /usr/local，再运行npm install。这个坑，我踩了三次才记牢。

5.6 常见问题速查表

这个表格是我过去一年在内部技术分享会上，根据上百次用户咨询整理出来的精华。它不是教科书式的罗列，而是每一个条目，都对应着一个真实发生过的、让人抓狂的下午。