AI Coding 零基础实战教程（三）：AI编程工具生态与模型选择

第二部分：AI编程工具生态

学习目标：深入掌握主流AI编程工具，重点精通Claude Code的使用

完成标志：能熟练使用Claude Code完成完整的编程任务，能根据场景选择合适工具

这是本教程最核心的一部分。如果说前面是"认知准备"，这里就是"真刀真枪"。我们将深入学习 Claude Code 的每一个细节，让你从安装配置到日常使用都游刃有余。

2.1 AI编程工具全景图

在深入 Claude Code 之前，先整体了解一下当前AI编程工具的格局，这样你才能理解每个工具的定位和适用场景。

2.1.1 按交互模式分类

2.1.2 按能力层级分类

L5 自主工程 ─── 端到端自主完成项目（探索中）
   ↑
L4 项目管理 ─── 多Agent协同、任务分解（Qoder）
   ↑
L3 任务执行 ─── 自主修改文件、运行命令（Claude Code、Cursor Agent）我们重点学这个
   ↑
L2 代码生成 ─── 生成完整代码块（ChatGPT、Claude.ai）
   ↑
L1 代码补全 ─── 行级/函数级补全（Copilot、TabNine）

本教程的核心工具 Claude Code 处于 L3 层级，是目前日常开发中最实用、最强大的层级。

2.1.3 如何评估一个AI编程工具

当你在选择AI编程工具时，可以从这8个维度来评估：

2.2 各AI编程工具概述

在深入了解具体工具之前，先快速认识一下目前最主流的几款AI编程工具——了解它们各自是什么、核心特点是什么，形成全局认知。

2.2.1 Claude Code

本节是全教程的核心重点，将从安装到进阶全方位讲解 Claude Code 的使用。

Claude Code 是 Anthropic 公司推出的 AI 编程智能体。它最经典的入口是终端 CLI，现在也提供 IDE、Desktop、Web 等形态。它能够读取项目代码、修改文件、运行命令、安装依赖 —— 就像你雇了一个 24 小时在线的远程程序员，你用自然语言告诉它做什么，它自己动手干活。

graph TB
   subgraph CC["Claude Code 核心能力架构"]
      direction TB
      Input["你的自然语言指令"] --> Brain["AI 大脑<br/>Claude Sonnet/Opus"]

      subgraph Abilities["四大能力模块"]
         direction LR
         subgraph F[" 文件操作"]
            F1["读取文件"]
            F2["创建/修改文件"]
            F3["搜索代码"]
         end
         subgraph T[" 终端执行"]
            T1["运行命令"]
            T2["安装依赖"]
            T3["启动服务"]
         end
         subgraph U[" 代码理解"]
            U1["项目结构分析"]
            U2["逻辑理解"]
            U3["依赖关系"]
         end
         subgraph W[" 智能编码"]
            W1["需求→代码"]
            W2["Bug定位修复"]
            W3["重构优化"]
         end
      end

      Brain --> F
      Brain --> T
      Brain --> U
      Brain --> W
   end

图：Claude Code 核心能力架构 —— AI大脑接收你的指令，通过四大能力模块操控项目

Claude Code 是什么？

如果把AI编程工具比作不同的交通工具：

• ChatGPT/Claude.ai 就像公交车 —— 你问路，它告诉你怎么走，但你得自己走

• Cursor 就像共享单车 —— 你骑着它走，它帮你指路和加速

• Claude Code 就像出租车 —— 你说目的地，它自己开到

Claude Code 的核心特点：

Claude Code vs Claude.ai 的核心区别：

提示：Claude Code 和 Claude.ai 都使用 Claude 系列模型，核心区别在于“交互方式”和“工具权限”。Claude Code 给了 AI “手” —— 让它能在你授权后直接触碰项目文件和开发工具。

2.2.1.1 LLM Loop：cc 凭什么是「Agent」而不是「聊天框」

要理解 Claude Code 与你以前用过的 ChatGPT、Claude.ai 的本质差别，必须先弄懂一个机制 —— LLM Loop（大模型循环）。

对话式 AI（ChatGPT/Claude.ai）的工作方式：你问一句 → 它答一句 → 结束。如果答案不满意，你再问一次。主动权一直在你手里，AI 只是个"高级回答机器"。

Claude Code 的工作方式：你下达一个目标 → cc 自己拆解步骤 → 自己调用工具 → 看结果 → 决定下一步 → 再调用工具 → ……一直循环到任务完成。主动权交给了 AI。这个不断"思考-行动-观察-再思考"的循环，就叫 LLM Loop。

