Claude Code 教程：从安装配置到自定义工具调用的完整实战指南

为什么是 Claude Code，而不是其他 CLI

目前主流的 AI 编码 CLI 有三条线：OpenAI 的 Codex、Google 的 Gemini CLI、Anthropic 的 Claude Code。三者底层模型各有侧重——Codex 接 GPT-5.4/5.5 系列，Gemini CLI 接 Gemini 3，Claude Code 则直连 Claude Sonnet 4.6 和 Opus 4.8。

区别不只在模型。Claude Code 的设计哲学更贴近"代理式编辑器"：它能读取整个项目目录、写文件、执行 shell 命令、调用自定义工具，整个交互发生在终端里，不需要打开任何 GUI。对于喜欢 terminal-first 工作流的开发者，这个设计非常顺手。

另一个务实理由是上下文窗口。Sonnet 4.6 的上下文长度达到 200K tokens，处理中等规模代码库（5 万行以内）时基本不需要手动裁剪上下文，这比早期版本需要频繁 /clear 的体验好很多。

---

安装与基础配置

环境要求：Node.js 18+ 或 Python 3.10+（取决于你用 npm 还是 pip 安装）。Claude Code 官方推荐 npm 路径：

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

安装完成后验证版本：

claude --version
# claude-code 1.x.x

配置 API Key：Claude Code 读取环境变量 ANTHROPIC_API_KEY。最简单的方式是写入 shell 配置文件：

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

如果你通过第三方兼容层（比如 XycAi 词元平台）接入，还需要指定 base URL：

export ANTHROPIC_BASE_URL="https://api.xyc.ai/v1"

选择默认模型：通过 claude config 命令设置默认模型，推荐日常任务用 Sonnet 4.6（速度与质量均衡），复杂重构任务切换到 Opus 4.8：

claude config set model claude-sonnet-4-6

---

核心使用模式：从单文件到整个 repo

Claude Code 有三种典型使用模式，按复杂度递进：

1. 单次问答模式（非交互）

claude -p "解释这个函数的时间复杂度" < utils.py

适合在脚本里嵌入，或者做 CI 里的自动化 code review。

2. 交互模式（最常用）

在项目根目录直接运行 claude，它会自动扫描目录结构并加载上下文。进入交互后，几个高频指令：

指令	作用
/add <file>	手动把某个文件加入当前上下文
/clear	清空对话历史，保留配置
/model opus	临时切换到 Opus 4.8 处理复杂任务
/cost	查看本次会话的 token 消耗和费用

3. 代理模式（Agentic Mode）

这是 Claude Code 最有价值的部分。加上 --dangerously-accept-edits 标志后，Claude Code 可以直接修改文件而不需要每步确认。适合有完整 git 保护的项目：

claude --dangerously-accept-edits

实际例子：让它给一个 Express.js 项目补全所有缺失的 JSDoc 注释——

> 扫描 src/ 目录下所有 .js 文件，找出没有 JSDoc 注释的 export 函数，逐个补全，格式参考 src/auth/login.js

Claude Code 会先列出计划，确认后批量写入，整个过程大约 2-3 分钟完成 40+ 个函数的注释补全，手工做要一两个小时。

---

自定义工具调用：把 Claude Code 接入你自己的系统

Claude Code 支持通过 CLAUDE.md 文件向模型注入项目级上下文，以及通过 MCP（Model Context Protocol）接入外部工具。这是它区别于普通聊天补全的核心能力。

CLAUDE.md 配置

在项目根目录创建 CLAUDE.md，内容会在每次会话开始时自动注入：

# 项目约定
- 包管理器：pnpm，禁止使用 npm install
- 测试框架：Vitest，测试文件放在 __tests__/ 目录
- 提交规范：Conventional Commits，类型限 feat/fix/chore/docs
- 数据库：PostgreSQL 16，ORM 用 Drizzle，禁止写裸 SQL

这样 Claude Code 在整个项目里都会遵守这些约定，不会突然用 npm 或者 Prisma。

MCP 工具接入

MCP 让 Claude Code 能调用你定义的外部函数。配置文件放在 ~/.claude/mcp.json：

{
  "tools": [
    {
      "name": "run_tests",
      "description": "运行项目测试套件",
      "command": "pnpm test --reporter=json",
      "parse": "json"
    },
    {
      "name": "query_db",
      "description": "执行只读 SQL 查询并返回结果",
      "command": "psql $DATABASE_URL -c '{query}' --csv"
    }
  ]
}

配置好之后，可以在对话里直接说"跑一下测试，看哪些用例挂了，帮我修复"——Claude Code 会调用 run_tests，读取 JSON 输出，定位失败用例，然后修改代码，再跑一次验证。这个闭环在复杂 bug 修复场景下效率提升非常明显。

---

真实项目集成：几个值得注意的细节

成本控制：Opus 4.8 单价约是 Sonnet 4.6 的 5 倍，日常编码任务没必要用旗舰模型。我的习惯是用 Sonnet 4.6 做 80% 的工作，只在架构设计或复杂算法问题上切换 Opus 4.8。通过 /cost 随时监控，月均消耗控制在 $20-$40 之间完全可行。

git 工作流保护：开启代理模式前，确保工作区干净（git status 无未提交变更），每次大任务前新建分支。Claude Code 不会自动提交，但它会覆写文件，分支隔离是唯一的后悔药。

上下文管理：200K 上下文听起来够用，但大型 monorepo 里依然要注意。用 /add 精确指定相关文件，比让 Claude Code 自己全量扫描更快、更便宜，也更准确。

与 CI 集成：在 GitHub Actions 里调用 Claude Code 做 PR code review 是一个低成本高价值的实践。非交互模式 + -p 参数输出结构化 JSON，可以直接作为 PR comment 发回去，整个 pipeline 加 2-3 分钟。

---

如果你在用 Claude Code 或者想对比 Codex、Gemini CLI 的实际效果，值得看看 XycAi 词元平台（https://www.xyc.ai）。它是 OpenAI 兼容 API，一个接入点打通 200+ 全球模型，官方 Claude / GPT / Gemini 模型低至官方价 1.4 折起，Claude Code、Codex、Gemini CLI 都支持一键切换接入，全球 CN2 节点延迟低至 5ms，企业侧持大模型算法备案号，可以开全球发票，省去各平台分别申请账号的麻烦。