VibeCoding

Claude Code

# Claude Code

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

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

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

# 安装

# 原生安装（推荐）

Windows PowerShell：

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

Windows CMD：

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

Windows 需先安装 Git for Windows (opens new window)。原生安装会在后台自动更新。

macOS / Linux / WSL：

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

# 其他方式

Homebrew（macOS）：

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

1
2

WinGet（Windows）：

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

1
2

# 启动

在项目目录下执行：

cd your-project
claude

1
2

首次使用会提示登录。

# 配置

# 配置目录

系统	路径	说明
Windows	`C:\Users\<用户名>\.claude`	用户配置根目录
macOS / Linux	`~/.claude`	用户配置根目录

# 配置文件层级

范围	路径	用途
组织策略	Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` Linux/WSL: `/etc/claude-code/CLAUDE.md` macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`	由 IT/DevOps 管理的组织级指令
项目	`./CLAUDE.md` 或 `./.claude/CLAUDE.md`	项目级指令，随版本控制共享
用户	`~/.claude/CLAUDE.md`	个人偏好，对所有项目生效
本地（不提交）	`./CLAUDE.local.md`	仅当前项目的个人偏好，建议加入 `.gitignore`

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

# 项目配置结构示例

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

1
2
3
4
5
6
7

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

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

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

变量	说明	示例
`ANTHROPIC_BASE_URL`	自定义 API 基础 URL（替代官方 `api.anthropic.com`）	`https://your-proxy.com/v1`
`ANTHROPIC_API_KEY`	中转站或网关提供的 API Key，作为 `X-Api-Key` 发送	由中转服务商提供
`HTTP_PROXY` / `HTTPS_PROXY`	仅需走 HTTP 代理时设置（不改 API 地址）	`http://127.0.0.1:7890`
`NO_PROXY`	不经过代理的地址，逗号分隔	`localhost,127.0.0.1`

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

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

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

1
2
3
4

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

Windows PowerShell（当前会话）：

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

1
2

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

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

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

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

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-proxy.com/v1",
    "ANTHROPIC_API_KEY": "your-transit-api-key"
  }
}

1
2
3
4
5
6

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

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-proxy.com/v1",
    "ANTHROPIC_API_KEY": "your-transit-api-key"
  }
}

1
2
3
4
5
6

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

# 使用代理但不改 API 地址

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

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

1
2
3
4

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

请求头报错：若网关对 anthropic-beta 等实验头不支持，可关闭实验性标头：
```
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
```
1
调试：查看实际使用的 URL 与认证方式：
- 会话内输入斜杠命令：/status
- 或开启请求日志：export ANTHROPIC_LOG=debug 后重启 claude

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

# 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 所在目录）：

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

1
2

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

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

	CLAUDE.md	自动记忆
谁写	你	Claude
内容	指令与规则	学习到的模式（构建命令、调试心得等）
加载	每个会话完整加载	每个会话加载前 200 行（MEMORY.md）

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

# 规则（.claude/rules/）

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

# 目录结构

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

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    └── api-design.md

1
2
3
4
5
6

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

# 路径限定规则（frontmatter）

---
paths:
  - "src/api/**/*.ts"
  - "tests/**/*.test.ts"
---

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

1
2
3
4
5
6
7
8
9

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

# 用户级规则

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

# Skills

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

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

# 存放位置

位置	路径	适用
企业	见托管设置 (opens new window)	组织内所有用户
个人	`~/.claude/skills/<skill-name>/SKILL.md`	你的所有项目
项目	`.claude/skills/<skill-name>/SKILL.md`	当前项目
插件	插件目录下的 `/skills/<skill-name>/SKILL.md`	启用该插件的环境

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

# Skill 目录结构

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

1
2
3
4
5

# SKILL.md 基本写法

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

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

1
2
3
4
5
6
7
8
9
10

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

# 内置捆绑 Skills

命令	说明
`/debug [描述]`	根据当前会话调试日志排查问题，可选描述聚焦范围
`/batch <描述>`	在代码库中并行做大范围修改：拆成 5–30 个单元，你批准后在各 git worktree 中并行执行并提 PR（需 git）
`/simplify [焦点]`	审查最近修改的文件，查找复用、质量、效率问题并修复；可加可选焦点如 `focus on memory efficiency`

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

# 常用命令（CLI）

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

# 会话与查询

命令	说明
`claude`	进入交互式会话
`claude "初始提示"`	带初始提示进入交互会话
`claude -p "提示"`	非交互：执行一次查询并退出（管道、脚本友好）
`claude -c`	继续当前目录下最近一次对话
`claude -c -p "提示"`	在最近对话基础上用 -p 再执行一次
`claude -r "会话名或ID" "提示"`	恢复指定会话并可选带提示

