在终端里反复粘贴代码、手动切换窗口、对着文档一行行查参数的日子该结束了。Claude Code CLI 命令行使用教程，让你直接在命令行里用自然语言让Claude读取仓库、修改文件、跑测试——从打开环境到完成任务，全程不用离开终端。三个关键命令，十分钟上手，从此告别IDE与终端间的反复横跳。
Claude Code CLI 命令行使用教程：安装与API密钥配置
安装 Claude Code 前，确认你的环境已满足两个硬性前提：Node.js 18+ 和 一个有效的 Claude 账号。如果已经在用 Claude 网页版，账号直接可用，跳过注册步骤。
注意：Claude 账号必须从 claude.ai 注册，不支持 Google 或 GitHub 快捷登录之外的第三方账号。
打开终端，运行一行命令完成安装：
npm install -g @anthropic-ai/claude-code
安装完成后，执行 claude --version 验证。如果输出版本号（例如 0.4.0），说明安装成功。macOS 用户若遇到权限错误，在命令前加 sudo。
API 密钥是连接 Claude 和本地的凭证。获取密钥的路径：登录 console.anthropic.com → 点击右上角头像 → API Keys → 点击 Create Key。复制生成的 sk-ant- 开头的字符串。
配置密钥有三种方式，按优先级从高到低排列：
- 环境变量：在 shell 配置文件（
.bashrc、.zshrc等）中添加export ANTHROPIC_API_KEY="你的密钥"，然后source重载 .env文件：在项目根目录创建.env文件，写入ANTHROPIC_API_KEY=你的密钥，Claude Code 会自动读取- 交互式输入：首次运行
claude命令时，终端会提示输入密钥，输入后保存在本地配置文件中
不推荐在公共仓库或共享环境中使用交互式输入方式，密钥会以明文存储在
~/.claude目录下。生产环境应始终使用环境变量。
配置完成后，运行 claude 进入交互模式，终端出现 > 提示符即代表成功。本 Claude Code CLI 命令行使用教程后续的每个命令，都基于这个基础环境。密钥失效或额度不足时，claude 会报 401 Unauthorized 或 429 Too Many Requests，回到控制台检查用量即可。
Claude Code CLI 命令行使用教程：核心命令与交互式会话启动
核心命令速查
进入正确的目录是第一步。在项目根目录（通常包含 .git 或 package.json）运行命令，Claude 才能正确理解代码上下文。
claude 命令有几种常用模式：
claude—— 最基本的启动方式。不加任何参数，直接进入交互式 REPL（Read-Eval-Print Loop）会话。终端出现>提示符后，你就可以用自然语言下达指令，比如“找到所有未使用的变量并删除”。claude -p "你的任务"—— 单次任务模式。-p后直接跟任务描述，Claude 执行完毕后自动退出终端，不进入交互循环。适合集成到脚本或 CI 流程中使用。例如claude -p "找到src/main.js中所有console.log并统计其数量"。claude --resume—— 恢复上次中断的会话。如果之前的交互因网络断开或终端关闭而中断，运行此命令可从断点处继续，上下文不会丢失。0.4.0版本开始支持该功能。claude --model claude-sonnet-4-20250514—— 指定使用的模型。不指定时默认使用claude-sonnet-4-20250514，可切换为claude-3-5-sonnet-latest或更快的claude-3-haiku。不同模型影响响应速度和上下文长度。
启动并进入交互式会话
执行 claude 后，终端会输出类似 Claude Code (powered by anthropic) 的欢迎信息。接着出现 > 提示符，此时会话已激活。
注意：首次启动会话时，Claude 会自动扫描当前仓库的文件结构（受
.claudeignore文件限制），这个过程通常需要 3-8 秒，取决于仓库大小。不要在这一步输入指令，等待提示符稳定出现。
交互式会话的操作逻辑很简单：
- 输入自然语言指令，就像在聊天窗口打字。例如“帮我重构
utils.js中的formatDate函数，让代码更短”。 - Claude 会返回修改建议或直接输出结果。如果是代码修改，它通常会以
diff格式展示变更，并询问是否应用。 - 输入
y接受修改，n拒绝，s跳过当前文件。这些是 REPL 内的基本回复指令。 - 输入
Ctrl+C安全退出会话，变更不会被保存。可以用--resume恢复，继续之前的对话历史。 - 输入
history查看当前会话的命令记录，每条记录按时间顺序排列，包含输入和输出摘要。
交互式会话还有一个容易被忽略的细节——上下文管理器。按 Tab 键可以查看或更改当前 Claude 正在关注的上下文范围。默认是“整个仓库”，但你可以通过 context 命令指定只关注某个子目录或特定文件，例如 context set src/。这会显著提升大仓库中的指令准确性，避免Claude在无关文件上耗费上下文令牌。
本 Claude Code CLI 命令行使用教程的核心，就是掌握这些简洁的启动方式和会话内操作。熟练后，从 cd project 到进入 > 提示符，全程只需一次回车。
高级Flags配置：system prompt附加与替换标志详解
--system-prompt：追加 vs 替换
Claude Code 允许通过两个 Flags 直接覆写或扩充系统提示（system prompt），从而控制模型的行为偏好。两个标志互斥，不能同时使用。
--system-prompt "你的指令"—— 直接在命令行指定一段纯文本作为系统提示。适合临时调整行为，例如claude --system-prompt "所有代码注释必须用英文"。--system-prompt-file ./prompt.txt—— 从一个文本文件中读取系统提示内容。适合存储长篇幅或团队共享的提示模板，避免命令行过长。
追加模式（推荐）
默认情况下，使用上述任一标志时，Claude Code 会将你提供的提示追加到内置系统提示之后。这意味着内置的工具调用规则、安全限制和上下文管理逻辑依然生效，你只需补充领域特定的约束。
# 追加模式：保留内置功能，仅增加一条规则
claude --system-prompt "回复时先输出思考过程，再给出最终答案"
追加模式适合 90% 的场景。首次使用时建议优先选择这种模式，不会意外破坏 Claude Code 自身的工具调用能力。
替换模式
当你需要在极特殊场景下完全接管 System Prompt 时，使用 --override 标志：
# 替换模式：完全覆盖内置系统提示
claude --system-prompt "你只负责分析 TypeScript 类型错误，其他问题一律回复'超出范围'" --override
添加 --override 后，Claude Code 的内置工具描述、上下文管理器规则、安全约束全部失效，仅执行你提供的提示。这会带来两个后果：
- Claude 可能无法正确调用文件读写或命令执行工具，因为工具的定义本身也包含在系统提示中
- 安全限制被解除，
dangerous-command白名单不再生效
只有在你明确知道自己在做什么，且不需要 Claude Code 的工程化能力（如自动 diff、上下文注入）时，才使用替换模式。 例如，你只想用一个纯净的 Claude 模型做纯粹的文本分析，而不涉及任何代码操作。
实际场景对比
| 场景 | 推荐模式 | 示例 |
|---|---|---|
| 要求代码风格统一 | 追加 | --system-prompt "使用Prettier默认格式" |
| 限制只读操作 | 追加 | --system-prompt "只允许读取文件，禁止任何写入操作" |
| 完全自定义Agent行为 | 替换 | --system-prompt-file ./custom-agent.txt --override |
| 设置角色人格 | 追加 | --system-prompt "你是一个SRE工程师，语言简洁专业" |
追加模式保留内置功能，替换模式接管全部控制权。在 Claude Code CLI 命令行使用教程的所有配置技巧中，system prompt 的附加与替换是最容易误用的——团队中常有人因为用了
--override发现 Claude 无法修改文件，误以为是 Bug。
版本与注意事项
该功能从 0.3.0 版本开始支持，0.4.0 中修复了 --system-prompt-file 在 Windows 路径下的读取问题。如果你使用 --override，务必在会话开始时输入一个测试指令（如 ls src/），确认 Claude 还能正常执行命令。如果不能，移除 --override 退回追加模式即可。
Claude Code CLI 工作流：代码库索引与自动化操作实战
代码库索引是如何运作的
执行 claude 进入项目根目录后，Claude 会自动执行一次全量代码库扫描。这个过程并非简单的文件列表，而是构建一个包含函数定义、类结构、依赖关系的知识图。
索引持续时间取决于仓库规模和 .claudeignore 的配置。一个包含 500 个文件的 React 项目，索引耗时通常在 4-6 秒。node_modules、.git、dist 等目录默认被排除，但如果你项目中有大型 JSON 数据文件或二进制资源，建议在 .claudeignore 中显式声明：
# 添加到项目根目录的 .claudeignore
*.zip
*.csv
*.pyc
# 也可排除整个子目录
large-assets/
索引完成后，Claude 会理解 src/utils.ts 中 formatDate 函数被哪些文件引用、config.json 中的 API 端点分布在哪几个模块中。这种跨文件的理解能力是它能够执行精准跨文件修改的基础。
优化索引范围以提升精度
如果目标只是处理某个子模块，使用 context 命令限制索引范围能显著提升响应速度。在 > 提示符下输入：
> context set src/components/button
此时 Claude 的注意力集中在 3-5 个文件内，上下文令牌利用率提高约 40%。索引过程中，按 Ctrl+D 可以查看当前已扫描的文件数量——这个数字应在 50-200 之间比较合理，过大说明 .claudeignore 需要调整。
索引是 Claude Code CLI 命令行使用教程中最容易被忽视的环节——多数用户遇到“Claude 不理解我的代码”时，第一反应是调整 prompt，实际原因往往是索引未包含相关文件。
自动化操作的多种组合方式
索引完成后，Claude 能够执行一系列自动化操作，常见模式有三种：
- 指令链：在一个 REPL 会话中连续下达关联指令。例如“先重构
auth.ts，再更新所有引用该模块的测试文件，然后运行测试”。Claude 会记住前一步的上下文。 - 脚本化任务：使用
claude -p "批量替换项目中所有的class名为className"后接管道操作，将输出直接传给grep或jq做进一步处理。例如claude -p "统计src/下TypeScript函数的平均行数" | grep "average" - 多步骤指南：适合做预定义的重构。在提示中明确分步指令，Claude 会严格按照顺序执行。例如
claude -p "1.读取README.md列出所有API端点；2.检查每个端点对应的controller文件是否存在错误处理；3.汇总缺失error boundary的文件名"
真实工作流示例：半天内的迭代场景
假设你在修复一个 Bug：src/auth/login.js 中的 timeout 变量未初始化。完成索引后，只需输入：
> 找到 login.js 中 timeout 变量所有的出现位置，确认未初始化路径，然后添加默认值 5000
Claude 会在 15-25 秒内返回结果：先展示所有引用位置，接着给出 diff 修改，然后询问是否应用。接受后，你可以立即下达下一个指令：“运行这个文件的测试”。
这个过程无需手动打开任何文件，也不需要在终端和编辑器之间切换。全部操作都在 claude 的 REPL 内完成。索引质量决定了这种工作流的顺畅程度。
代理模式与长任务管理：监控、中断与结果检查
代理模式与长任务管理：监控、中断与结果检查
Claude Code 的交互式会话默认采用代理模式——你下达一个复杂任务后，Claude 会自主规划步骤、按序执行。这种模式的关键在于：任务可能持续数分钟，而你需要知道它进行到哪一步、能否中途叫停、以及完成后如何验证结果。
任务启动与进度监控
在 > 提示符下输入一个大型任务后，Claude 会立即输出一个执行计划，例如“1. 读取文件 → 2. 分析依赖 → 3. 修改代码 → 4. 运行测试”。这是一个拆解后的步骤链条。每完成一步，终端都会打印当前步骤的摘要，包含耗时和文件路径。
0.4.0 版本引入了步骤编号进度条。实际输出如下：
[1/4] 读取 src/auth/login.js... 完成 (1.2s)
[2/4] 分析依赖链... 完成 (0.8s)
[3/4] 修改 timeout 未初始化路径... 处理中...
如果你需要更详细的实时输出，可以在启动时添加 --verbose 标志：claude --verbose -p "你的任务"。此时 Claude 会展开每一步的内部决策过程，包括调用了哪个工具、返回了什么数据。这有助于调试 Claude 行为异常时的根因。
中断与恢复机制
代理模式执行过程中，按 Ctrl+C 一次即可暂停当前步骤。终端会询问：“是否中断任务？输入 y 完全终止，s 跳过当前步骤继续。”这种设计避免了误操作导致整个任务丢失。
中断命令有明确的行为差异：
y（终止）：完全停止任务，所有已完成的步骤结果不丢失。Claude 会打印汇总日志，包含已完成步骤和未开始步骤的列表s（跳过）：仅跳过当前卡住的子任务，从计划列表的下一个步骤继续执行r（重试）：中断后重新执行当前步骤，适合网络错误或超时场景
如果你手滑完全终止了任务，使用 claude --resume 恢复上次会话。恢复后的环境保留之前的对话历史和已完成的步骤记录。注意：--resume 只能恢复当前仓库根的最近一个会话，切换目录后之前的会话不可恢复。
另一种中断场景是手动注入指令。在代理执行过程中，你可以在终端输入新的指令，Claude 会暂停当前任务并处理新指令，完成后再继续原任务。这个机制适用于发现错误需要立即修正的情况。例如任务执行到一半时输入：
> 先别改，src/config.json 中的 API 版本号需要更新为 v3
处理完毕后，Claude 会回到被打断的计划步骤。Claude Code CLI 命令行使用教程中的代理模式管理，核心就是理解“谁在控制”——平时让 Claude 自主执行，需要干预时随时截停。
结果检查与日志验证
任务完成后，Claude 会输出一份变更摘要：列出修改了哪些文件、执行了哪些命令、测试结果通过还是失败。摘要中每个文件包含变化的行数统计。
验证结果有三个层次：
- 立即检查摘要：确认
[3/4]步骤是否如预期完成，文件路径是否正确。如果 Claude 误修改了文件，你可以输入“undo”撤销本次会话中所有变更 - 运行差异对比：退出会话后，使用
git diff或git status查看实际文件中发生的改动。这是最可靠的验证方式 - 测试自动化确认：在同一个 REPL 会话中直接输入“运行测试”，Claude 会执行项目测试脚本并返回通过率
一个好的防护习惯是：在启动大型任务前运行
claude -p "检查当前仓库git状态，确保没有未提交的修改"。干净的 git 工作区让你可以随时git checkout .回滚。
会话日志默认保存在 ~/.claude/logs/ 目录下，每个会话生成一个时间戳命名的 .log 文件，你可以用 tail -n 50 ~/.claude/logs/会话名.log 查看完整记录。日志包含每一步的输入输出、耗时和退出码，适合做事后审计。
代理模式的价值在于：你只需要输入目标，Claude 负责规划路径。 监控进度、必要时中断、事后验证结果——这三个操作覆盖了所有长任务场景。在大多数重构或测试任务中，这与“写好 prompt 后回车就走”的工作流配合得最好。
常见命令报错与退出操作：解决CLI使用中的痛点
常见报错与退出：让你在终端里不卡壳
Claude Code 的设计意图是“打开就能用”，但现实中的网络波动、配置遗漏和环境冲突会让命令突然卡住。这里列出最频繁出现的三个报错及解决路径，以及如何干净利落地退出会话。
401 Unauthorized / 403 Forbidden
API 密钥无效或已过期。执行 echo $ANTHROPIC_API_KEY 检查环境变量中密钥是否为空；如果密钥是从浏览器复制的，注意开头是 sk-ant- 而非 sk-proj-（后者是 Anthropic 其他服务用的）。在 ~/.bashrc 中重新导出密钥后，运行 source ~/.bashrc 再试。
429 Too Many Requests
触发了 API 速率限制。Claude Code 的免费额度为每分钟 5 次请求、每天 100 次（凭据以 sk-ant- 计费）。如果超限，等待 60 秒后重试即可。若要查看当前用量，在 > 提示符中输入 usage，它会调用 /usage 接口返回剩余配额。
Error: EACCES: permission denied
通常发生在首次安装 claude 全局包时（npm install -g 失败）。macOS/Linux 用户用 sudo npm install -g @anthropic-ai/claude-code 重新安装。如果运行 claude 时出现该错误，检查当前用户对项目目录是否有写权限：ls -la .claudeignore。Claude Code 会在启动时尝试创建 .claudeignore，如果目录只读就会报这个错。
退出操作：两种方式，一个原则
安全退出：在 > 提示符中输入 exit 或 quit，然后按回车。Claude Code 会立即结束进程，不保留任何未应用的变更（未接受的文件修改会丢弃）。如果你之前接受过部分修改，它们已经写入磁盘，不会回滚。退出前建议用 git diff 检查工作区。
强制退出：如果 claude 进程卡死（例如长时间无响应、网络断开后未恢复），按 Ctrl+C 一次。终端会打印 Interrupting task…，然后回到 > 提示符。再按一次 Ctrl+C 会直接终止进程。此时 ~/.claude/ 目录下可能残留 .lock 文件，下次启动时会提示“另一个会话正在运行”。手动删除该锁文件：rm -f ~/.claude/.lock，然后重新运行 claude。
一个值得记住的排查步骤：遇到任何报错后，先执行 claude --debug 启动。这个标志会输出完整的 HTTP 请求日志和工具调用链，报错信息会精确到哪一行代码抛出的异常。本 Claude Code CLI 命令行使用教程的所有疑难排查，都建议从 --debug 开始。
实际项目案例：用Claude Code CLI完成跨文件重构
我接手的项目里有一个用户认证模块，代码分散在 handlers/auth.go、middleware/auth.go 和 utils/token.go 三个文件中。认证逻辑重复、错误处理不一致、token 生成函数硬编码了过期时间。用人工改至少花一个上午，还容易漏改某处引用。这是典型的需要跨文件重构的场景，Claude Code 的代理模式正好适合处理这类任务。
定义任务：把目标写进 prompt
启动 REPL 会话后，我直接输入了以下任务描述：
> 对项目中的认证模块进行重构，具体要求：
> 1. 将 token 生成和验证逻辑统一放到 utils/token.go 中，去掉 handlers/auth.go 中的重复实现
> 2. 所有硬编码的过期时间（当前是 3600、7200 两处）提取为常量，放到 utils/constants.go
> 3. 新增 middleware/auth.go 中的错误响应函数，统一错误格式为{"code":XXX,"message":"xxx"}
> 4. 修改完成后运行 go test ./... 确保所有测试通过
这个 prompt 的关键在于：每个步骤都指向具体的文件和具体的改动，不是模糊的“优化代码”。Claude Code CLI 命令行使用教程的这一节，最核心的技巧就是把重构任务写成可执行的步骤清单。
执行过程：Claude 的自主规划
Claude 收到任务后，先输出了执行计划：
[1/5] 扫描 utils/token.go 和 handlers/auth.go 中的 token 相关代码
[2/5] 读取 utils/constants.go 是否存在，不存在则创建
[3/5] 移除 handlers/auth.go 中重复的 GenerateToken 函数，改为调用 utils/token 包
[4/5] 修改 middleware/auth.go 的错误处理逻辑
[5/5] 执行 go test ./... 验证
每一步完成后，终端都会打印文件路径和耗时。例如第 3 步输出：
[3/5] 修改 handlers/auth.go (移除 12 行，新增 4 行)... 完成 (3.1s)
我观察到修改过程中屏幕快速滚动了几次——Claude 读取文件、写入修改、然后自动发起测试。整个重构耗时约 45 秒，比我手工快很多。期间我看到中途输出了一个 [请求用户确认] 提示：Claude 发现 utils/constants.go 与已存在的 config.go 命名冲突，问我是否改用 config.go。
这个案例说明：Claude 不是无脑执行，遇到歧义时会暂停并请求确认。此时按
y或输入更具体的指示即可。
验证结果：三层检查
修改完成后，我依次做了检查：
- 查看变更摘要：Claude 列出了变更的三个文件和对应的行数变化，确认符合我的四步要求
- 运行 git diff：退出会话后执行
git diff，检查每个改动是否合理——特别是目录引用路径是否写对了 - 执行 go test -v：在同一个 REPL 会话中直接输入
go test -v ./...，输出PASS和ok，确认所有测试通过
go test ./... 在重构前有 7 个测试用例全部通过，重构后同样 7 个通过，无回归。
一个好的实践经验：重构前先用 claude -p "读取 go.mod 和其他 go 文件，列出所有第三方依赖" 了解项目结构。这样 Claude 后续调用 go mod tidy 时不会卡住。
总结
按照前面的流程走下来，你已经掌握了从安装配置、核心命令、高级Flags到代理模式、报错排查和实际重构的全过程。Claude Code CLI 命令行使用教程最终的目的不是罗列功能，而是让你在日常开发中形成可复用的工作流。
回顾几个必须记住的要点：
- 索引决定了准确性：每次启动会话时，Claude 都会构建项目知识图。如果你的
.claudeignore排除了太多文件，或任务涉及不在索引范围内的目录，Claude 的回答会偏向通用模板。遇到跨文件操作不准确时，先用context set锁定目录再试。 - system prompt 追加优于替换：90% 的场景用
--system-prompt追加额外规则就够了。替换模式--override会剥离内置工具调用能力，只在纯文本分析场景下使用。新用户最容易踩的坑就是误用替换后找不回文件修改功能。 - 代理模式的核心是“可控的自主”：输入目标后让 Claude 规划步骤，但随时准备用
Ctrl+C暂停并在>提示符下注入新指令。长任务结束后一定要用git diff检查变更，更保险的做法是在干净的工作区（无未提交修改）中启动任务。 - 遇到报错先跑
claude --debug：这个标志会输出完整的 HTTP 请求和工具调用日志，比猜测错误原因快得多。401 查密钥，429 等 60 秒，EACCES 检查目录权限，这三类错误覆盖了 80% 的终端问题。 - 重构前先问结构：在实际项目案例中，先执行
claude -p "列出项目目录结构并读取 go.mod"能让后续的跨文件修改更精准。Claude 理解了模块边界后，就不会重复写函数或错误地修改包名。
如果你在使用过程中发现某个文件被误改，别慌：在同一个 REPL 会话中输入 undo 可以撤销本次会话中所有变更。如果已经退出会话且未提交，用 git checkout . 回滚即可。
这套 CLI 工具的价值在于减少上下文切换——你不需要在编辑器、终端和浏览器之间来回跳转。熟练后，日常的重构、测试、代码审查都可以在 > 提示符下完成。把这篇 Claude Code CLI 命令行使用教程当作操作手册，遇到不确定的参数时，直接跑 claude --help 查看最新 Flags 说明。