claude_guide/07_coding/7.2_cli.md at main · yeasy/claude_guide

7.2 Claude Code CLI 入门与基础运维

Claude Code 是 Anthropic 推出的专为开发者设计的终端工具。它不仅仅是一个 API 包装器，而是一个具有 Agentic Capabilities 的编程助手——可以直接读取文件系统、运行终端命令、甚至自动提交 Git commit。

7.2.1 安装与认证

安装

Claude Code 当前推荐优先使用原生安装器或系统包管理器；npm 仍可用，但更适合作为兼容路径。安装前先确认操作系统、shell、网络和账号满足官方 Advanced setup 的要求。

macOS、Linux 或 WSL：

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

在受管环境或生产工作站上，不要盲目执行远程脚本；可先下载脚本审阅，或优先使用 Homebrew、WinGet、apt/dnf/apk 等可审计的包管理器路径。

macOS 也可以使用 Homebrew：

brew install --cask claude-code

如果团队仍采用 npm 分发，可以使用：

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

认证

安装后直接运行：

claude

CLI 会引导浏览器完成登录。Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 等具备 Claude Code 权限的账号；免费 claude.ai 账号不等于拥有 Claude Code 访问权。脚本和 CI 场景不要复用交互式登录流程，应按官方 CLI 文档生成长期 token 或使用企业授权方式，例如：

claude setup-token

7.2.2 运行模式与认证机制

来源说明：本节部分内容基于社区对 Claude Code 源代码的逆向分析（HitCC 项目，CC BY 4.0），具体行为可能随版本更新而变化。

多种运行模式

Claude Code 支持多种运行模式以适应不同场景：

模式	用途	典型场景
TUI 交互模式	终端内的富文本交互界面	日常开发：`claude` 直接启动
Headless 无头模式	非交互式处理，输出文本或 JSON	CI/CD 流水线、脚本集成
Bridge 远程控制	允许外部程序（如 claude.ai）远程接管会话	`/remote-control` 跨端协作
SDK 模式	程序化调用 Claude Code 能力	应用程序集成、自动化工作流
IDE 插件	VS Code、JetBrains 等编辑器集成	IDE 内编码辅助

不同模式在启动时就会进入各自的代码路径，避免加载不必要的模块。

认证排障顺序

当你遇到认证问题时，先按当前官方文档列出的凭据来源逐层确认，不要把历史逆向结果当作稳定 ABI：

云供应商路径：如果启用了 Bedrock 或 Vertex AI，先检查对应的环境变量和云侧凭据链。
自定义 Authorization header：ANTHROPIC_AUTH_TOKEN 会作为 Authorization: Bearer ... 使用。
Anthropic API Key：ANTHROPIC_API_KEY 会作为 API key 使用；交互式订阅用户仍应优先通过 /login 登录。
apiKeyHelper：适合网关、Vault 或短期凭据轮换；官方文档明确其优先级低于 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY。
Claude.ai 登录态：面向订阅账户，由 Claude Code 管理本地安全存储。

CLAUDE_CODE_OAUTH_TOKEN 不应作为通用 API key 覆盖方案；只有在当前版本文档或企业部署说明明确要求时再使用。

此外，如果使用 Amazon Bedrock 或 Google Vertex AI 作为后端，需要通过专用环境变量启用：

# 使用 Bedrock 后端
export CLAUDE_CODE_USE_BEDROCK=1

# 使用 Vertex AI 后端
export CLAUDE_CODE_USE_VERTEX=1

不同的后端提供商有各自独立的认证实现，不共享代码路径。排查认证问题时，务必先确认当前使用的是哪个后端。

7.2.3 核心命令

交互模式

直接运行 claude 进入对话模式：

$ claude
> 帮我分析一下当前目录的结构。
(Claude runs `ls -R`)
当前目录包含 src, tests 和 docs...

> 把 src/utils.py 里的日志库从 logging 换成 structlog。
(Claude reads src/utils.py, edits, shows diff)

单次任务

claude "generate a commit message for the current changes"
claude "explain main.go"
claude "fix strict null checks"

Unix 哲学与管道：Piping

Claude Code 拥有高度的可组合性，遵循 Unix 哲学。你可以将日志、命令输出通过管道符 (|) 传给 Claude，进行串联处理：

# 监控日志并让 Claude 进行异常告警
tail -f app.log | claude -p "Slack me if you see any anomalies"

# 结合持续集成进行自动化处理
claude -p "translate new strings into French and raise a PR for review"