graph LR
   A["你给一个目标"] --> B[" 思考<br/>制定下一步计划"]
   B --> C[" 行动<br/>调用工具/执行命令"]
   C --> D[" 观察<br/>读取执行结果"]
   D --> E{"任务完成?"}
   E -- "否" --> B
   E -- "是" --> F[" 交付结果"]

图：LLM Loop —— Claude Code 的自主循环机制

这就是为什么我们把 cc 称为 Agent（智能体） 而不是 Chatbot（聊天机器人）。也正因为如此：

• 你可以给 cc 一个模糊的高层目标（如"帮我做一个番茄钟"），它会自己一步步推进

• cc 在执行过程中会自我纠错——某条命令报错了，它会读错误信息，调整方案再试

• 注意： cc 不一定每一步都问你，所以在它"撒丫子跑"之前，你要给好上下文（CLAUDE.md、Skills、计划等）

关键认知：cc 是一整套"程序+模型"的组合，底层的大模型其实可以替换——这也是为什么后面我们能用 DeepSeek、千问、GLM 等国产模型来驱动 cc。是这套 Loop 机制 + Harness 工程，让 cc 比单纯的对话式 AI 强大得多。

2.2.1.2 Claude Code 是如何“读懂”你的代码库的（Agentic Search）

很多人对 Claude Code 有个误解：以为它会像其他 AI 工具一样，需要先把项目代码上传到服务器建立“索引”。事实上，Claude Code 不需要任何预先的代码库索引。

官方把这种机制叫做 Agentic Search（智能体式检索），它的工作方式和一个人类工程师冷启动一个项目完全一样：

graph LR
   A["你的需求"] --> B["浏览目录结构"]
   B --> C["读取关键文件"]
   C --> D["用 grep 搜索代码"]
   D --> E["跟进引用/调用关系"]
   E --> F["在本地理解代码"]
   F --> G["执行任务"]

图：Agentic Search——像人一样按需读取代码库

与传统 RAG/向量检索的本质区别：

关键意义：这意味着 Claude Code 天生适合活跃代码库——它不依赖一份可能过期的预建索引，也不需要 IT 部门部署向量数据库。但它读取到的相关文件内容仍会作为上下文发送给模型服务，所以处理敏感代码时依然要遵守公司安全规范。

2.2.1.3 “脚手架”比“模型”更重要：Harness 体系

官方反复强调一个观点：决定 Claude Code 表现的，不只是背后的模型，还有围绕模型搭建的“脚手架 Harness”。

理解方式：模型能力决定下限，项目上下文、工具权限、规则文件和工作流决定上限。实际生产中，围绕模型搭建的工具生态会显著影响最终表现。

本教程把 Claude Code 的工程化能力抽象成 7 个扩展点，建议按“从底到顶”的顺序理解——先打好上下文和规则基础，再接入更复杂的外部工具：

graph TB
   L7["⑦ Subagents（子代理）<br/>独立上下文窗口去调研/执行"]
   L6["⑥ MCP Servers<br/>接入外部工具与数据源"]
   L5["⑤ LSP（语言服务器）<br/>给 AI 装上 IDE 导航能力"]
   L4["④ Plugins<br/>Skills+Hooks+MCP 打包分发"]
   L3["③ Skills<br/>按需加载的专业知识包"]
   L2["② Hooks<br/>会话生命周期钩子"]
   L1["① CLAUDE.md<br/>项目上下文文件"]
   Base[" 模型本身（地板）"]

   Base --> L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7

图：Harness 的 7 层扩展点——下三层是“纪律”（项目上下文、钩子、知识），上四层是“武器”（包分发、IDE、外部、子代理）

注意： 顺序重要！ 初学者不要在基础还没搭好时就急着上 MCP 或 Subagents。先把 CLAUDE.md、Hooks、Skills 这三层基本功做扎实再说。

2.2.2 OpenAI Codex

Codex 是 OpenAI 推出的 AI 编程 Agent，是 Claude Code 最主要的竞争对手之一。其中 Codex CLI 是开源项目，Codex App / Desktop / IDE 插件则更偏产品化入口。它目前常见的使用形态包括：

CLI 会使用本地 ~/.codex/ 配置目录；桌面端和 IDE 插件也会共享 OpenAI 账号体系，但具体配置项、插件能力和界面入口会随版本变化，以当前客户端显示为准。

核心亮点：

• CLI 开源透明（Apache 2.0）：可以阅读源码理解工具原理

• 沙箱与审批机制：通过 sandbox / approval mode 控制文件修改和命令执行风险

• AGENTS.md 项目说明：用于记录项目规则、上下文和工作约定，便于 Agent 在新会话中快速接手

• 多模型提供商：原生支持 GPT 系列，也可接入 DeepSeek、Ollama、Mistral 等任何兼容 OpenAI API 的服务