# 认证与更新

命令	说明
`claude auth login`	登录（可加 `--email`、`--sso`）
`claude auth logout`	登出
`claude auth status`	查看登录状态（`--text` 人类可读）
`claude update`	更新到最新版本
`claude -v`	显示版本号

# 常用标志

标志	说明
`--model sonnet` / `--model opus`	指定模型别名
`--append-system-prompt "..."`	在默认系统提示后追加指令（推荐）
`--tools "Bash,Edit,Read"`	限制可用工具；`"default"` 为全部
`--add-dir ../other-lib`	让 Claude 可访问额外目录
`-w [名称]` / `--worktree [名称]`	在独立 git worktree 中运行（并行会话）
`--teleport`	在本地终端恢复之前在 Web 上创建的会话
`--remote "任务描述"`	在 claude.ai 上创建新的 Web 会话

# 管道与脚本示例

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

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

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

1
2
3
4
5
6
7
8

完整选项见 CLI 参考 (opens new window)。

# 内存、上下文与 Token 优化

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

# 内存与缓存

机制	说明	配置建议
自动记忆	Claude 将学习到的内容写入 `~/.claude/projects/<project>/memory/`，其中 `MEMORY.md` 前 200 行在每次会话加载	默认开启。不需跨会话学习时可设 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` 禁用
Prompt 缓存	对系统提示等重复内容做缓存，降低重复 token 成本	默认开启，一般不要关闭。仅当网关/代理不支持时再按模型禁用：`DISABLE_PROMPT_CACHING_SONNET=1` 等
CLAUDE.md 体积	主 CLAUDE.md 在会话开始时完整加载，行数越多占上下文越多	建议单文件 ≤200 行；详细工作流放到 Skills 按需加载

# 上下文与自动压缩

自动压缩 (auto-compact)：当上下文使用率接近上限（约 95%）时，Claude 会总结历史对话以腾出空间。可通过环境变量提前触发压缩，减小单次对话的 token 占用：
```
# 在 50% 使用率时即触发压缩（默认约 95%）
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
```
1
2
取值 1–100，仅可调低、不能高于默认阈值。
手动与习惯：
- /compact：立即触发压缩；可带指令聚焦保留内容，例如：/compact Focus on code samples and API usage。
- /clear：清空当前对话上下文，任务切换时使用可避免陈旧内容持续占 token；清空前可用 /rename 命名会话，之后用 /resume 找回。
- /context：查看当前占用上下文的内容（如 MCP 工具定义、大块附件）。

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

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

1
2

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

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

变量 / 设置	说明	推荐
CLAUDE_CODE_MAX_OUTPUT_TOKENS	单次回复最大输出 token，默认 32,000，最大 64,000	默认即可；增大可提高单次输出上限，但会更早触发自动压缩，一般不必改
BASH_MAX_OUTPUT_LENGTH	Bash 命令输出最大字符数，超出会截断	按需设置，避免超大日志占满上下文
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS	单次文件读取的 token 上限	仅在需要读很大文件时适当提高

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

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000"
  }
}

1
2
3
4
5
6

# 模型与扩展思考

模型选择：日常编码用 Sonnet 即可，成本低于 Opus；复杂架构或多步推理再用 Opus；subagent、简单任务可用 Haiku。会话内用 /model 切换，或在 /config 设默认。
扩展思考 (thinking)：默认启用且预算较大（约 31,999 token），思考 token 按输出计费。简单任务可在 /config 关闭思考，或降低预算：
```
export MAX_THINKING_TOKENS=8000
```
1
设为 0 可完全关闭。Opus 4.6 / Sonnet 4.6 也可在 /model 中调低「努力级别」以省 token。

# MCP 与工具占用的上下文

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

工具搜索 (tool search)：当 MCP 工具描述超过上下文约 10% 时，Claude Code 会延迟加载、按需拉取工具。可把阈值调低以更早启用：
```
export ENABLE_TOOL_SEARCH=auto:5
```
1
（即 5% 时触发；auto 默认 10%，auto:N 为自定义百分比。）
/mcp：查看已配置的 servers，关闭当前会话用不到的，减少常驻工具定义。

# 查看用量与状态

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

# 推荐习惯小结

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

官方完整说明见有效管理成本 (opens new window)。

# 延伸阅读

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

帮助我改善此页面

上次更新: 2026/03/11, 14:06:00

← Cursor OpenClaw→