# 批量进行文件安全检查
git diff main --name-only | claude -p "review these changed files for security issues"

7.2.4 CLAUDE.md：项目记忆文件

CLAUDE.md 是 Claude Code 的项目记忆机制，让 Claude 在会话开始时获得稳定的项目上下文。它适合记录长期有效的规则、架构说明、常用命令和注意事项，不适合记录一次性任务状态、密钥、私人 token 或会频繁过期的事实。

什么是 CLAUDE.md？

CLAUDE.md 是一个特殊的 Markdown 文件，Claude Code 会在合适的位置读取它，并把内容作为项目上下文提供给模型。这意味着你无需重复解释项目结构、编码规范和常用命令；但它仍然是给模型看的上下文，不应被当成不可变的系统级安全边界。

文件位置

位置	作用域	典型用途
`~/.claude/CLAUDE.md`	用户级	个人偏好、常用工具、通用工作习惯
项目根目录 `CLAUDE.md`	项目级	架构、命令、编码规范、测试入口
`.claude/CLAUDE.md`	项目级	与项目内 `.claude/rules/` 搭配的主项目说明
`CLAUDE.local.md`	本地个人覆盖	不提交的本机路径、个人偏好、实验设置
`.claude/rules/*.md`	项目规则	可按路径或文件类型组织的规则文件

更稳妥的使用方式不是维护一份神秘的“优先级链”，而是把记忆按稳定性拆开：项目级事实写进项目记忆，个人偏好写进用户记忆，临时任务状态写进 issue、plan 或 checkpoint，密钥和敏感信息一律放在受控 secret 系统。

@import 文件导入

CLAUDE.md 支持 @path/to/import 语法导入其他文本文件：

@docs/coding-standards.md
@.claude/shared-rules.md

导入路径可以是相对路径或绝对路径；相对路径按包含该导入语句的文件所在目录解析，而不是按当前 shell 工作目录解析。导入可以递归，但官方文档限制最大深度为 4 跳。首次导入项目外文件时，按当前客户端策略可能需要用户批准。

CLAUDE.local.md：本地覆盖

CLAUDE.local.md 是专为个人配置设计的覆盖文件，典型用途包括：

个人的 API 密钥路径或环境变量
本地特有的构建命令（如不同的 Python 版本路径）
开发者个人偏好（如 diff 格式、日志级别）

因为 .local.md 通常被添加到 .gitignore，所以不会影响团队其他成员。

示例 CLAUDE.md

# Project Context

When working with this codebase, prioritize readability over cleverness.

## About This Project

FastAPI REST API for user authentication. Uses SQLAlchemy and Pydantic.

## Key Directories

- `app/models/` - database models
- `app/api/` - route handlers
- `app/core/` - configuration and utilities

## Standards

- Type hints required on all functions
- pytest for testing (fixtures in `tests/conftest.py`)
- PEP 8 with 100 character lines

## Common Commands

```bash
uvicorn app.main:app --reload  # dev server
pytest tests/ -v               # run tests
```

## Notes

All routes use `/api/v1` prefix. JWT tokens expire after 24 hours.

使用 /init 自动生成

运行 /init 命令可以自动分析项目并生成初始 CLAUDE.md：

cd your-project
claude
/init

Claude 会检查 package.json、README、配置文件等，生成一份针对你项目的配置文件。

自动记忆

你不必总是手动更新 CLAUDE.md，Claude Code 具备 自动记忆能力。在日常的交叉任务中，Claude Code 能够自我学习，并将经常用到的构建命令、特殊的调试发现保存下来，并在跨会话中持续起作用，无需你额外操心。

出错即学：把单次纠错变成持久规则

CLAUDE.md 的真正价值是复利。最简单的复利习惯是：每次 Claude 因为不知道某条项目约定而出错时，在 prompt 末尾追加一句：

Update CLAUDE.md so you do not repeat this.

Claude 会自己把这条经验提炼成 CLAUDE.md 里的一行规则。下一次新会话开始，这条规则就已经随项目上下文自动加载了。Boris（Anthropic Claude Code 团队）形容 Claude “出奇地擅长给自己写规则”。

这个习惯比手动维护 CLAUDE.md 更可持续，因为：

触发条件明确：只在 Claude 实际犯错时写，避免预设过多不必要规则
来源真实：每条规则都对应一次真实的错误，而不是想象中可能的问题
复利可见：几周后回看 CLAUDE.md，能直接看到团队踩过的坑被沉淀