• 三档自主级别：suggest（每次确认）→ auto-edit（自动编辑，命令需确认）→ full-auto（完全自主），灵活控制

• 推理强度可控：low / medium / high 三档，根据任务复杂度平衡速度与质量

Codex 与 Claude Code 核心对比：

何时选择 Codex：

• 已有 ChatGPT 账号或 OpenAI API → 零配置开箱即用

• 看重开源透明、想阅读源码 → Codex CLI 可审计

• 需要明确控制命令和文件修改风险 → 关注 Codex 的 sandbox / approval 设置

• 想用 GPT 系列的代码能力 → Codex 是 GPT 的原生入口

• 需要跨工具统一规范 → AGENTS.md 是开放标准

一句话总结：Codex 适合看重开源、安全沙箱和 GPT 生态的用户；Claude Code 适合追求国内模型生态成熟度和 Coding Plan 省心体验的用户。两者可在同一项目中共存，AGENTS.md 和 CLAUDE.md 互不干扰。

2.2.3 Cursor

如果说 Claude Code 是命令行中的"远程程序员"，那 Cursor 就是坐在你旁边、和你共用一个屏幕的"编程搭档"。

2.2.3.1 Cursor 概述与定位

Cursor 是一个基于 VS Code 改造的 AI 原生 IDE（集成开发环境）。它把AI能力直接嵌入到了代码编辑器中，让你在写代码的同时随时获得AI辅助。

提示：Claude Code 和 Cursor 不是竞争关系，而是互补关系。很多开发者的工作流是：用 Claude Code 搭建项目骨架和实现后端逻辑，用 Cursor 精调前端细节和日常编码。

2.2.4 其他AI编程工具

除了三大主流工具之外，还有一些各具特色的AI编程工具值得了解。

2.2.4.1 Qoder（阿里）

Qoder 是阿里推出的 AI 编程工具，主打更强的任务拆解、上下文检索和 Agent 化开发体验。由于这类工具迭代很快，具体功能入口和角色命名请以官网当前版本为准。

可以把它理解为更偏“项目团队协作感”的 AI IDE：

基本使用流程

Qoder 的典型工作流：

你描述需求 → 工具理解并拆分任务
   → 检索现有代码
   → 制定实施计划
   → 执行编码
   → 运行验证
   → 汇报结果与后续建议

Qoder 特别适合复杂项目，因为它的多Agent协作可以同时处理代码编写、测试、审查等多个环节，减少返工。

2.2.4.2 CodeBuddy（腾讯云AI代码助手）

腾讯推出的AI编程助手，以 IDE 插件形式提供。特点是中文优化好、国内直接可用、企业级功能完善。

适合在腾讯云生态中开发的团队。

2.2.4.3 Trae（字节跳动）

字节跳动推出的AI IDE，类似 Cursor，但深度集成了豆包大模型。国内直接可用，中文支持好。

2.2.4.4 在线快速原型工具

这些工具不需要安装任何东西，直接在浏览器中描述你想要什么，它们会生成可运行的应用。适合快速验证想法，但对于学习AI编程技能来说，Claude Code 和 Cursor 能让你学到更多。

2.2.5 工具对比与选型指南

2.2.5.1 全维度对比矩阵

2.2.5.2 场景化选型建议

2.2.5.3 工具+模型组合推荐

选择AI编程方案时，工具和模型要一起考虑——就像买车不能只看车架不看发动机。以下是根据不同预算和需求，经过大量实战验证的最优组合：

性能组：Claude Code + Claude 模型

这是目前综合体验最好的组合。Claude Code 的 Agent 能力 + Claude 模型的代码理解能力，两者深度适配。缺点是需要国际支付方式，且按量付费需要留意用量。

适合：有国际信用卡的学生/开发者，对代码质量要求高。

免费组：Codex CLI + ChatGPT/Codex 账号额度

Codex CLI 可以通过 ChatGPT 账号或 API Key 使用，具体额度取决于你的账号套餐和官方策略。Codex CLI 开源透明，沙箱和审批机制清晰，适合低成本入门。缺点是不同地区、套餐和时间段的可用额度可能变化。

适合：想零成本入门 AI 编程的新手。

性价比组：Claude Code + GLM Coding Plan

智谱的 Anthropic 兼容接口做得比较完整，三个模型槽位（Opus/Sonnet/Haiku）可自动映射到 GLM 系列，免去手动配置的麻烦。套餐价格、额度和高峰期倍率会调整，正式购买前以智谱官网为准。

适合：国内大多数开发者，不想折腾配置、追求稳定省心。

极客组：Claude Code + DeepSeek V4 Pro

