Claude Code 中文完全指南

从安装到熟练 —— 配置、第三方 API 接入、成本优化、报错排查

Claude Code 是什么

Claude Code 是 Anthropic 官方的命令行编程助手。它跑在终端里，能直接读写你的项目文件、执行命令、跑测试、提交 Git —— 不是补全插件，是一个能自己动手干活的 Agent。

和 Cursor、Copilot 这类工具的核心区别：Claude Code 以整个代码库为工作单元，而不是当前打开的这个文件。它会自己去找相关文件、理解项目结构、跨文件改代码。

适合的场景

场景	说明
跨文件重构	改一个接口，把所有调用方一起改掉
从零实现功能	描述需求，它自己找位置、写代码、加测试
排查 Bug	给它报错信息，它自己复现、定位、修
读陌生项目	让它先给你讲清楚架构再动手
批量修改	统一改配置、升级依赖、迁移 API

安装

前置要求

Node.js 18 或更高版本
macOS、Linux，或 Windows（推荐 WSL，原生也可用）

npm 安装

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

验证

claude --version

更新

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

配置官方 API

官方有两种付费方式。

方式一：订阅（Pro / Max）

claude
# 首次启动会引导浏览器登录

订阅	价格	可用模型	限制
Pro	$20/月	Sonnet	不含 Opus，有 5 小时用量窗口
Max 5x	$100/月	Sonnet + Opus	有 5 小时用量窗口
Max 20x	$200/月	Sonnet + Opus	有 5 小时用量窗口

⚠️ Pro 用不了 Opus。 这是很多人踩的坑 —— 订了 Pro 才发现最强的模型不在里面。

方式二：API Key 按量付费

export ANTHROPIC_API_KEY="sk-ant-your-key"
claude

按 Token 实际用量计费，没有窗口限制，但需要外币信用卡充值。

配置第三方 API（中转网关）

如果你遇到下面任一情况，第三方网关是更实际的选择：

没有外币信用卡
不想为了偶尔用 Opus 付 $100/月
被 5 小时窗口卡住过
想在一个 Key 下同时用 Claude 和 GPT

配置方法

Claude Code 通过两个环境变量支持任意兼容 Anthropic 协议的网关：

export ANTHROPIC_BASE_URL="https://your-gateway.com/api"
export ANTHROPIC_AUTH_TOKEN="sk-your-key"

注意是 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY。用错变量名会导致 Claude Code 仍然走官方地址。

持久化配置

macOS / Linux — 写进 ~/.zshrc 或 ~/.bashrc：

echo 'export ANTHROPIC_BASE_URL="https://your-gateway.com/api"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="sk-your-key"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell：

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://your-gateway.com/api", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-your-key", "User")
# 重开终端生效

Windows CMD：

setx ANTHROPIC_BASE_URL "https://your-gateway.com/api"
setx ANTHROPIC_AUTH_TOKEN "sk-your-key"

验证是否生效

claude
# 进入后输入 /status，确认 API 地址是你配置的网关

可选网关

自建方案见 awesome-ai-api-gateway（one-api / new-api / LiteLLM 等）。

不想折腾服务器的话，Leonis AI 是开箱即用的托管网关：一个 Key 同时接 Claude、GPT、Gemini、Grok 共 114 个模型，国内直连，支持 Prompt 缓存，用量明细可查。

export ANTHROPIC_BASE_URL="https://ai.svtun.cn"
export ANTHROPIC_AUTH_TOKEN="sk-your-key"
claude

核心用法

启动

cd your-project
claude

常用斜杠命令

命令	作用
`/clear`	清空对话上下文（最重要的省钱命令）
`/compact`	压缩上下文，保留要点
`/model`	切换模型（Opus / Sonnet / Haiku）
`/status`	查看当前配置、API 地址、Token 用量
`/cost`	查看本次会话花费
`/init`	生成 `CLAUDE.md` 项目说明文件
`/review`	审查代码改动
`/help`	全部命令

键盘快捷键