判断哪些经验值得写进 CLAUDE.md 的简单筛选问题：“如果删除这一行，Claude 还会不会再犯这个错？” 答案是会，就留下；答案是不会，就删除。CLAUDE.md 不该比一屏内容更长。

上下文喂养：Reference，不要 Describe

给 Claude 喂上下文有两种方式，效果差距很大：

反模式	推荐做法	原因
“看看 auth 模块”	`@src/auth/login.py`	用 `@path` 让 Claude 精确读到文件
把错误日志粘贴进 prompt	`cat error.log \| claude`	管道把完整日志喂给 Claude，不丢上下文
“我们项目用 FastAPI”	把这条事实写进 `CLAUDE.md`	项目级事实只需要写一次

@path/to/file 语法在 CLAUDE.md 和交互式 prompt 中都支持，相对路径按当前文件所在目录解析。Pipe 模式让 Claude 直接消化外部工具输出（构建错误、测试结果、gh pr view 输出），避免你手动复制粘贴时丢失信息。

Hooks：拦截命令体系

为了在流程中更自如地植入代码质量检测，Claude Code 引入了 Hooks 机制：你可以约定让 Shell 命令在 Claude 发生相关行为前/后自动执行。例如修改完任何文件后必须走一遍代码格式化（自动运行 Prettier/Black）；再比如可以在让 Claude 代码修改准备 Commit 提交之前执行全量的 Lint 检测，确保不引入新的问题。

7.2.5 自定义 Slash Commands

将常用的提示词封装为自定义命令，避免重复输入。

注意：自定义命令功能可用性取决于当前 Claude Code 版本。建议参考官方文档了解最新支持。

创建自定义命令

在项目根目录创建 .claude/commands/ 目录并添加 Markdown 文件：

mkdir -p .claude/commands

创建 .claude/commands/security-review.md：

# Security Review

Analyze the provided code for security vulnerabilities:

## Areas to Check
- SQL injection risks
- XSS vulnerabilities
- Authentication/authorization issues
- Sensitive data exposure
- Input validation

## Output Format
For each issue:
1. **Severity**: Critical/High/Medium/Low
2. **Location**: File and line number
3. **Issue**: Description
4. **Fix**: Recommended solution

**Code to review:**
$ARGUMENTS

使用自定义命令

> /security-review src/auth/login.py

$ARGUMENTS 会被替换为命令后的参数。

内部机制提示：内置命令（如 /clear、/compact）由 CLI 本地处理；自定义 commands/skills 是提示词工作流，调用后其内容会渲染并发送给 Claude。理解这一区别有助于排查“为什么模型没有响应我的斜杠命令”类问题。

7.2.6 上下文管理技巧

使用 /clear 重置上下文

长时间对话会累积无关上下文。在切换任务时使用：

> /clear

这会清除对话历史，但保留 CLAUDE.md 配置。

使用 Subagent 隔离上下文

对于需要不同视角的任务（如实现后的安全审查），指示 Claude 使用子代理：

> 使用一个子代理对刚才实现的代码进行安全审查

子代理拥有独立的上下文，不会被前序开发思路影响。

技术细节：通过远程控制（/remote-control）接管的会话有命令限制——能产生文本输出的命令（如 /compact、/clear、/context、/usage、/exit、/recap 等，新版本还包括 /mcp）可在移动端/网页端使用；需要本地交互式选择器的命令（如 /plugin、/resume）仅限本地，触发时返回 “isn't available over Remote Control”。具体清单以官方 remote-control 文档为准。

7.2.7 权限模式

为了安全，Claude Code 把“能否直接修改文件、执行命令、跳过确认”拆成多个权限模式。不要把它简化成 Safe / Auto 二分；不同客户端和账号可见的模式也可能不同。

模式	适用场景	关键边界
`default`	日常开发	需要用户确认写入和多数命令
`acceptEdits`	让 Claude 连续编辑文件	文件编辑和部分工作区内文件系统命令可自动批准，其他命令仍会询问
`plan`	先审方案再动手	适合高风险任务、重构和部署前规划
`auto`	账号和环境满足要求后的自动执行	依赖官方分类器和客户端设置，不应当作简单 allowlist
`dontAsk`	CI 脚本等非交互/自动化场景	不弹窗确认：未经 `/permissions` 或 `permissions.allow` 规则预先批准的操作会被自动拒绝，只读命令仍可执行
`bypassPermissions`	容器、一次性 VM 或强隔离环境	会跳过权限层和大多数安全确认，不应在普通工作机或生产环境使用