DeepSeek 官方提供了 Claude Code 的 Anthropic 兼容接入方式，当前文档示例使用 deepseek-v4-pro[1m]，并可把轻量任务映射到 deepseek-v4-flash。价格通常较低，但需要自己配置端点、Key 和环境变量，并按官方文档核对最新模型名。

适合：动手能力强、追求极致性价比的学生和个人开发者。

选型建议：新手推荐从性价比组（GLM Coding Plan）或免费组（Codex CLI）开始，零风险体验。等熟悉了再升级到性能组。

2.2.5.4 工具组合（进阶玩法）

上一节是按"预算"选方案，这一节是按"场景"搭工具组合——你可以同时用多个工具，发挥各自优势。

双工具流（推荐）：Claude Code（后端/架构/数据库）+ Cursor（前端/UI细节）

这是目前社区公认的最佳实践。Claude Code 擅长从零搭建项目骨架、写 Prisma Schema、设计 API；Cursor 擅长对着设计稿调像素、改 Tailwind 类名。两者互补，效率最高。

轻量组合：Cursor + Claude.ai 网页版辅助

不想学命令行的替代方案。主力用 Cursor 写代码，遇到复杂问题打开 Claude.ai 网页版直接问。

国内友好组合：Trae + DeepSeek API

全程无需代理，Trae 的 IDE 体验接近 Cursor，DeepSeek 提供高性价比的模型能力。

2.3 Claude Code 安装与配置

2.3.1 安装

前提条件：

Claude Code 官方提供原生安装器和 npm 等安装方式。本教程已经在第零部分安装 Node.js，因此优先使用 npm 安装方式，和后续前端项目开发环境保持一致；如果你不想通过 npm 管理 Claude Code，也可以使用官方原生安装器。

方式一：npm 安装（推荐本教程使用）

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

Windows 提醒：Claude Code 对 Windows 的支持方式会随版本变化。若官方文档提示通过 WSL 使用，请在 WSL 的 Linux 终端里执行安装和环境变量配置；如果你的当前版本支持原生 Windows，再按官方 Windows 说明操作。

方式二：原生安装器（可选）

官方也提供原生安装器，用于不想通过 npm 管理 Claude Code 的用户。安装命令和支持系统可能变化，使用前请以 Claude Code 官方 setup 文档为准。

# macOS / Linux / WSL 示例
curl -fsSL https://claude.ai/install.sh | bash

验证安装：

$ claude --version

预期输出：

claude-code v1.x.x

验证：如果能看到版本号，说明安装成功！

安装常见问题排查：

提示： 国内用户 如果官方安装器网络不稳定，可以临时使用 npm 方式，并先配置 npm 镜像：

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

2.3.2 API 配置

安装好 Claude Code 后，需要配置 API 密钥或登录方式才能使用。这一节提供三类配置方案，请根据你的情况选择。

核心配置参数速查表：

提示： 参数关系说明：ANTHROPIC_API_KEY 用于官方直连，ANTHROPIC_AUTH_TOKEN 用于第三方服务。两者不要同时设置，否则会冲突。ANTHROPIC_BASE_URL 只在使用非官方端点时需要设置。

三种配置方式对比：

配置文件路径说明：

• 全局：~/.claude/settings.json（Windows：C:\Users\<用户名>\.claude\settings.json）

• 项目级（团队共享）：项目根目录/.claude/settings.json（可提交 Git）

• 项目级（个人私有）：项目根目录/.claude/settings.local.json（加入 .gitignore）

graph TB
   subgraph Priority["配置优先级（从高到低）"]
      direction TB

      subgraph L1["① 启动参数（最高优先级）"]
         P1["claude --model opus"]
      end

      subgraph L2["② 环境变量"]
         P2["ANTHROPIC_MODEL<br/>ANTHROPIC_AUTH_TOKEN<br/>ANTHROPIC_BASE_URL"]
      end

      subgraph L3["③ 配置文件（从高到低）"]
         P3A["项目/.claude/settings.local.json<br/>（个人私有，不提交Git）"]
         P3B["项目/.claude/settings.json<br/>（团队共享，提交Git）"]
         P3C["~/.claude/settings.json<br/>（全局生效）"]
         P3A --> P3B --> P3C
      end

      L1 --> L2 --> L3
   end

   subgraph Methods["三种配置方式"]
      direction LR
      M1[" 临时环境变量<br/>关窗口即失效<br/>适合：快速测试"]
      M2[" 永久环境变量<br/>所有终端生效<br/>适合：固定使用"]
      M3[" settings.json<br/>项目级隔离<br/>适合：多项目切换"]
   end

图：Claude Code 配置体系架构 —— 三种配置方式及其优先级层级

