Claude Code

Claude Code

Claude Code 是一个代理编码工具，可以读取你的代码库、编辑文件、运行命令，并与你的开发工具集成。可在终端、IDE、桌面应用和浏览器中使用。

Claude Code 由 AI 驱动，帮助你构建功能、修复错误和自动化开发任务。它理解整个代码库，可跨多个文件和工具完成任务。

• 官方文档：https://code.claude.com/docs/zh-CN
• 环境：需 Claude 订阅 或 Anthropic Console 账户；Terminal CLI 和 VS Code 也支持 第三方提供商。

安装

原生安装（推荐）

Windows PowerShell：

1
irm https://claude.ai/install.ps1 | iex

Windows CMD：

1
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows 需先安装 Git for Windows。原生安装会在后台自动更新。

macOS / Linux / WSL：

1
curl -fsSL https://claude.ai/install.sh | bash

其他方式

Homebrew（macOS）：

1
brew install --cask claude-code
2
# 手动更新：brew upgrade claude-code

WinGet（Windows）：

1
winget install Anthropic.ClaudeCode
2
# 手动更新：winget upgrade Anthropic.ClaudeCode

启动

在项目目录下执行：

1
cd your-project
2
claude

首次使用会提示登录。

配置

配置目录

配置文件层级

更具体的位置优先于更广泛的位置。

项目配置结构示例

1
your-project/
2
├── CLAUDE.md              # 或 .claude/CLAUDE.md
3
├── CLAUDE.local.md        # 可选，不提交
4
└── .claude/
5
    ├── config.json        # 项目设置
6
    ├── rules/             # 规则文件（见下文）
7
    └── skills/            # 项目级 skills

国内环境：自定义模型地址 / 中转站

在国内或内网环境下，可通过自定义 API 基础 URL 将请求发往自建网关、中转服务或兼容 Anthropic 的代理，避免直连官方接口。

方式一：环境变量（推荐）

注意：ANTHROPIC_BASE_URL 一般需带路径 /v1，例如 https://api.example.com/anthropic/v1。

macOS / Linux / WSL（当前终端生效）：

1
export ANTHROPIC_BASE_URL="https://your-proxy.com/v1"
2
export ANTHROPIC_API_KEY="your-transit-api-key"
3
# 若中转站在国内、仅终端走代理访问外网时可设：
4
# export HTTPS_PROXY="http://127.0.0.1:7890"

永久生效可写入 ~/.bashrc 或 ~/.zshrc 后执行 source ~/.zshrc。

Windows PowerShell（当前会话）：

1
$env:ANTHROPIC_BASE_URL = "https://your-proxy.com/v1"
2
$env:ANTHROPIC_API_KEY = "your-transit-api-key"

永久生效：在系统「环境变量」中新建用户变量 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY，或采用下文「方式二」用 settings.json 注入。

方式二：通过 settings.json 注入环境变量

在用户或项目设置中通过 env 为每次会话注入变量，便于团队统一或本机持久化：

用户级（~/.claude/settings.json）：

1
{
2
  "env": {
3
    "ANTHROPIC_BASE_URL": "https://your-proxy.com/v1",
4
    "ANTHROPIC_API_KEY": "your-transit-api-key"
5
  }
6
}

项目级（.claude/settings.json，可提交）或仅本机（.claude/settings.local.json，建议加入 .gitignore）：

1
{
2
  "env": {
3
    "ANTHROPIC_BASE_URL": "https://your-proxy.com/v1",
4
    "ANTHROPIC_API_KEY": "your-transit-api-key"
5
  }
6
}

使用中转/网关时，通常用 API Key 认证而非 Claude.ai 登录；若仍希望用 OAuth，需中转服务支持对应登录流。

使用代理但不改 API 地址

若只希望流量走 HTTP/HTTPS 代理（例如科学上网），不更换 API 提供商：

1
export HTTPS_PROXY="http://127.0.0.1:7890"
2
export HTTP_PROXY="http://127.0.0.1:7890"
3
# 可选：某些域名直连
4
export NO_PROXY="localhost,127.0.0.1"

第三方网关 / 中转常见问题

• 请求头报错：若网关对 anthropic-beta 等实验头不支持，可关闭实验性标头：

  1
  export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

• 调试：查看实际使用的 URL 与认证方式：
  • 会话内输入斜杠命令：/status
  • 或开启请求日志：export ANTHROPIC_LOG=debug 后重启 claude