CLI 可以用 --permission-mode 指定起始模式。--dangerously-skip-permissions / bypassPermissions 只应在隔离沙箱中使用；在真实项目中，更好的做法是缩小工作区、明确 allowed tools，并保留人工确认门槛。

7.2.8 内部架构揭秘

来源说明：本节内容基于社区对 Claude Code 源代码的逆向分析和工程推断。虽然反映了合理的架构设计方向，但具体技术实现细节、API 参数和隐藏特性描述可能与实际产品有所不同。本节 不应作为官方功能承诺，仅供架构学习之用。关于生产环境中 Claude Code 的确切行为，请以官方文档和实际使用为准。

基于社区对源代码的分析，Claude Code 的内部架构展现了 Anthropic 对 AI 编程助手的深刻理解。

分层模块化架构

Claude Code 采用 5 层架构设计，从高到低分别为：

Entry Layer          → 入口路由（REPL、SDK、HTTP Bridge）
  ↓
Command Layer       → 命令解析、Slash 命令处理
  ↓
Core Engine         → 对话管理、状态机、事件循环
  ↓
Tools & Services    → 文件操作、终端执行、Git、MCP
  ↓
Infrastructure      → 存储、缓存、认证、日志

这种分层设计允许 Claude Code 在不加载无关模块的情况下独立运行各个层级。例如，在 REPL 模式下无需加载完整的 SDK 通信层，在 Bridge 远程模式下也无需启用交互式 UI 组件。

4 种运行时模式

Claude Code 在启动时进入不同代码路径以匹配运行环境：

运行模式	默认入口	场景	核心特征
REPL	`bin/claude`	终端交互	Ink 实时渲染，Readline 输入
SDK (Headless)	`node_modules/claude-code/sdk.js`	程序调用	返回 JSON，无 UI
Print	单次命令执行	`claude "task"`	输出结果即退出
Bridge (CCR)	Websocket 服务器	远程控制	允许 claude.ai 接管会话

每种模式有独立的事件处理、状态管理和输出格式。

状态管理：AppStateStore

Claude Code 维护一个 150+ 字段的应用状态存储。核心字段包括：

type AppStateStore = {
  // 会话状态
  conversation_id: string;
  model: string;
  system_prompt: string;

  // 上下文
  current_directory: string;
  git_status: object;
  recent_files: string[];

  // 授权与配置
  auth_token: string;
  api_key: string;
  user_preferences: object;

  // 运行时
  pending_tool_calls: unknown[];
  tool_results_cache: Map<string, unknown>;
  conversation_history: unknown[];

  // 性能与监控
  token_count: number;
  estimated_cost: number;
  last_cache_hit_time: number;
};

状态管理采用 35 行的发布-订阅实现：

// 简化版 PubSub
class StateStore {
  constructor() {
    this.state = {};
    this.subscribers = new Map();
  }

  subscribe(key, callback) {
    if (!this.subscribers.has(key)) {
      this.subscribers.set(key, []);
    }
    this.subscribers.get(key).push(callback);
  }

  update(key, value) {
    this.state[key] = value;
    this.subscribers.get(key)?.forEach(cb => cb(value));
  }
}

所有状态变更通过 DeepImmutable 包装器进行，确保不可变性和可追溯性。

对话引擎：QueryEngine

整个会话的生命周期由一个 1,295 行的 QueryEngine 类 管理：

主要职责：

消息归一化（处理不同格式输入：自然语言、结构化任务、工具输出）
令牌预算管理（跟踪上下文窗口使用，触发压缩）
对话流控制（回合制管理、暂停、恢复）
缓存整合（自动检测缓存命中，调整成本计算）

核心方法：

class QueryEngine {
  async executeQuery(userInput) {
    // 1. 消息规范化
    normalized = this.normalizeInput(userInput);

    // 2. 上下文预算检查
    if (this.tokenBudget.remaining < 1000) {
      await this.compressHistory();
    }

    // 3. 构建请求
    request = this.buildApiRequest(normalized);

    // 4. API 调用
    response = await this.callAPI(request);

    // 5. 结果处理与工具调用
    while (response.stop_reason === 'tool_use') {
      results = await this.executeTool(response.tool_use);
      response = await this.continueConversation(results);
    }

    return response;
  }
}

系统提示词架构

Claude Code 使用 模块化可缓存的系统提示词片段：