方案选择指南：

你能直接访问 Anthropic 网站吗？
├── 能 → 方案一：使用 Anthropic 官方 API（推荐）
└── 不能 → 你在国内吗？
   ├── 想用原版 Claude 模型 → 方案二：使用第三方API中转服务 国内首选
   ├── 想用其他模型（DeepSeek/千问/GLM等） → 方案三：接入其他模型
   └── 想要包月套餐、省心不操心 → 在方案三中选择厂商 Coding Plan

2.3.2.1 方案一：使用 Anthropic 官方 API（推荐海外用户）

这是最直接的配置方式，适合能稳定访问 Anthropic 服务、具备合规支付方式的用户。国内用户可能会遇到注册、支付、访问稳定性等问题，建议按自己的网络和合规条件谨慎选择。

注册步骤（可直接访问国际网络的用户）：

1. 访问 https://console.anthropic.com/

2. 点击 "Sign up" 注册账号

3. 使用邮箱注册并完成验证

4. 登录后，进入 API Keys 页面

5. 点击 "Create Key" 创建一个新的 API Key

6. 为这个 Key 起个名字（如 "claude-code"）

7. 立即复制并保存 —— API Key 只会显示一次！

避坑：API Key 就像你的银行卡密码，绝对不要分享给别人，也不要把它写在代码文件里提交到 GitHub。一旦泄露，别人可以用你的额度调用API，产生费用。

计费说明：

Anthropic API 采用按量计费模式（用多少付多少）：

提示：一个 Token 大约等于 4 个英文字符或 1-2 个中文字符。一次普通的编程对话大约消耗 1000-5000 个 Token，具体费用取决于输入/输出比例和所选模型。新用户是否有免费额度，以 Anthropic 当前页面为准。

（价格信息按 Anthropic 官方价格页在 2026-05-18 核对，请以官网最新价格为准）

Step 1：设置环境变量

你需要将 API Key 设置为系统环境变量，这样 Claude Code 启动时就能自动读取。

Windows 用户（PowerShell）：

# 方法一：临时设置（仅当前终端窗口有效，关闭后失效）
$env:ANTHROPIC_API_KEY = "sk-ant-api03-你的实际API-Key"

# 方法二：永久设置（推荐，一次设置永久生效）
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-你的实际API-Key", "User")

注意：永久设置后需要重新打开终端才能生效。

macOS / Linux 用户：

# 编辑 shell 配置文件（根据你使用的 shell 选择）
# 如果用 zsh（macOS 默认）：
$ echo 'export ANTHROPIC_API_KEY="sk-ant-api03-你的实际API-Key"' >> ~/.zshrc

# 如果用 bash：
$ echo 'export ANTHROPIC_API_KEY="sk-ant-api03-你的实际API-Key"' >> ~/.bashrc

# 使配置立即生效
$ source ~/.zshrc  # 或 source ~/.bashrc

Step 2：首次启动 Claude Code

# 进入你的项目目录
$ cd D:\ai-coding-projects  # Windows
$ cd ~/ai-coding-projects   # macOS

# 启动 Claude Code
$ claude

预期输出：

╭──────────────────────────────────────────╮
│                                │
│   Welcome to Claude Code!            │
│                                │
│   /help for available commands         │
│                                │
╰──────────────────────────────────────────╯

>

你会看到一个交互式界面，光标等待你输入。试试输入你的第一条消息：

> 你好，请介绍一下你自己

验证：如果 Claude Code 正常回复了你的消息，恭喜，API配置成功！

常见错误排查：

2.3.2.2 方案二：使用第三方API中转服务（国内用户）

如果你在国内无法直接访问 Anthropic 的服务，这个方案是你的最佳选择。

注意：很多个人搭建的中转平台，溢价严重，甚至有作假的情况，请仔细甄别。而且避免封号的情况也无法保证，这里不做推荐。

主流中转服务对比：

（价格倍率会随市场波动，请以各服务商官网最新价格为准）

提示：所谓"价格倍率"，是指相比 Anthropic 官方价格的加价比例。例如官方 $3/百万Token，1.2x 倍率就是 $3.6/百万Token。中转服务需要维护服务器和线路，所以会有一定加价，这是正常的。

以 OpenRouter 为例的注册流程：

1. 访问 https://openrouter.ai/

2. 点击 "Sign in" 注册账号（支持 Google 账号登录）

3. 登录后，进入 "Keys" 页面

4. 点击 "Create Key" 创建 API Key

5. 复制并保存你的 API Key（以 sk-or- 开头）

6. 在 "Credits" 页面充值（支持信用卡）

需要记录的关键信息：