官方说明：LLM 网关与代理配置见 第三方集成，完整环境变量见 设置 - 环境变量。

CLAUDE.md

CLAUDE.md 是 Markdown 文件，用于为项目、个人工作流或组织提供持久指令。纯文本编写，每个会话开始时由 Claude 读取。

作用与限制

• 作为上下文加载，不是强制配置；指令越具体、简洁，遵循越稳定。
• 建议单文件控制在 200 行以内，过长可拆成 导入 或 .claude/rules/。
• 用标题和列表分组，便于 Claude 和人类阅读。

编写建议

• 具体：如「API 在 src/api/handlers/」优于「保持文件有组织」。
• 可验证：如「提交前运行 npm test」优于「测试你的更改」。
• 一致：避免与其它 CLAUDE.md 或 rules 冲突；在 monorepo 中可用 claudeMdExcludes 排除无关指令。

快速生成项目 CLAUDE.md

在会话中运行 /init：Claude 会分析代码库并生成或改进 CLAUDE.md（构建命令、测试、约定等）。已有文件时不会覆盖，只建议改进。

导入其他文件

在 CLAUDE.md 中用 @path 引用其他文件，会在启动时一并加载（相对路径相对于该 CLAUDE.md 所在目录）：

1
有关项目概述见 @README，可用脚本见 @package.json。
2
Git 工作流见 @docs/git-instructions.md

支持递归导入，最大深度 5。首次遇到外部导入时会提示确认。

自动记忆（与 CLAUDE.md 互补）

自动记忆默认开启，存储于 ~/.claude/projects/<project>/memory/。会话中输入 /memory 可查看、编辑或开关自动记忆。

规则（.claude/rules/）

用于把指令拆成多个主题文件，便于维护，并可按文件路径限定生效范围，节省上下文。

目录结构

在项目 .claude/rules/ 下放 Markdown 文件，可分子目录：

1
.claude/
2
├── CLAUDE.md
3
└── rules/
4
    ├── code-style.md
5
    ├── testing.md
6
    └── api-design.md

• 无 paths 的规则：会话启动时加载，与主 CLAUDE.md 同优先级。
• 带 paths 的规则：仅在 Claude 处理匹配文件时加载。

路径限定规则（frontmatter）

1
---
2
paths:
3
  - "src/api/**/*.ts"
4
  - "tests/**/*.test.ts"
5
---
6

7
# API 开发规则
8
- 所有 API 端点必须做输入校验
9
- 使用统一错误响应格式

常用 glob：**/*.ts、src/**/*、*.md。规则与 Skills 的区别：规则在会话/打开匹配文件时加载；Skills 可在调用或相关时再加载。

用户级规则

~/.claude/rules/ 下的规则对你本机所有项目生效；项目规则优先级更高。

Skills

Skills 扩展 Claude 的能力：把可复用工作流写成 SKILL.md，Claude 会在相关时使用，或通过 /skill-name 直接调用。

• 兼容 Agent Skills 开放标准。
• 旧版 .claude/commands/ 下的文件仍可用，与 skills 合并为同一套「斜杠命令」。

存放位置

同名时优先级：企业 > 个人 > 项目。

Skill 目录结构

1
my-skill/
2
├── SKILL.md           # 必需，主说明与 frontmatter
3
├── template.md        # 可选，模板
4
└── examples/
5
    └── sample.md      # 可选，示例

SKILL.md 基本写法

1
---
2
name: explain-code
3
description: 用图示和类比解释代码。在用户问「这是怎么工作的」时使用。
4
---
5

6
解释代码时请：
7
1. 先给一个生活化类比
8
2. 用 ASCII 图画出流程或结构
9
3. 逐步说明代码在做什么
10
4. 指出常见误区

• name：对应 /name 斜杠命令（小写、数字、连字符，建议 ≤64 字符）。
• description：推荐填写，供 Claude 判断何时自动加载。
• disable-model-invocation: true：仅允许用户通过 /name 调用，不自动触发。
• user-invocable: false：从 / 菜单隐藏，只作背景知识。

内置捆绑 Skills

更多 frontmatter（如 allowed-tools、context: fork、hooks）见 官方 Skills 文档。

常用命令（CLI）

在项目目录下使用，以下为常用子集。

