1.1 选项全景#

claude --help 输出的选项有将近 50 个，按功能分六组：

下面逐组进行实验与讲解：

1.2 模型与能力类#

--model 指定模型，可以传别名（sonnet、opus、fable）或全名（claude-fable-5）。

模型选择的原则：日常编码用 sonnet（快、便宜），复杂推理或架构设计用 opus（更谨慎、推理链更长），追求最强能力用 fable。对于简单任务（解释概念、格式化代码），模型之间的差异不明显，不必纠结。

--effort 控制思考深度，取值为 low、medium、high、xhigh、max。注意部分模型不支持 max，会静默降级到 high，所以别拿 max 当稳定配置硬靠，效果可能不如你以为的那么强。

工作机制：effort 越高，模型在回答前花越多时间做内部推理（extended thinking）。对于简单问题，高 effort 可能判断”不需要展开”，输出反而更短；对于需要多步推理的问题，高 effort 才会体现为更完整的推导过程。不要用输出长度衡量 effort 的效果，要看推理深度。

实际使用建议：日常对话用 medium（默认），写代码和 debug 用 high，遇到特别棘手的问题再上 xhigh 或 max。

effort 的来源有几层：--effort 参数 > CLAUDE_CODE_EFFORT_LEVEL 环境变量 > 模型默认值。设环境变量是让 effort 按项目或按 shell 会话固定下来的常用做法。至于解析链的内部实现（状态字段、max 的会话级限制、降级规则），属于实现细节，本文不展开，入门阶段记住”五档加一句环境变量可覆盖”就够用。

--fallback-model 设置备用模型，只在 --print 模式下生效。当主模型过载或不可用时自动切换，可以传逗号分隔的列表按顺序尝试：

1
claude -p --model opus --fallback-model sonnet "hello"

主模型 opus 如果响应超时，就自动降级到 sonnet。

1.3 会话与上下文类#

