把 AI 编程助手从网页聊天框搬进终端，这件事比听起来更重要。Claude Code 是一套完全跑在命令行里的 AI 编程工具，你输入一句自然语言，它能读文件、改代码、执行测试、查日志，整套动作都在终端上下文里完成。对我来说，它最大的价值不是“聊代码”，而是可以像一条普通命令那样被反复调用：一次性执行、管道输入、接进脚本、跑在 CI 里。这篇内容就是按我实际使用 Claude Code CLI 的路径，把从安装到自动化的常用命令、参数、斜杠命令和避坑点完整梳理一遍。不管你是刚接触终端的新手，还是整天在 shell 里打滚的老手，都能从这里找到能直接抄的用法。
1. 安装与初始化：先拿到一个能用的 claude 命令
1.1 两种安装方式怎么选
Claude Code 的安装路径其实不多，我用下来最常见的是 npm 全局安装。如果你本机已经有 Node.js 环境，一条命令就能搞定：
npm install -g @anthropic-ai/claude-code装完先验证版本，确认命令真的可用：
claude --version我见过不少人装完直接敲claude却发现命令找不到，十有八九是 npm 全局目录没被加进 PATH。这时候先跑npm config get prefix看全局安装目录，再检查系统 PATH 是否包含它。Windows 上还要注意 PowerShell 的脚本执行策略，必要时把执行策略调整成允许签名脚本。
另外官方也提供原生安装脚本，适合不想装 Node.js 或者想体验自动更新的场景。两种方式选哪个没有绝对答案：npm 装的好处是和依赖管理统一，脚本装的优点是不依赖 Node 版本。我的建议是主力开发机上用 npm，如果是临时环境、容器镜像里用脚本装更快。装好后直接跑claude，会进入首次登录流程。
提示：无论哪种安装方式，装完后第一件事是
claude --version。版本号能帮你确认后面所有命令的参数是否准确，不同版本之间的默认行为和参数写法有过差异。
1.2 登录鉴权与凭证保存的位置
首次运行claude会弹出一个登录引导，完成授权后，凭证会保存到本机用户目录下的.claude配置目录里。也就是说，你只需要登录一次，之后所有项目、所有终端窗口都能复用。
如果你不想走交互式登录，也可以直接在环境变量里设置 API 密钥：
export ANTHROPIC_API_KEY=你的密钥这个方式特别适合 CI、容器、服务器这类没有浏览器交互的场景。我在写自动化任务时更倾向于用环境变量，因为脚本可复现、不依赖本地缓存。不过要注意环境变量的优先级：如果同时配置了环境变量和本地登录凭证，工具实际会用哪一个，得去查当前版本的官方说明。经验是：在本地机器用登录凭证，在 CI 和容器里用环境变量，各安其位，互不干扰。
登录状态出问题时，常见反应是重新登录。交互会话里直接输/login可以再次发起登录，命令行层面也能处理会话失效。遇到“登录过期”之类的报错，不用慌，先看配置目录下的凭证文件是否还在，再判断是重新登录还是彻底清理重来。
1.3 第一个交互会话怎么玩
装好、登录完，随便找个目录敲下claude，你会进入一个交互式会话界面。底部有输入框，直接打字就像跟同事聊天。第一次玩的时候，可以试试让它“看看当前目录结构”“解释某段代码”。
交互模式下，Claude 不只是回复文字，它会调用工具：读文件、列目录、改代码、执行命令。每次调用工具，界面上都会展示它准备做什么，改动之前会征求你的确认，除非你已经给了它对应权限。这种“看得见、可打断、能拒绝”的交互方式，是 CLI 工具和网页端的最大区别。你不再是输入一段话等结果，而是全程参与 AI 的工作过程。
我第一次用的时候有个误解：以为 CLI 就是一个套壳聊天框。实际跑下来发现，它能直接操作真实项目文件，能在你的环境里执行命令，这意味着它不是一个参考工具，而是一个真正动手的同事。明确这个定位，后面理解权限模型、工具白名单这些机制就顺理成章了。
2. 核心命令拆解：交互模式、打印模式与会话恢复
2.1 交互模式：日常开发的主战场
交互模式就是直接执行claude进入的界面。它适合日常开发：让 AI 查问题、改代码、边看边改边确认。在这个模式下，你不需要关注那些命令行参数，所有操作靠聊天和斜杠命令完成。
进入交互模式后，有几个基础操作必须记住：
- 直接输入文本发送消息，按 Enter 发送
/help查看所有斜杠命令和快捷键/status查看当前会话状态- 连续按两次 Esc 可以中断 Claude 正在执行的操作
- 想要退出会话，输
/exit或按 Ctrl+C
中断操作这个功能我几乎天天用。有时候模型规划的方向不对，或者它开始改一些不该动的文件，我会立刻中断，重新给指示。在交互模式里，你始终掌握最终控制权，这也是我把日常开发放在交互模式、把批量任务交给打印模式的原因。
2.2 非交互模式：-p 参数和 stdin 管道
非交互模式是 CLI 工具真正“香”的地方。加上-p（即--print）之后，它不再进入聊天界面，而是执行完直接打印结果，然后退出：
claude -p "解释一下什么是布隆过滤器，用三句话"这个模式能放进任何脚本。比如我想快速审查一段代码，可以这样：
cat auth.ts | claude -p "审查这段代码的安全问题，输出 Markdown 列表"注意这里的核心规则：-p后面跟的是提示词，管道传入的内容会被当作上下文。很多新手踩的坑是把管道内容当成了提示词本身。正确姿势是把“指令”放-p，“被处理的数据”放 stdin。
我实际用下来最顺手的组合是：
claude -p "给这个文件补充完善的错误处理，保持原有逻辑不变" < src/service.ts输出可以直接重定向到文件，整个流程就变成了一个命令。这种“把复杂任务当命令执行”的思路，是 CLI 工具区别于网页版的核心价值。
2.3 会话续接：--continue 与 --resume 的使用时机
AI 编程助手最怕上下文丢失。你上午让它了解了项目结构，下午再开新会话，它又变成什么都不认识的新人。Claude Code 用会话机制解决这个问题。
# 继续最近一次会话 claude --continue # 恢复指定会话 claude --resume <session-id>--continue的语义是“接着刚才没聊完的继续”，它自动加载最近会话的历史；--resume更精确，后面跟会话 ID 就能恢复任意一次指定会话。在交互模式下，也可以输入/resume唤起会话选择器，从历史会话列表里挑一个继续。
我的经验是：跨天工作尽量用--resume恢复到上一个会话，而不是重新开一个。AI 对新会话完全失忆，重建上下文的成本很高。不过也要注意，会话历史越长，上下文占用越大，回复质量和速度都会下滑。一个会话用太久之后，记得用/compact压缩历史，把重要的信息提炼成摘要继续跑。
2.4 脚本友好的输出格式：--output-format
如果要把输出喂给脚本处理，光有文本可不够。--output-format参数就是为了解决这个问题。
# 默认纯文本 claude -p "列出当前目录所有 TODO 注释" # JSON 单对象输出 claude -p "列出当前目录所有 TODO 注释" --output-format json # 流式 JSON 输出 claude -p "列出当前目录所有 TODO 注释" --output-format stream-jsontext是默认值，适合给人看；json会输出结构完整的结果对象，适合程序解析；stream-json逐行输出 JSON 数据，适合长任务的实时处理。用 stream-json 时还可以加--include-partial-messages获取流式部分消息。
我在做自动化脚本时优先选json：解析稳定、字段固定，不会因为模型生成的格式变化导致脚本崩溃。记住一个原则：人看的用 text，机器解析的用 json，实时监控长任务才用 stream-json。
3. 权限与安全边界：让 CLI 放手到什么程度
3.1 权限机制为什么重要
Claude Code 能读文件、写文件、执行命令，本质上拥有了你机器的部分控制权。如果没有权限管控，它可能会在未经你同意的情况下执行危险操作。权限机制就是给这匹快马绑上缰绳。
默认情况下，Claude 尝试执行敏感操作时会弹出确认提示，询问你是否允许。这个机制看着简单，但实际体验有个微妙平衡：权限提示太少容易失控，太多会让人烦到想关掉所有提示。理解权限模型的粒度，才是高效使用 CLI 的关键。
3.2 permission-mode 四种取值的选择逻辑
--permission-mode参数决定了权限策略的宽严程度，我常用的有四种：
default：默认模式，敏感操作逐次询问，适合日常开发acceptEdits：自动接受文件编辑，其他敏感操作仍询问，适合“让它放手改代码”的场景plan：只读模式，不允许修改文件，适合代码审查、结构分析bypassPermissions：跳过所有权限确认，只适合完全可信的自动化环境
启动时指定：
claude --permission-mode acceptEdits claude --permission-mode plan我的选型逻辑是这样的：日常写代码用default，看住每一步；做机械性重构、批量改格式用acceptEdits，效率翻倍；只想要审查建议时用plan，绝对不会改坏文件；CI 里跑的是受控任务，才会考虑更宽的模式，但即便在 CI 里我也尽量用精确的工具白名单，而不是直接放开全部权限。
3.3 工具白名单：allowedTools 与 disallowedTools
比全局权限模式更精细的，是工具白名单。你可以用--allowedTools指定允许的工具，用--disallowedTools明确禁止某些工具：
# 允许执行 npm test，禁止其他 Bash 命令 claude --allowedTools "Bash(npm test)" "Edit" # 明确禁止删除类操作 claude --disallowedTools "Bash(rm *)" "Bash(git reset --hard *)"工具名支持通配匹配。Edit代表文件编辑，Read代表读取文件，Bash(具体命令)是限定 Bash 工具里某一条命令的白名单。这种粒度比一刀切的权限模式实用得多：既能让 AI 自由跑测试，又能防止它随便执行危险命令。
我建议把白名单理解成“给 AI 画的工作区域”。你在项目里用到的常规命令就那几条，干净利落地白名单化，比被弹窗打断十几次舒服多了。
3.4 关于 --dangerously-skip-permissions 的忠告
看到名字里带“dangerously”就知道这不是个善茬。--dangerously-skip-permissions会跳过所有权限确认，让 Claude 可以在你的系统上执行任意操作。我不建议在任何真实项目、重要机器上用这个参数，哪怕是在临时容器里，也要想清楚它的边界。
我见过有人为了省事直接带上这个参数跑自动化，结果 Claude 执行了超出预期的操作。正确做法永远是“最小权限”：需要什么工具就放行什么工具，能做多窄就做多窄。CI 环境里的命令是固定的，白名单完全可以穷举，根本不需要全局放开。权限上的“省事”，往往是最贵的事。
4. 斜杠命令全清单：会话内高频指令实测
4.1 会话治理四件套：status、cost、compact、clear
交互会话里，斜杠命令是最高频的操作入口。先说我每天都用的四个。
/status 查看当前会话状态 /cost 查看 token 消耗和费用 /compact 压缩会话历史，提炼摘要 /clear 清空当前会话历史，开启新对话/cost是成本控制的第一道防线。我习惯隔一段时间就敲一下，看这个会话烧了多少 token。AI 编程助手按 token 计费，一次不控制粒度的大规模重构可能消耗巨大。/compact是我用得比想象中频繁得多的命令——会话太长、上下文快满、回复开始迟钝时，压缩一次，效果立竿见影。
但要注意，压缩是有代价的。压缩后模型会丢掉一些细节，如果会话里有特别重要的约束条件，压缩前最好先把它们写进项目的记忆文件里，免得模型“失忆”。
4.2 模型与记忆：model、memory、add-dir
/model 切换模型 /memory 管理记忆文件 /add-dir 把指定目录加入上下文/model用来在会话中途切换模型。不同档位的模型在速度和深度上差异明显：轻量任务用轻量模型，复杂架构分析用重量模型。我把切换模型当成“对话策略”来用：写注释、小改动用轻量档，重构、排查疑难 bug 再切到高档位，成本和效果平衡得最好。
/memory管理的是记忆文件。Claude Code 会把项目级记忆写到项目根目录的CLAUDE.md文件，每次会话启动都会自动加载。这是整个工具里我认为最值得投入的地方：把你项目的结构约定、技术栈、编码规范、常见坑，用几句话写进这个文件里，AI 的工作质量会直接上一个台阶。
/add-dir则用于把目录加进上下文。大型仓库里全量扫一遍很不划算，按需把相关目录喂给 AI，既能保证它理解局部信息，又能控制 token 开销。
4.3 工程辅助：init、review、doctor、vim
/init 初始化项目记忆文件 /review 审查最近的代码改动 /doctor 运行自诊断，排查配置问题 /vim 切换 vim 键位模式/init是个好的起点：在项目里自动生成或补全CLAUDE.md。我第一次跑完/init后意识到，之前抱怨 AI 不理解项目，根源就是没给它一份“项目说明书”。/review则是基于最近一次 git 改动做审查，逻辑清晰、上手零成本。/doctor在你怀疑环境有问题时非常管用：能检查配置、依赖、登录状态，省去手工排查的时间。/vim是给 vim 用户的小彩蛋，如果你平时在终端里用 vim 键位，这个功能会让你觉得像是回到了家。
5. 把命令行工具搬进自动化：脚本与 CI 管道对接
5.1 批量任务的经典流水线写法
CLI 工具最值钱的使用场景，是脱离交互界面跑自动化。我经常做的一类任务是批量文档生成：
#!/bin/bash # 批量给 JS 文件生成技术说明文档 mkdir -p docs for f in src/*.js; do claude -p "为 $(basename "$f") 生成技术说明文档，包含函数签名、参数解释和返回值说明" < "$f" > "docs/$(basename "$f").md" done这个脚本的逻辑很直白：遍历文件、读取内容、交给 AI、输出文档。-p模式让 AI 变成一个可以从任意脚本调用的“函数”，输入文件内容，输出处理结果。我在实际项目里用这种方式只花了几分钟就给一个中型模块补齐了全部接口文档。
5.2 退出码语义与 CI 里的判断逻辑
脚本要可靠，必须懂退出码。Claude Code 的退出码语义基本稳定：
| 退出码 | 含义 | 应对策略 |
|---|---|---|
| 0 | 成功完成 | 正常处理输出 |
| 1 | 运行异常（网络、鉴权、内部错误） | 重试或告警 |
| 2 | 达到 --max-turns 上限 | 增大上限或拆分子任务 |
| 3 | 权限相关（工具被拒绝） | 调整权限白名单 |
在 CI 里我可以据此做差异化处理：
claude -p "review 当前 diff 的安全问题" --permission-mode plan --output-format json if [ $? -eq 3 ]; then echo "权限配置有问题，检查 allowedTools" exit 1 fi给自动化任务加--max-turns限制是必须做的，否则失控的循环会让 token 飞速消耗。任何没有预算上限的 AI 自动化脚本，都是定时炸弹。
5.3 MCP 管理命令：claude mcp 全参数
MCP（模型上下文协议）是 Claude Code 连接外部数据和服务的重要通道。命令行层面有一套专门的子命令：
# 列出所有 MCP 服务 claude mcp list # 添加一个 MCP 服务 claude mcp add my-docs -- npx -y some-mcp-server # 使用 HTTP 传输协议添加 claude mcp add local-api --transport http -- http://127.0.0.1:8080 # 查看某个 MCP 服务的详情 claude mcp get my-docs # 移除 MCP 服务 claude mcp remove my-docsclaude mcp add的常用参数包括--transport（指定 stdio、http 等传输协议）、--env（注入环境变量）、--scope（决定配置作用域，本地、项目还是用户级）。我习惯把连接数据库、搜索接口、内部文档系统这类能力都封装成 MCP 服务，让 AI 在会话里能直接查外部信息，而不是靠我手动贴上下文。配置完记得用claude mcp list验证服务挂在哪个作用域下，很多连接不上的问题都是作用域搞错了。
5.4 配置管理：claude config 的全局与项目作用域
配置管理也有专门的子命令体系：
# 查看当前配置 claude config list # 设置全局配置 claude config set --global theme dark # 设置项目级配置 claude config set --local theme light-daltonized # 读取某个配置项 claude config get theme全局配置作用于当前用户，项目配置会写进项目目录，优先于全局配置。我的习惯是：编辑器主题、通知渠道这类偏个人偏好的配置放全局；涉及具体项目的模型选择、权限设置放项目级。这种分层思路和 git 的--global与--local配置很相似，理解成本低，用起来顺手。
6. 常见问题排查与我的避坑心得
6.1 登录鉴权和环境变量相关的问题
遇到鉴权报错，优先按这个顺序排查：
- 先跑
claude看是否弹出登录引导，能进交互式说明登录正常 - 检查环境变量里是否残留了错误的 API 密钥
- 确认配置目录下凭证文件还在，没有被误清理
- 网络异常时问自己一个问题：同样的网络环境下其他依赖网络的服务正常吗
我在 CI 里踩过的坑是：环境变量拼写错误，导致工具读不到密钥，白白跑了十几分钟失败任务。所以建议在 CI 的启动阶段加一步打印密钥是否存在的检查：
test -n "$ANTHROPIC_API_KEY" || echo "API key is missing"6.2 上下文超限与成本失控的防护
“上下文窗口满了”是长时间使用后必然遇到的问题。表现是：AI 开始遗忘早期内容、回复质量下降、执行奇怪的操作。解决办法是及时/compact，但更重要的是把关键约束提前固化到CLAUDE.md里。
成本失控则是另一类高发问题。我的经验是每次都评估一下任务规模：预计要跑很久的任务，先口头给 AI 定一个“分阶段执行、每阶段确认”的基调；自动化任务一定加--max-turns；大批量任务先拿小样本试跑一次，估算成本再全量执行。控制成本和给代码做性能优化是同一个道理：先测量，再优化，最后才谈规模。
6.3 权限拦截和工具调用失败
权限相关报错的表现很典型：AI 想执行某条命令，系统提示被拒绝，进程以退出码 3 结束。遇到这种问题，先看是哪个工具被拦，再检查当前权限模式和白名单配置。比如你用acceptEdits模式，它能自动改文件，但 Bash 命令还是会被询问，这是正常的。
工具调用失败的另一种常见原因是命令依赖的环境没对齐。AI 执行npm test失败，往往不是因为 AI 不行，而是某个依赖没装、环境变量没配。这种时候别急着甩锅给 AI，先手动跑一遍同样的命令确认环境正常。
6.4 几条长期有效的实操习惯
最后分享几条我在实际项目中反复验证过的习惯。
第一，每个项目都维护一份CLAUDE.md。花十分钟写清楚项目目标、目录结构、技术栈、构建命令、代码规范、已知坑，后面所有会话的质量都会受益。这是投入产出比最高的一件事。
第二，会话里带上“工作进度”。每完成一个阶段，简单总结当前状态和下一步计划，告诉 AI 这是后续工作的上下文。这样即使会话被压缩、被中断，也能快速恢复。
第三，批量任务永远先小规模试跑。拿一个文件、一条命令试跑，确认输出符合预期、成本可接受，再扩大范围。我吃过几次直接全量跑的亏，之后再也没有跳过试跑这一步。
第四，善用plan模式做审查。只审查、不修改的模式非常适合做 code review 和架构分析，零风险，效果好。我把这个模式当成团队的免费初审，每天跑一遍，比手工检查省力得多。
Claude Code CLI 这一套命令体系，本质上就是给你一个可以编程调用、可以自动化、可以被信任控制的 AI 工作环境。把命令记熟只是第一步，真正提升效率的，是你怎么设计权限边界、怎么管理上下文、怎么把它嵌进现有的自动化流程里。希望这篇梳理能帮你少走一些弯路。