快捷键	作用
`Esc`	打断当前生成
`Esc` `Esc`	回退到上一轮对话
`Ctrl+C`	取消当前输入
`Ctrl+D`	退出
`Shift+Tab`	切换自动接受编辑模式
`!` 开头	直接执行 shell 命令

CLAUDE.md — 项目记忆

在项目根目录建 CLAUDE.md，Claude Code 每次启动都会读它。这是让它"懂你的项目"最有效的方式。

# 项目说明

## 技术栈
Next.js 15 (App Router) + TypeScript + Tailwind + Prisma + PostgreSQL

## 目录约定
- `src/app/` 路由
- `src/components/ui/` 基础组件（shadcn/ui，不要手改）
- `src/lib/` 工具函数

## 编码规范
- 组件用函数式 + 具名导出
- 数据获取一律用 Server Component，不要在客户端 fetch
- 提交前必须跑 `pnpm lint && pnpm typecheck`

## 不要做的事
- 不要改 `src/components/ui/` 下的文件
- 不要引入新的状态管理库，项目已用 zustand
- 不要在没有测试的情况下改 `src/lib/billing/`

用 /init 可以让它自动生成一份初稿，再手动改。

成本优化

Claude Code 的账单结构和普通对话完全不同 —— 大头不是你打的字，是每轮重发的项目上下文。

先理解账单构成

一轮 Claude Code 请求包含四类 Token：

类型	说明	相对价格
Input	本轮新增的输入	基准
Output	模型生成的内容	最贵（约 5 倍 Input）
Cache Write	首次写入缓存的上下文	约 1.25 倍 Input
Cache Read	命中缓存的重复上下文	约 0.1 倍 Input

长会话里，Cache Read 往往占总 Token 量的 60%~90%。所以：

网关是否支持 Prompt Caching，直接决定长会话成本能差好几倍。

五条实操建议

1. 日常用 Sonnet，卡关再切 Opus

Opus 单次请求成本约为 Sonnet 的 5 倍。绝大多数任务 Sonnet 完全够用。

/model sonnet     # 日常
/model opus       # 卡住了再切

2. 及时 `/clear`

上下文越长，每轮重发的 Token 越多，成本是累积增长的。换一个任务就 /clear，不要一个会话干到底。

任务之间没有关联时，/clear 能立刻把成本打回起点。

3. 配置 `.claudeignore`

把不需要读的东西排除掉：

node_modules/
.next/
dist/
build/
coverage/
*.lock
pnpm-lock.yaml
package-lock.json
*.min.js
*.map
public/assets/
*.png
*.jpg
*.mp4
*.pdf
.git/

一个没配 .claudeignore 的项目，可能光扫 node_modules 就烧掉几十万 Token。

4. 精确指定文件

❌ 帮我优化一下项目性能
✅ 优化 src/app/dashboard/page.tsx 的首屏加载，重点看数据获取部分

模糊的指令会让它满项目找文件，明确的指令直接命中。

5. 用 `/compact` 而不是硬撑

上下文接近上限时，/compact 会把历史压缩成摘要，保留关键信息但大幅缩短长度。比继续硬撑便宜得多。

成本自查

/cost      # 本次会话花费
/status    # 累计 Token 用量

常见报错排查

`Invalid API key` / `401 Unauthorized`

依次检查：

变量名是不是写成了 ANTHROPIC_API_KEY？用第三方网关必须用 ANTHROPIC_AUTH_TOKEN
环境变量生效了吗？echo $ANTHROPIC_AUTH_TOKEN
改完 ~/.zshrc 后 source 了吗？或者重开终端
Key 有没有多余的空格、引号、换行

# 快速验证
curl -s https://your-gateway.com/api/v1/messages \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

配了 BASE_URL 但还是走官方

env | grep -i anthropic

常见原因：

同时设了 ANTHROPIC_API_KEY，它的优先级更高 → unset ANTHROPIC_API_KEY
之前用 claude login 登录过，本地凭据优先 → claude logout 后重试
IDE 集成终端没继承新环境变量 → 重启 IDE