这组选项管理”接着上回聊”的能力。它们的背后是一套会话持久化机制：每次对话都被记录在 ~/.claude/sessions/*.json（元数据）和 ~/.claude/projects/<hash>/<id>.jsonl（完整对话内容）中，恢复会话就是从这些文件加载数据（详见3.6 sessions 与 history）。

--continue（-c）恢复当前目录下最近一次对话。它的做法是扫描 ~/.claude/sessions/*.json 找到 cwd 匹配当前目录且时间最近的会话，然后从 ~/.claude/projects/<path-hash>/<sessionId>.jsonl 加载完整对话历史。

1
# 第一轮：让 Claude Code 记住数字
2
claude -p "记住数字 42"

1
已记住数字 42。

1
# 第二轮：恢复会话并追问
2
claude -p -c "我上次让你记住的数字是什么"

1
根据我的记忆，你上次让我记住的数字是 42。

会话状态被完整保留了。Claude Code 在后台把每次对话存为 session，--continue 会自动找到当前目录最近的那一个。

--resume 比 --continue 更精确，通过 session ID 直接定位 ~/.claude/projects/<path-hash>/<sessionId>.jsonl，也可以打开交互式选择器（数据来自 ~/.claude/history.jsonl 中的 prompt 记录）。--session-id 在启动时指定一个 UUID 作为会话标识，新会话的元数据和对话内容会写入对应的 ~/.claude/sessions/*.json 和 ~/.claude/projects/<path-hash>/<sessionId>.jsonl，适合需要精确追踪会话的自动化场景。--fork-session 配合 --resume 使用，复制源 jsonl 的对话内容到一个新的 session ID 下，相当于”另存为”，原会话不受影响。

1.4 权限与安全类#

这组选项控制 Claude Code 能做什么、不能做什么。权限规则存储在 settings.json 的 permissions.allow / permissions.deny 字段中（详见3.5 settings.json），CLI 选项在启动时与文件中的规则合并生效。

--allowedTools 自动批准列表，列出的工具调用时跳过权限确认，与 settings.json 中的 permissions.allow 合并。注意：它不是白名单，未列出的工具仍然可用，只是走正常权限流程。如果你需要严格限制可用工具，应该用 --tools（见1.6 工作区与环境类）。

--disallowedTools 拒绝列表，列出的工具会从模型的工具上下文中完全移除，模型无法调用它们。拒绝规则优先于所有允许规则，即使 settings.json 中有对应的 permissions.allow 也会被覆盖。比如禁止 Bash 执行：

1
claude -p --disallowedTools "Bash" -- "列出当前目录的文件"

1
当前目录下的文件：
2
README.md  src/  package.json

Bash 被移除后，Claude Code 会改用 Read 工具或 Glob 工具来获取文件列表，而不是执行 ls 命令。这在只读审查场景下很实用。

如果你需要更精细的控制，--disallowedTools 也支持范围规则：Bash(rm *) 只拒绝匹配 rm * 的 Bash 调用，但保留其他 Bash 命令的可用性。

--dangerously-skip-permissions 跳过所有权限检查。名字本身就在警告你：只在沙箱环境里用。还有一个相关选项 --allow-dangerously-skip-permissions，它不会直接跳权限，而是让你在运行时可以切换到跳权限模式，更安全一些。--permission-mode 提供更细粒度的控制，可选值包括 manual（每次询问）、acceptEdits（自动接受文件编辑）、auto（自动判断）、dontAsk（不询问直接执行）、plan（只规划不执行）、bypassPermissions（等同 --dangerously-skip-permissions）。不传该参数时走默认行为，即 manual 的逐次询问。

auto 模式不是简单的”全允许”，而是用一个 LLM 分类器实时判断每次工具调用安不安全，判断不了就默认阻止（fail-closed），安全工具（Read、Grep、Glob 等）则直接放行。分类器的双阶段机制、危险规则的临时剥离、熔断回退，这些属于权限系统的实现细节，本文不展开。入门阶段记住”auto 是让一个分类器替你守门，守不住就回退来问你”即可。

排障时常要分清 --safe-mode 和 --bare，两者都”关掉一部分东西”但范围不同：

--safe-mode 面向”关掉自定义保排障”，--bare 面向”最小依赖启动”。排查行为异常先用 --safe-mode，确认是配置问题后再逐个开回去。

1.5 输出与集成类#

这组选项控制 Claude Code 怎么把结果交给你，在非交互场景下尤其重要。

--print（-p）是最常用的集成选项，让 Claude Code 输出结果后直接退出，不走交互式对话。配合 --output-format json 可以拿到结构化的完整信息：

1
claude -p --output-format json "1+1等于几"

1
{
2
    "type": "result",
3
    "subtype": "success",
4
    "is_error": false,
5
    "api_error_status": null,
6
    "duration_ms": 3550,
7
    "duration_api_ms": 3499,
8
    "ttft_ms": 3545,
9
    "ttft_stream_ms": 3447,
10
    "time_to_request_ms": 54,
11
    "num_turns": 1,
12
    "result": "2",
13
    "stop_reason": "end_turn",
14
    "session_id": "b6128269-06e7-4a7f-8281-ed0a9c66970b",
15
    "total_cost_usd": 0.11613,
16
    "usage": {
17
        "input_tokens": 23216,
18
        "cache_creation_input_tokens": 0,
19
        "cache_read_input_tokens": 0,
20
        "output_tokens": 2,
21
        "server_tool_use": {
22
            "web_search_requests": 0,
23
            "web_fetch_requests": 0
24
        },
25
        "service_tier": "standard",
26
        "cache_creation": {
27
            "ephemeral_1h_input_tokens": 0,
28
            "ephemeral_5m_input_tokens": 0
29
        },
30
        "inference_geo": "",
31
        "iterations": [],
32
        "speed": "standard"
33
    },
34
    "modelUsage": {
35
        "claude-opus-4-8": {
36
            "inputTokens": 23216,
37
            "outputTokens": 2,
38
            "cacheReadInputTokens": 0,
39
            "cacheCreationInputTokens": 0,
40
            "webSearchRequests": 0,
41
            "costUSD": 0.11613,
42
            "contextWindow": 202752,
43
            "maxOutputTokens": 32000
44
        }
45
    },
46
    "permission_denials": [],
47
    "terminal_reason": "completed",
48
    "fast_mode_state": "off",
49
    "uuid": "b0d681a9-ef9a-4b10-b9fb-f836dcac438e"
50
}

JSON 输出里包含了耗时、token 用量、费用、session ID 等元数据，对自动化流程和成本追踪很有价值。

--json-schema 进一步约束输出格式，让 Claude Code 按照 JSON Schema 生成结构化数据：

1
claude -p --output-format json \
2
  --json-schema '{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name","description"]}' \
3
  "介绍一个 Python 内置函数"

输出里大部分元数据字段（usage、modelUsage 等）和上一个示例一致，省略，只看有差异的部分：

1
{
2
    "type": "result",
3
    "subtype": "success",
4
    "duration_ms": 36118,
5
    "num_turns": 3,
6
    "result": "{\"name\":\"lru_cache_intro\",\"description\":\"介绍了 Python 内置装饰器 functools.lru_cache 的基本用法、关键参数（maxsize/typed）、实用场景（昂贵计算/重叠子问题/不可变对象判等）、注意事项（可哈希要求/缓存清理/引用语义/Python 3.9+ 的 @cache 简写）以及自省方法（cache_info/cache_clear）。\"}",
7
    "stop_reason": "tool_use",
8
    "total_cost_usd": 0.25574,
9
    "permission_denials": [],
10
    "structured_output": {
11
        "name": "lru_cache_intro",
12
        "description": "介绍了 Python 内置装饰器 functools.lru_cache 的基本用法、关键参数（maxsize/typed）、实用场景（昂贵计算/重叠子问题/不可变对象判等）、注意事项（可哈希要求/缓存清理/引用语义/Python 3.9+ 的 @cache 简写）以及自省方法（cache_info/cache_clear）。"
13
    },
14
    "terminal_reason": "completed",
15
    "fast_mode_state": "off"
16
}

可以看到，.structured_output 输出严格符合 schema 定义的字段和类型。把 Claude Code 嵌入数据处理管线时，不需要正则提取或后处理，直接拿到结构化结果。

1.6 工作区与环境类#

这组选项控制 Claude Code 的工作范围和运行环境。

--add-dir 允许 Claude Code 访问主工作目录之外的目录。默认情况下，Claude Code 只能操作启动时所在目录（及其子目录）的文件。加上 --add-dir 后，指定的目录也进入它的”视野”，同时会扫描并加载该目录下的 CLAUDE.md（详见3.3 CLAUDE.md）：

1
claude -p --add-dir /tmp/other-project \
2
  "列出两个目录下的所有文件"

--bare 启动极简模式（见 1.4 节说明）。

1
claude -p --bare "你好"

1
你好！有什么我可以帮你的吗？

--worktree 为当前会话创建一个独立的 git worktree，避免在主分支上做实验性修改。--mcp-config 加载 MCP（Model Context Protocol）服务器配置，读取指定 JSON 文件中的 mcpServers 定义，与 .mcp.json 和 settings.json 中的配置合并（详见3.8 MCP 配置）。--tools 直接指定可用工具集，比如 "Bash,Edit,Read" 只保留这三个工具，传 "" 则禁用所有工具。--settings 从额外文件或 JSON 字符串加载配置，成为 settings 层级中优先级最高的 flagSettings（详见3.5 settings.json），覆盖项目级和用户级设置。

1.7 系统提示类#

--system-prompt 完全替换默认系统提示，--append-system-prompt 在默认提示后追加内容。后者更常用，因为你不希望丢掉 Claude Code 的内置行为指令。

1
claude -p --append-system-prompt "所有代码注释用中文" \
2
  "写一个快排函数"

追加的指令会叠加在默认提示之上。--append-system-prompt 适合给 Claude Code 加上项目特有的规则，比如”优先使用函数式风格”或”测试用 pytest 不用 unittest”。它在 prompt runtime 中走的是追加指令总线，涉及多级覆盖优先级，本文只讲操作层面，不展开内部处理。

1.8 CLI 选项的设计哲学#

回头看这六组选项，有一个共同的设计思路：能在启动时声明的，就不要留到运行时。模型选择、权限范围、输出格式、工作目录，这些参数在会话开始前就已经确定了，整个会话期间保持不变。这种”先声明后执行”的模式让 Claude Code 的行为可预期，也方便自动化。

1.9 子命令#

除了选项，claude 还接受子命令，用于执行一次性操作而非启动交互会话：

其中 claude doctor 和 claude mcp 最常用。doctor 是排查环境问题的第一步，mcp 则是管理外部工具接入的核心命令。agents、auth、install、update 是个人日常会用到的；setup-token、ultrareview、gateway、auto-mode 偏企业或云端场景（长期令牌、云端多代理审查、企业网关、分类器配置），个人用户多数用不上，不用挨个试。

2.1 命令全景#

下面逐类说明。

2.2 会话管理#

• /clear：清空当前对话历史，重新开始。不会退出 Claude Code，只是在会话 jsonl 中写入一个清除标记，上下文重置。
• /compact：压缩对话历史以释放上下文窗口。它读取当前 session 的 jsonl 全文，通过一次额外的 API 调用生成摘要，然后将压缩结果追加写入同一 jsonl（详见3.6 sessions 与 history）。原始消息仍在 jsonl 中留档，只是在上下文窗口中被摘要替代。自动压缩在有效上下文窗口的约 93% 处触发。压缩后最近用到的文件和状态会被重新喂回上下文。连续 3 次压缩失败后自动压缩停止（熔断器机制）。
• /resume：在交互模式下恢复之前的会话。扫描 ~/.claude/sessions/*.json 展示当前项目的历史会话列表，同时读取 ~/.claude/history.jsonl 中的 prompt 记录供搜索。和 CLI 的 --resume 功能相同，但入口在运行时。
• /rewind：回退到之前的对话轮次。它从 ~/.claude/file-history/<session-id>/ 目录读取文件编辑前的快照，恢复被修改的文件，同时截断 jsonl 中的对话记录到回退点（快照机制详见3.9 其他数据文件）。

2.3 上下文操作#

• /context：查看当前会话的上下文状态，展示已加载的 CLAUDE.md 文件、memory 文件、settings 配置等（分别对应3.3 CLAUDE.md、3.4 memory、3.5 settings.json）。帮你搞清楚”Claude Code 现在到底知道些什么”。
• /add-dir：运行时添加额外的工作目录，同时扫描并加载该目录下的 CLAUDE.md。和 CLI 的 --add-dir 功能相同，区别是不需要退出重启。

2.4 权限调整#

• /permissions：查看和修改当前会话的权限设置。读取 settings.json 三层级的权限配置，修改时写回对应层级的 settings 文件（详见3.5 settings.json）。你可以在运行时开放或收紧工具权限，比如临时允许 Bash 执行，做完再关掉。

2.5 模型切换#

• /model：在对话中切换模型。不用退出重启，直接从 sonnet 切到 opus 或反过来。对”先用快速模型探索，再用强模型精修”的工作流很方便。

2.6 调试与诊断#

• /doctor：检查 Claude Code 的健康状态。读取 settings.json、.mcp.json、installed_plugins.json 等配置文件（分别对应3.5、3.8、3.9），验证 MCP 服务器连接、认证状态、自动更新器是否正常。排查环境问题的第一步。
• /cost：显示当前会话的累计花费。从当前 session 的 jsonl 中累计 token 用量并换算为费用（详见3.6）。长对话随时看一眼成本是个好习惯。
• /debug：切换调试模式，查看 API 请求、工具调用等内部细节。

2.7 工作流#

• /init：在当前项目目录初始化 CLAUDE.md。它分析项目结构后生成一份包含项目规则、关键路径、编码风格的 CLAUDE.md，写入项目根目录（详见3.3 CLAUDE.md）。如果 CLAUDE.md 已存在，会建议改进。新项目接入 Claude Code 时建议先跑一次。
• /review：让 Claude Code 审查当前的代码变更（git diff），给出修改建议。

2.8 CLI 选项与 / 命令的对照#

有些能力在 CLI 和 / 命令两边都有入口，有些只有单边：

表里有个规律：压缩、清空、回退这三个只有运行时入口，没有 CLI 选项。原因很直接，它们操作的是”对话进行中产生的状态”，而启动时还没有对话可压缩、可清空、可回退。反过来，输出格式和系统提示只在启动时确定，因为它们是送进模型的固定框架，运行中改意义不大。这条分界线，正好对应下一节要讲的”可控性”。

2.9 / 命令的设计哲学#

/ 命令解决的核心问题是 Agent 的可控性。如果所有参数都只能在启动时设定，一旦对话方向偏离，你只能退出重来。有了 / 命令，你可以在运行中调整模型、压缩上下文、回退轮次，这些能力让 Agent 从”启动即锁定”变成”运行时可调”。

3.1 命令与文件的映射#

很多命令的行为直接由文件驱动。下面这张表把最常用的”我敲了这个命令，它读写什么文件”的对应关系梳理出来：

有了这张表做参照，下面逐项展开文件布局的细节时，你能随时对照”这个文件被哪个命令读写”。

3.2 文件布局全景#

Claude Code 的文件分布在两个层级：用户级（~/.claude/）和项目级（项目根目录下的 .claude/ 和 CLAUDE.md）。

注：实际还有目录级，主要用于 monorepo 的场景，但子目录级别只对 CLAUDE.md 和 .claude/rules/*.md 有效；

下面逐项说明关键文件的作用和内容。

3.3 CLAUDE.md：项目级的行为指令#

CLAUDE.md 是 Claude Code 最核心的配置文件。每次启动时，Claude Code 会自动在项目根目录查找并加载它，把内容注入系统提示。它相当于给 Claude Code 写了一份”项目说明书”。

一个典型的 CLAUDE.md 包含：

1
# Claude Code 项目配置
2

3
## 项目概述
4
项目是什么、用什么技术栈、部署在哪里。
5

6
## 关键路径
7
文章目录、草稿目录、配置文件位置。
8

9
## 写作规范
10
遵循哪些 skill，优先级如何。
11

12
## 工作流约定
13
修改前检查格式、不编造事实、草稿先放 _draft 目录。

你可以用 /init 命令让 Claude Code 交互式引导你创建 CLAUDE.md，也可以手动编写。CLAUDE.md 的加载路径不限于项目根目录：Claude Code 还会扫描 .claude/rules/*.md、用户级 ~/.claude/CLAUDE.md、以及 --add-dir 添加目录下的 CLAUDE.md（见1.6 工作区与环境类），从外到内逐层叠加。--safe-mode 和 --bare（见1.4 权限与安全类）会跳过 CLAUDE.md 的自动发现。

CLAUDE.md 的加载遵循四级信任模型（Managed > User > Project > Local），后加载的文件覆盖先加载的。Project 和 Local 文件按目录从根到 CWD 遍历，越靠近 CWD 的文件优先级越高。CLAUDE.md 还支持 @./relative/path 语法引用外部文件（深度上限 5），.claude/rules/*.md 中的规则文件可以用 frontmatter 的 paths: 字段声明条件加载。这些加载规则的内部实现（section 化拼装、缓存边界、动态注入）本文不展开。

3.4 memory：跨会话的持久记忆#

memory 目录在 ~/.claude/projects/<项目路径哈希>/memory/ 下。每个记忆是一个独立的 markdown 文件，带 frontmatter（包含 name、description、metadata 等字段）。MEMORY.md 是索引文件，每行一条记忆的标题和摘要。Claude Code 每次启动时加载 MEMORY.md，根据描述判断哪些记忆与当前任务相关，再按需读取具体文件。memory 的注入机制和更新协议（session memory prompt、memory extraction prompt）本文不展开。

memory 和 CLAUDE.md 的区别：CLAUDE.md 是你主动写的项目规则（用 /init 创建，见2.7 工作流），memory 是 Claude Code 在对话中自己沉淀的跨会话经验。一个管”你应该怎么干活”，一个管”上次干活学到了什么”。--safe-mode 和 --bare（见1.4 权限与安全类）会跳过 memory 的自动加载。

3.5 settings.json：权限与配置#

settings.json 有三个层级，优先级从低到高：

1. 用户级：~/.claude/settings.json，全局生效
2. 项目级：<project>/.claude/settings.json，进 git，团队共享
3. 本地级：<project>/.claude/settings.local.json，不进 git，个人覆盖

一个典型的项目级 settings.json：

1
{
2
  "permissions": {
3
    "allow": [
4
      "Bash(*)",
5
      "Read",
6
      "Write",
7
      "Edit"
8
    ]
9
  }
10
}

这里声明了允许的工具权限。settings.local.json 的格式相同，但适合放个人偏好（比如本地开发环境特有的权限），不会污染 git 仓库。

用户级 settings.json 则承载全局配置：环境变量（API key、base URL）、插件启用、主题选择等。三个层级的配置在启动时合并，高优先级覆盖低优先级。--settings 指定的配置成为 flagSettings 层，优先级最高（见1.6 工作区与环境类）。--setting-sources 可以控制只加载其中某些层级。/permissions 命令（见2.4 权限调整）在运行时修改权限后，会写回对应层级的 settings 文件。

3.6 sessions 与 history：对话数据#

~/.claude/sessions/*.json 存储会话元数据，每个文件以进程 PID 命名，记录 sessionId（UUID）、cwd（工作目录）、status（idle/busy/completed）、startedAt、version 等字段。--continue 就是扫描这些文件找当前目录最近的会话，--resume 按 sessionId 直接定位。

~/.claude/projects/<path-hash>/<session-id>.jsonl 存储会话的完整对话内容，采用 append-only 事件日志格式。每一行是一个 JSON 对象，消息类型包括 mode、system、user、assistant、attachment、file-history-snapshot、ai-title、last-prompt 等。这是 Claude Code 的”对话档案”，也是 --continue/--resume 恢复对话的数据来源，/compact 写入压缩摘要的目标，/rewind 截断对话的起点。子代理（Agent）的对话记录在 ~/.claude/projects/<path-hash>/<session-id>/subagents/agent-<id>.jsonl，元信息在对应的 .meta.json 中。大工具输出持久化在 ~/.claude/projects/<path-hash>/<session-id>/tool-results/ 下。

~/.claude/history.jsonl 是更轻量的记录，每行只存用户输入的 display text、时间戳、session ID 和 project 路径，不包含模型回复。这个文件用于 /resume 的交互式选择器，让你搜索历史对话。

3.7 skills：行为扩展#

skills 以目录形式存储，每个 skill 目录包含一个或多个 markdown 文件，定义了特定场景下的行为规范。

skills 的加载来源按优先级排列：

1. Bundled skills：内置在 Claude Code 二进制中（--disable-slash-commands 可禁用）
2. 用户级：~/.claude/skills/，全局生效
3. 项目级：<project>/.claude/skills/，只在该项目生效
4. 插件级：~/.claude/plugins/cache/<marketplace>/<plugin>/skills/
5. 自定义命令：<project>/.claude/commands/ 中的文件自动成为 / 命令

当你在对话中触发一个 skill（比如 /sync-api），Claude Code 从 skills 目录加载对应的 markdown 内容，注入当前对话的上下文。

3.8 MCP 配置：外部工具接入#

MCP（Model Context Protocol）服务器的配置分布在多个文件中：

claude mcp list 列出所有来源的 MCP 服务器。项目级 .mcp.json 中的服务器首次加载时会弹出安全确认，批准后才能连接。--strict-mcp-config 只允许 --mcp-config 指定的服务器，忽略其他来源。

3.9 其他数据文件#

这些文件一般不需要手动编辑，但了解它们的存在有助于排查问题。比如 /rewind 能回退文件修改，靠的就是 ~/.claude/file-history/ 中的快照；用 /plugin install 装插件时，会同时写入 ~/.claude/plugins/installed_plugins.json、~/.claude/plugins/cache/ 和 settings.json 的 enabledPlugins 字段（详见第五节插件生态）。

3.10 文件系统的设计哲学#

Claude Code 的文件布局体现了一个设计思路：文件系统即记忆。CLAUDE.md 是项目级的”工作手册”，memory 是跨会话的”经验笔记”，sessions jsonl 是”对话档案”，settings.json 是”权限清单”。这些文件让 Claude Code 从一个”每次启动都从零开始的聊天机器人”变成了”有项目上下文、有历史经验、有行为约束的 Agent”。文件系统不是 Claude Code 的附带产物，而是它”记住事情”的根基。