API Base URL: https://openrouter.ai/api/v1
API Key: sk-or-v1-xxxxxxxxxxxxx（你的实际Key）

注意：不同的中转服务有不同的 API Base URL 格式。注册后请仔细查看服务商提供的文档，找到他们的 Base URL 和支持的模型列表。

原理回顾：

你的 Claude Code ──请求──→ 中转服务器（国内可达）──转发──→ Anthropic API
      ↑                                         │
      └──────────────── 返回 AI 回复 ←───────────────────────┘

中转服务本质上就是一个"代理"，帮你把请求转发给 Anthropic，再把结果返回。你在 Claude Code 中需要做的就是把"目的地地址"从 Anthropic 官方改成中转服务。

Step 1：获取中转服务的信息

在 0.3.2 节你已经注册了中转服务，现在需要两个关键信息：

API Base URL：中转服务的地址（每个服务商不同）
API Key：在中转服务上创建的 Key（不是 Anthropic 官方的 Key）

以 OpenRouter 为例：

API Base URL: https://openrouter.ai/api/v1
API Key: sk-or-v1-你的OpenRouter-Key

Step 2：设置环境变量

Claude Code 通过 ANTHROPIC_BASE_URL 环境变量来指定API地址。

Windows 用户（PowerShell）：

# 临时设置（当前窗口有效）
$env:ANTHROPIC_BASE_URL = "https://openrouter.ai/api/v1"
$env:ANTHROPIC_API_KEY = "sk-or-v1-你的中转服务Key"

# 永久设置（推荐）
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://openrouter.ai/api/v1", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-or-v1-你的中转服务Key", "User")

macOS / Linux 用户：

# 编辑 shell 配置文件
$ vim ~/.zshrc  # 或你喜欢的编辑器

# 在文件末尾添加以下两行：
export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_API_KEY="sk-or-v1-你的中转服务Key"

# 保存后使配置生效
$ source ~/.zshrc

Step 3：验证配置

# 重新打开终端（重要！）
# 启动 Claude Code
$ claude

输入测试消息：

> 你好，请告诉我今天是星期几

如果收到正常回复，说明中转配置成功。

验证：Claude Code 正常回复即表示中转服务配置成功。

不同中转服务的配置参考：

注意：不同中转服务的 Base URL 格式不同，请务必查阅你所使用的服务商的文档。有些服务商要求 URL 末尾带 /v1，有些不需要，配错会导致连接失败。

中转服务常见问题：

2.3.2.3 方案三：接入其他模型（DeepSeek/千问/GLM）

Claude Code 不仅可以使用 Claude 模型，还可以通过配置接入其他AI模型。这对国内用户特别有价值 —— 你可以使用国内直连的模型服务，不需要任何代理。

工作原理：

Claude Code 内部有一个三级模型槽位体系。无论你用哪个模型提供商，它始终维护三个"角色位"：

接入第三方模型有两种方式：

方式一：直接指定模型（通用方式）

# 设置 API Key 和 Base URL（大部分第三方模型都兼容 OpenAI 格式）
export ANTHROPIC_AUTH_TOKEN="你的模型API-Key"
export ANTHROPIC_BASE_URL="模型的API地址"

然后在启动 Claude Code 时指定模型：

# 使用指定模型启动
$ claude --model "模型名称"

方式二：Anthropic 兼容接口（自动映射，包含 DeepSeek、GLM、Kimi）

目前官方提供 Anthropic Messages API 兼容端点的国产厂商越来越多，包括：

配置后，Claude Code 界面仍然显示 Opus/Sonnet/Haiku 的别名，但实际调用的是厂商的模型——这就是服务端模型映射。

以智谱 GLM 为例：

# 智谱 GLM 最简配置
export ANTHROPIC_AUTH_TOKEN="你的智谱API-Key"
export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic"

智谱 GLM 默认的服务端自动映射关系（根据官方文档最新表述）：

提示：要用上旗舰型号 GLM-5.1，需要手动覆盖三个槽位（详见下面「接入智谱 GLM」部分）。不要误以为默认就是 GLM-5.1。

现在GLM的Coding Plan非常抢手，不一定能买到，而且有限额、高峰期翻倍消耗额度。

方式三：通过配置文件（推荐持久化配置）

除了环境变量，还可以在 settings.json 的 env 块中配置，效果相同但更持久、更清晰：

// ~/.claude/settings.json（全局生效）
{
  "env": {
   "ANTHROPIC_AUTH_TOKEN": "你的API-Key",
   "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
   "API_TIMEOUT_MS": "3000000"
  }
}

提示：三种配置方式的优先级为：启动参数 --model > 环境变量 ANTHROPIC_MODEL > 配置文件 settings.json 中的 model 字段。选择最适合你工作习惯的方式即可。