会话与查询

认证与更新

常用标志

管道与脚本示例

1
# 分析日志
2
tail -f app.log | claude -p "发现异常时总结并告警"
3

4
# 批量翻译并提 PR
5
claude -p "把新增文案翻译成法语并提 PR"
6

7
# 按变更文件做安全审查
8
git diff main --name-only | claude -p "对这些变更文件做安全审查"

完整选项见 CLI 参考。

内存、上下文与 Token 优化

成本随上下文大小增长：上下文越大，每条消息消耗的 token 越多。Claude Code 通过 Prompt 缓存（减少系统提示等重复内容的成本）和 自动压缩（接近上下文上限时总结对话历史）做内置优化。下面是可以主动配置和习惯上可做的优化。

内存与缓存

上下文与自动压缩

• 自动压缩 (auto-compact)：当上下文使用率接近上限（约 95%）时，Claude 会总结历史对话以腾出空间。可通过环境变量提前触发压缩，减小单次对话的 token 占用：

  1
  # 在 50% 使用率时即触发压缩（默认约 95%）
  2
  export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

  取值 1–100，仅可调低、不能高于默认阈值。

• 手动与习惯：

  • /compact：立即触发压缩；可带指令聚焦保留内容，例如：/compact Focus on code samples and API usage。
  • /clear：清空当前对话上下文，任务切换时使用可避免陈旧内容持续占 token；清空前可用 /rename 命名会话，之后用 /resume 找回。
  • /context：查看当前占用上下文的内容（如 MCP 工具定义、大块附件）。

• CLAUDE.md 中的压缩偏好：可在项目 CLAUDE.md 里写：

  1
  # Compact instructions
  2
  When you are using compact, please focus on test output and code changes

• 1M 上下文：若不需要超长上下文或出于合规关闭，可设 CLAUDE_CODE_DISABLE_1M_CONTEXT=1，1M 模型将不再出现在模型选择器中。

Token 与输出限制（推荐配置）

可通过 settings.json 的 env 统一注入（用户或项目级）：

1
{
2
  "env": {
3
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
4
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000"
5
  }
6
}

模型与扩展思考

• 模型选择：日常编码用 Sonnet 即可，成本低于 Opus；复杂架构或多步推理再用 Opus；subagent、简单任务可用 Haiku。会话内用 /model 切换，或在 /config 设默认。
• 扩展思考 (thinking)：默认启用且预算较大（约 31,999 token），思考 token 按输出计费。简单任务可在 /config 关闭思考，或降低预算：

  1
  export MAX_THINKING_TOKENS=8000

  设为 0 可完全关闭。Opus 4.6 / Sonnet 4.6 也可在 /model 中调低「努力级别」以省 token。

MCP 与工具占用的上下文

每个 MCP server 会向上下文注入工具定义。可做：

• 工具搜索 (tool search)：当 MCP 工具描述超过上下文约 10% 时，Claude Code 会延迟加载、按需拉取工具。可把阈值调低以更早启用：

  1
  export ENABLE_TOOL_SEARCH=auto:5

  （即 5% 时触发；auto 默认 10%，auto:N 为自定义百分比。）
• /mcp：查看已配置的 servers，关闭当前会话用不到的，减少常驻工具定义。

查看用量与状态

• /cost：当前会话的 token 使用与估算成本（API 用户）；订阅用户可用 /stats 看使用模式。
• 状态行：在 statusLine 配置 中可使用 context_window.used_percentage 等字段，实时显示上下文使用率。

推荐习惯小结

• 任务切换时 /clear，或给会话 /rename 后用 /resume 再续。
• CLAUDE.md 保持简短，工作流类指令放到 Skills，需要时再调用。
• 提示尽量具体（如指定文件/函数），减少无谓的代码库扫描。
• 大块日志、长测试输出可交给 subagent 或 hooks 预处理，只把摘要或关键行交给主会话。
• 复杂多步任务先用 Plan 模式（Shift+Tab）再实现，避免方向错误导致的重复消耗。

官方完整说明见 有效管理成本。

延伸阅读

• 快速入门 — 从探索代码到提交修复
• 常见工作流 — 推荐用法与模式
• 有效管理成本 — Token、上下文与成本优化
• 设置 — 配置文件与选项
• Hooks — 在操作前后执行 shell
• MCP — 连接外部数据与工具
• 故障排除