System Prompt = Base + Dynamic Parts + Cache Boundary
                ├─ Base (不变)
                │  ├─ 角色定义 (~500 tokens)
                │  ├─ 工具清单 (~8,000 tokens)
                │  └─ CLAUDE.md 上下文 (~5,000 tokens)
                │
                └─ Dynamic (变化)
                   ├─ 最近命令历史 (~1,000 tokens)
                   └─ 性能指标 (~200 tokens)

关键优化是 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 分割策略：

// 缓存边界标记
const BOUNDARY = "<!-- SYSTEM_PROMPT_DYNAMIC_BOUNDARY -->";

// 第一次请求
system_prompt = BASE_SYSTEM + BOUNDARY + dynamic_part_1;
// → Cache Write: BASE_SYSTEM + BOUNDARY

// 后续请求（仅动态部分变化）
system_prompt = BASE_SYSTEM + BOUNDARY + dynamic_part_2;
// → Cache Hit on BASE_SYSTEM + BOUNDARY, Cache Write on dynamic_part

这种策略减少了每次会话中的缓存写入成本 75%。

功能开关与编译时优化

Claude Code 在构建时包含 70+ 功能开关：

// Bun 的 feature() 函数
if (feature("enable_computer_use")) {
  // 计算机使用模块
}

if (feature("enable_remote_control")) {
  // Bridge 模式代码
}

if (feature("enable_experimental_planning")) {
  // 实验性规划引擎
}

这些开关进行 编译时常量折叠和死代码消除，确保：

生产构建不包含调试代码
某些功能可通过环境变量动态启用
减少二进制大小和运行时开销

UI 层：Ink 与 React

Claude Code 的终端 UI 基于 React + Ink 架构，包含：

50+ 自定义组件（MessageBox、CodeBlock、Spinner、ProgressBar 等）
Yoga 布局引擎（CSS Flexbox 的移植）
87 个 React Hooks（包括自定义 Hook 如 useTokenCount、useStreamingResponse）

关键的 UI 架构：

// 简化的 Claude Code UI 结构
function CLIApp() {
  const [messages, setMessages] = useState([]);
  const [streamingText, setStreamingText] = useState('');
  const [tokenCount, setTokenCount] = useTokenCount();

  return (
    <Box flexDirection="column" padding={1}>
      <ConversationView messages={messages} />
      <StreamingBox>{streamingText}</StreamingBox>
      <CostIndicator tokens={tokenCount} />
      <InputPrompt />
    </Box>
  );
}

隐藏特性

源代码中发现了三项产品文档未公开的实验特性：

特性名	特性门	作用
KAIROS	编译时 `feature('KAIROS')`	持久运行的后台助手，维护每日日志，通过 `<tick>` 提示主动行动，设有 15 秒阻塞预算
BUDDY	编译时 `feature('BUDDY')`	虚拟宠物伴侣系统，含 18 个物种、5 级稀有度、确定性抽卡（同一用户永远得到同一伴侣）
ULTRAPLAN	编译时特性门	将复杂规划卸载到远程 CCR 会话，最多 30 分钟思考时间

这些特性通过 Bun 的编译时特性门控制，在外部构建中被死代码消除，仅内部版本可用。

推测执行引擎

Claude Code 包含一个 推测执行模块，在等待 API 响应时预执行可能的下一步操作：

隔离机制：写入操作（Edit、Write）被重定向到 overlay 文件系统 ${CLAUDE_TEMP_DIR}/speculation/${PID}/${id}，读取操作在 overlay 上隔离进行
安全边界：Bash 命令不允许在推测执行中运行（可能产生不可逆副作用），权限被拒的工具也会终止推测
结果处理：用户确认 → 合并 overlay 到主目录；用户拒绝 → 丢弃 overlay；主响应到达 → 中止推测
ROI 追踪：系统记录每次推测执行的时间节省，用于量化推测执行的投入产出比

核心设计约束是可逆性：文件操作通过 overlay 实现可逆，但 bash 命令（如 git commit）可能产生不可逆副作用，因此是推测执行的硬边界。

CLI 工具非常适合个人开发者在本地终端使用。若想体验 Claude 的进阶特性并在多平台上发挥它更广阔的能力，请延伸阅读本章 7.6 小节。

➡️ Agent SDK 集成等相关内容，或者直接了解 Claude Code 高阶特性与多端生态

FilesExpand file tree

7.2_cli.md

Latest commit

History