接入智谱 GLM 的完整步骤：

智谱 AI 提供了 Anthropic Messages API 兼容接口，是目前国内配置最简单的方案之一。

官方文档：https://docs.bigmodel.cn/cn/coding-plan/tool/claude

最简配置（使用默认 GLM-4.7 映射）：

# 环境变量方式
export ANTHROPIC_AUTH_TOKEN="你的智谱Key"
export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic"

或使用配置文件（智谱官方推荐方式）：

// ~/.claude/settings.json
{
  "env": {
   "ANTHROPIC_AUTH_TOKEN": "你的智谱Key",
   "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
   "API_TIMEOUT_MS": "3000000",
   "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  }
}

另外智谱官方要求在 ~/.claude.json 中添加（跳过首次启动的引导流程）：

// ~/.claude.json
{
  "hasCompletedOnboarding": true
}

配置完成后重启终端，运行 claude 即可。默认服务端映射如上表（Opus/Sonnet → GLM-4.7，Haiku → GLM-4.5-Air）。

使用 GLM-5.1（需手动覆盖三个槽位）：

GLM-5.1 / GLM-5-Turbo 作为高阶模型，对标 Claude Opus，使用时会按“高峰期 3 倍、非高峰期 2 倍”系数消耗套餐额度（"高峰期"为每日 14:00～18:00 UTC+8）。如需使用，手动覆盖：

// ~/.claude/settings.json
{
  "env": {
   "ANTHROPIC_AUTH_TOKEN": "你的智谱Key",
   "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
   "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.1",
   "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5-turbo",
   "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
   "API_TIMEOUT_MS": "3000000",
   "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  }
}

注意： 版本兼容提醒：第三方 Anthropic 兼容接口可能会受到 Claude Code 新功能影响。如果遇到工具调用或 Beta 参数报错，优先查看对应厂商官方文档的兼容说明，不要盲目复制旧版本配置。

提示： 一键脚本：macOS / Linux 用户可以直接运行官方脚本自动完成上述配置：

curl -O "https://cdn.bigmodel.cn/install/claude_code_env.sh" && bash ./claude_code_env.sh

接入 Kimi（月之暗面）的完整步骤（严格按 Kimi 官方文档）：

Kimi 为 Claude Code 提供了 Anthropic 兼容端点，推荐使用 kimi-k2.5 模型（在 Agentic / 工具调用场景下的主力型号）。

官方文档：https://platform.moonshot.cn/docs/guide/agent-support

Step 1：在 https://platform.kimi.com/console/api-keys 创建 API Key。建议同时在项目设置里设置「项目日消费预算」防超支。

Step 2：设置环境变量

Windows PowerShell：

$env:ANTHROPIC_BASE_URL="https://api.moonshot.ai/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="<你的 Moonshot API Key>"
$env:ANTHROPIC_MODEL="kimi-k2.5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="kimi-k2.5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="kimi-k2.5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="kimi-k2.5"
$env:CLAUDE_CODE_SUBAGENT_MODEL="kimi-k2.5"
$env:ENABLE_TOOL_SEARCH="false"
claude

macOS / Linux：

export ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic
export ANTHROPIC_AUTH_TOKEN=<你的 Moonshot API Key>
export ANTHROPIC_MODEL=kimi-k2.5
export ANTHROPIC_DEFAULT_OPUS_MODEL=kimi-k2.5
export ANTHROPIC_DEFAULT_SONNET_MODEL=kimi-k2.5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=kimi-k2.5
export CLAUDE_CODE_SUBAGENT_MODEL=kimi-k2.5
export ENABLE_TOOL_SEARCH=false
claude

Step 3：进入 cc 后输入 /status 验证模型状态。如需启用 kimi-k2.5 的思考（Thinking）能力，进入 cc 后按 Tab 键切换，看到 "Thinking on" 即为生效。

注意： 重要：不要使用老写法 https://api.moonshot.cn/v1 + moonshot-v1-128k。它们是 Kimi 的 OpenAI 兼容端点与早期模型名，在 Claude Code 中会遇到工具调用不可靠。官方为 Claude Code 提供的是 /anthropic 端点 + kimi-k2.5。

所有模型配置速查表（以各厂商官方文档为准）：

注意： 重要区分：

• 官方提供 Anthropic 兼容端点的厂商（DeepSeek、GLM、Kimi）：使用完整的 ANTHROPIC_* 环境变量集进行三级槽位映射，无需 --model。

• OpenAI 兼容端点厂商（千问、Ollama、其他中转）：仍需 --model 指定具体模型名。

• 统一使用 ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL 进行认证；不要使用已废弃的 OPENAI_API_KEY + OPENAI_BASE_URL 方式。

2.3.2.4 配置验证与诊断

无论使用上述哪种方案，配置完成后都应进行验证：

快速验证三步走：

# Step 1：启动 Claude Code
$ claude

# Step 2：在对话中检查当前状态
> /status
# 查看当前使用的模型、API Endpoint 是否正确

# Step 3：发送测试消息
> 你好，请告诉我你是什么模型

如果 AI 正常回复，说明配置成功。如果出现错误，请参考第三部分 3.7 节的 FAQ 进行排查。

提示：使用 /model 命令可以查看和切换当前模型，使用 /cost 命令可以实时查看 Token 消耗和费用。

2.3.3 接入 DeepSeek 的完整步骤

Claude 系列模型受限、GLM 套餐难抢时，DeepSeek 是一个值得考虑的国内直连方案。

DeepSeek 是国内极具性价比的 AI 模型，代码能力强。官方为 Claude Code 专门提供了 Anthropic 兼容端点，不需要走 OpenAI 兼容接口。

官方文档：https://api-docs.deepseek.com/zh-cn/quick_start/agent_integrations/claude_code。下面的配置与模型名与该文档一致，后续以官方文档为准。

Step 1：在 https://platform.deepseek.com/ 注册并获取 API Key。

Step 2：设置环境变量（注意 Base URL 是 /anthropic 端点，不是 /v1）

Windows PowerShell：

# 临时设置（仅当前终端窗口生效）
$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="<你的 DeepSeek API Key>"
$env:ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
$env:CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"
$env:CLAUDE_CODE_EFFORT_LEVEL="max"

macOS / Linux：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<你的 DeepSeek API Key>
export ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-flash
export CLAUDE_CODE_EFFORT_LEVEL=max

或使用配置文件（推荐，不需重启终端）：

// ~/.claude/settings.json
{
  "env": {
   "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
   "ANTHROPIC_AUTH_TOKEN": "<你的 DeepSeek API Key>",
   "ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
   "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
   "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
   "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
   "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash",
   "CLAUDE_CODE_EFFORT_LEVEL": "max"
  }
}

Step 3：进入项目目录，启动 Claude Code

cd /path/to/my-project
claude

启动后无需传 --model 参数，Claude Code 会通过环境变量调用 DeepSeek 官方示例中的模型映射。

选择主题：直接按数字即可


按回车继续：


确认目录：回车即可


提示：DeepSeek 模型名、可用端点和 Claude Code 兼容能力会随官方迭代变化。实际使用前请打开上面的官方文档核对，不要照抄旧教程里的模型名。

Step 4：验证

> /status

在 cc 会话中输入 /status，可看到当前 Base URL 和模型是否已切换到 DeepSeek。

注意： 常见踩坑：如果你之前使用过 https://api.deepseek.com/v1（OpenAI 兼容端点）+ claude --model deepseek-chat 的老写法，建议改为 DeepSeek 官方 Claude Code 文档中的 Anthropic 兼容端点 https://api.deepseek.com/anthropic。


2.3.4 多模型并存管理：cc-switch 可视化切换工具

上面几类方案你并不需要"二选一"——很多人的真实使用场景是：今天偶尔走 Anthropic 官方、明天切中转、后天干脆用 DeepSeek，偶尔还要用 GLM Coding Plan 套餐。手动改环境变量太麻烦，这时候就需要一个专门的多模型管理器。

cc-switch 是社区开源的一款桌面小工具，可以让你在多个 Claude Code 配置间一键切换。

• 项目地址：https://github.com/farion1231/cc-switch

• 下载：进入 Releases 页面，选对应系统（Windows、macOS、Linux）的安装包

• 使用：打开 cc-switch → 点击“新增” → 填入 API Key 和 BaseURL → 起个名字（如 “Anthropic-官方”、“DeepSeek”、“GLM-CodingPlan”）保存 → 需要哪个点哪个

工作机制：cc-switch 把你配置的多个 API Key 和 BaseURL 存起来，选择哪个就自动修改对应的环境变量，然后重启终端运行 claude 就生效。

注意： 最容易翻车的坑（必看）：切换 cc-switch 一定要在启动 claude 之前！如果你已经在 cc 会话里了再去 cc-switch 切换，是切不动的——环境变量在进程启动时就被加载到内存了。正确顺序是：先 cc-switch 选定配置 → 重启终端 → 运行 claude。很多新手都在这里上过当。

提示： 适用人群：如果你只用一家服务商，直接走上面配置方案里的 settings.json 即可，不需要 cc-switch。它是为"多模型重度用户"准备的。