`Context low` / 上下文超限

/compact     # 优先：压缩历史
/clear       # 或者：直接清空重来

预防：配好 .claudeignore，别让它读无关文件。

请求超时 / 卡住不动

Esc 打断
检查网络到网关的连通性
换个模型试试（/model sonnet）
复杂任务拆成小步骤，一次让它做太多容易卡

Windows 上表现异常

Windows 原生终端对 ANSI 转义、路径分隔符的处理和 Unix 不同。推荐用 WSL2：

wsl --install
# 进入 WSL 后按 Linux 方式安装配置

`429 Rate limit`

官方订阅：撞上 5 小时窗口了，等窗口重置
第三方网关：上游限流，稍后重试或换通道

进阶技巧

计划模式

复杂任务先让它出方案，你确认后再动手：

Shift+Tab   # 切换到 Plan Mode

避免它上来就改一堆文件，改错了还得回滚。

自定义斜杠命令

在 .claude/commands/ 下建 Markdown 文件，文件名就是命令名：

<!-- .claude/commands/review-pr.md -->
审查当前分支相对 main 的所有改动，重点关注：
1. 是否有未处理的错误分支
2. 是否有 N+1 查询
3. 是否缺少测试
4. 命名是否符合项目规范

按严重程度排序输出，每条给出文件名和行号。

之后输入 /review-pr 即可调用。

Hooks

在 .claude/settings.json 里配置自动化动作：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "pnpm lint --fix $CLAUDE_FILE_PATHS" }
        ]
      }
    ]
  }
}

每次改完文件自动跑 lint 修复。

管道用法

# 从 stdin 读
cat error.log | claude -p "分析这段报错，给出修复方案"

# 单次执行，不进交互
claude -p "把 README 翻译成英文并保存为 README.en.md"

# 结合 git
git diff | claude -p "给这些改动写一条 commit message"

多目录工作

claude --add-dir ../shared-lib --add-dir ../api-types

让它同时看到多个仓库，适合 monorepo 或前后端分离的项目。

License

MIT

_{关键词 · Claude Code · Claude Code 教程 · Claude Code 中文 · Claude Code 配置 · Claude Code 中转 ·
Claude API · Anthropic API · AI 编程助手 · AI 中转 · API 中转 · claude code 报错 · claude code 省钱}

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
LICENSE		LICENSE
README.md		README.md

仓库	说明
claude-code-guide	Claude Code 中文完全指南
codex-cli-guide	Codex CLI 完全配置手册
gemini-api-guide	Gemini API 中文配置手册
cc-switch-guide	多配置一键切换
awesome-ai-api-gateway	AI 网关与中转生态精选
ai-api-pricing	成本计算与缓存经济学
ai-client-configs	20+ 客户端配置模板
全部 114 个模型	在线可搜索模型清单

Folders and files

Latest commit

History

Repository files navigation

Claude Code 中文完全指南

目录

Claude Code 是什么

适合的场景

安装

前置要求

npm 安装

验证

更新

配置官方 API

方式一：订阅（Pro / Max）

方式二：API Key 按量付费

配置第三方 API（中转网关）

配置方法

持久化配置

验证是否生效

可选网关

核心用法

启动

常用斜杠命令

键盘快捷键

CLAUDE.md — 项目记忆

成本优化

先理解账单构成

五条实操建议

1. 日常用 Sonnet，卡关再切 Opus

2. 及时 /clear

3. 配置 .claudeignore

4. 精确指定文件

5. 用 /compact 而不是硬撑

成本自查

常见报错排查

Invalid API key / 401 Unauthorized

配了 BASE_URL 但还是走官方

Context low / 上下文超限

请求超时 / 卡住不动

Windows 上表现异常

429 Rate limit

进阶技巧

计划模式

自定义斜杠命令

Hooks

管道用法

多目录工作

相关资源

本组织的其他项目

相关手册

官方文档

贡献

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors