第 10 章 · 01 核心命令与标志
文档摘要
第 10 章 · 01 核心命令与标志 本节摘要:Claude Code 的 CLI 是与其交互的第一入口。本节把常用命令与标志按"启动方式→命令族→标志分组"三层讲透:四种启动方式如何选、常用命令干什么、标志按模型/系统提示/权限/工作区/会话/高级六个维度怎么配。学完本节,你能不看文档组装出任意场景的启动命令。 学习目标 说出四种启动方式(REPL/ / / )的分工与组合用法。 说出 10 个以上常用命令与 5 个以上常用标志的含义。 说出交互模式与打印模式的能力差异。 说出模型选择相关标志(--model/--fallback-model/--effort/opusplan)的用法。
第 10 章 · 01 核心命令与标志
本节摘要:Claude Code 的 CLI 是与其交互的第一入口。本节把常用命令与标志按"启动方式→命令族→标志分组"三层讲透:四种启动方式如何选、常用命令干什么、标志按模型/系统提示/权限/工作区/会话/高级六个维度怎么配。学完本节,你能不看文档组装出任意场景的启动命令。
学习目标
- 说出四种启动方式(REPL/
-p/-c/-r)的分工与组合用法。 - 说出 10 个以上常用命令与 5 个以上常用标志的含义。
- 说出交互模式与打印模式的能力差异。
- 说出模型选择相关标志(--model/--fallback-model/--effort/opusplan)的用法。
一、四种启动方式
Claude Code 的启动命令可以浓缩为"四兄弟",其余都是它们的参数组合:
| 方式 | 命令 | 行为 | 适用场景 |
|---|---|---|---|
| 交互 REPL | claude |
进入多轮对话界面 | 日常开发、探索式工作 |
| 初始提示 | claude "query" |
带着问题进入 REPL | 有明确起点的工作 |
| 打印模式 | claude -p "query" |
单次问答后退出,可管道 | 脚本化、CI/CD、批处理 |
| 继续会话 | claude -c |
加载最近一次会话 | 接着上次的活继续干 |
| 恢复会话 | claude -r "名称" "query" |
按名称或 ID 恢复指定会话 | 多任务并行切换 |
三个高频组合:
# 继续最近会话并在打印模式下执行(检查类型错误) claude -c -p "check for type errors" # 恢复命名会话继续干活 claude -r "auth-refactor" "finish this PR" # 处理管道输入 cat logs.txt | claude -p "explain these errors"
交互 vs 打印:交互模式拥有多轮对话、Tab 补全、历史记录、斜杠命令;打印模式只做"单查询→退出",但换来可脚本化、可管道、可 JSON 输出。一句话:人在场用交互,机器在用打印。
二、常用命令速查
| 命令 | 作用 | 示例 |
|---|---|---|
claude update |
升级到最新版 | claude update |
/doctor |
诊断安装/配置/插件健康(响应中也可打开,f 键自动修复) |
REPL 内运行 |
claude mcp |
管理 MCP 服务器(含 login/logout) | claude mcp list |
claude mcp serve |
把 Claude Code 本身作为 MCP 服务器运行 | claude mcp serve |
claude agents |
打开 Agent View 多会话管理器 | claude agents |
claude plugin |
插件管理(install/enable/disable) | claude plugin install my-plugin |
claude plugin init <名> |
脚手架生成插件 | claude plugin init my-plugin |
claude plugin tag <版本> |
为插件创建发布 tag(带版本校验) | claude plugin tag v0.3.0 |
claude plugin prune |
清理孤儿插件依赖 | claude plugin prune |
claude install [版本] |
安装指定版本原生二进制 | claude install 2.1.131 |
claude project purge [路径] |
删除项目全部本地状态(先用 --dry-run 预览) | claude project purge ~/repo --dry-run |
claude ultrareview [目标] |
无头 PR 审查,成功退出 0/有发现退出 1 | claude ultrareview 1234 --json |
claude auth login/logout/status |
登录/登出/查认证状态 | claude auth status |
claude auto-mode defaults/reset |
查看/恢复自动模式默认规则 | claude auto-mode defaults |
claude remote-control |
启动远程控制服务 | claude remote-control |
小知识:v2.1.113 起 CLI 改为原生二进制分发(npm 安装体验不变,Windows 与固定环境仍用 JS 包)。代理环境注意把
downloads.claude.ai加入白名单,否则安装与更新会失败。
三、标志按功能分组
3.1 模型与配置
| 标志 | 作用 | 示例 |
|---|---|---|
--model |
指定模型(sonnet/opus/haiku 或完整名) | claude --model opus "design a caching strategy" |
--fallback-model |
主模型过载时自动回退(可配最多三个) | claude -p --model opus --fallback-model sonnet "query" |
--effort |
思考力度(low/medium/high/xhigh/max) | claude --effort xhigh |
--agents |
用 JSON 定义会话级自定义子代理 | 见第 3 节 |
--agent |
指定会话使用的代理 | claude --agent my-custom-agent |
opusplan 别名值得单独记住:它让 Opus 做计划、Sonnet 执行,是"贵脑想方案、快脑写代码"的省钱组合:
claude --model opusplan "design and implement the caching layer"
3.2 系统提示定制
| 标志 | 行为 | 交互 | 打印 |
|---|---|---|---|
--system-prompt |
整体替换默认系统提示 | ✅ | ✅ |
--system-prompt-file |
从文件加载替换(仅打印模式) | ❌ | ✅ |
--append-system-prompt |
在默认提示后追加 | ✅ | ✅ |
# 完全自定义人格 claude --system-prompt "You are a senior security engineer. Focus on vulnerabilities." # 追加固定要求 claude --append-system-prompt "Always include unit tests with code examples"
记住:--system-prompt-file 只在打印模式可用,交互模式请用另外两个。
3.3 工具与权限
| 标志 | 作用 | 示例 |
|---|---|---|
--tools |
限制可用内建工具 | claude -p --tools "Bash,Edit,Read" "query" |
--allowedTools |
免提示执行的白名单 | claude --allowedTools "Bash(git log:*)" "Read" |
--disallowedTools |
从上下文移除的黑名单 | claude --disallowedTools "Bash(rm:*)" "Edit" |
--permission-mode |
指定启动权限模式 | claude --permission-mode auto |
--dangerously-skip-permissions |
跳过全部权限询问(仅沙箱用) | 慎用 |
工具匹配支持 Tool(参数:值) 形式(v2.1.178+),不再局限于命令前缀与路径 glob:
# 只读审查:plan 模式 + 三个只读工具 claude --permission-mode plan --tools "Read,Grep,Glob" "audit this codebase" # 精确放行 git 系列命令 claude --allowedTools "Bash(git status:*)" "Bash(git log:*)" # 封禁危险操作 claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"
注意(v2.1.214 权限加固):Docker/Podman 守护进程重定向标志、
file命令的-m/-f参数现在强制询问;超过 10000 字符的 Bash 命令无论如何都要询问。另外--permission-mode在 v2.1.132+ 恢复会话时也会被尊重(早期版本会悄悄丢弃)。
3.4 工作区与目录
| 标志 | 作用 | 示例 |
|---|---|---|
--add-dir |
追加额外工作目录 | claude --add-dir ../frontend ../backend |
--settings |
从文件或 JSON 加载设置(≤2 MiB) | claude --settings '{"model":"opus","verbose":true}' |
--setting-sources |
指定设置来源(user,project) | claude --setting-sources user,project |
--plugin-dir |
从目录加载插件(可重复) | claude --plugin-dir ./my-plugin |
--mcp-config |
加载 MCP 服务器配置 | claude --mcp-config ./mcp.json "list open PRs" |
--strict-mcp-config |
只用指定的 MCP 配置 | claude --strict-mcp-config --mcp-config ./prod.json |
3.5 会话管理
| 标志 | 作用 | 示例 |
|---|---|---|
--session-id |
使用指定 UUID 会话 | claude --session-id "550e8400-..." |
--fork-session |
恢复时创建分支会话 | claude --resume abc123 --fork-session "try alternative approach" |
-n, --name |
会话显示名 | claude -n "auth-refactor" |
--from-pr <编号/URL> |
恢复关联 PR/MR 的会话(支持 GitHub/GitLab/Bitbucket) | claude --from-pr 42 |
--remote "任务" |
在 claude.ai 创建云端会话 | claude --remote "implement API" |
--teleport |
把云端会话搬回本地 | claude --teleport |
分支会话是"试错不伤主线"的关键:原会话保持不动,分叉出去的是一个全新独立会话。
3.6 高级与最小化
| 标志 | 作用 |
|---|---|
--bare |
最小模式:跳过 Hooks/技能/插件/MCP/自动记忆/CLAUDE.md |
--safe-mode |
关闭全部定制(隔离配置问题;环境变量 CLAUDE_CODE_SAFE_MODE=1) |
--max-turns |
限制代理轮数(非交互) |
--max-budget-usd |
打印模式费用上限(命中后连后台子代理一并停止) |
--debug |
调试模式,可过滤("api,mcp") |
--verbose |
详细日志 |
--no-session-persistence |
打印模式不保存会话 |
--disable-slash-commands |
禁用全部技能与斜杠命令 |
--chrome / --no-chrome |
启用/禁用浏览器集成 |
--ide |
自动连接 IDE |
排查配置问题的黄金路径:claude --safe-mode 启动 → 正常则逐个恢复定制项 → 定位肇事者。
四、模型选择
| 模型 | 定位 | 语境窗口 |
|---|---|---|
| Opus 5 | 旗舰,复杂架构与深度推理,默认 effort=high | 1M |
| Sonnet 5 | 默认均衡选择(Pro/Team 座位默认) | 1M |
| Opus 4.8 | 上一代旗舰,仍可选 | 1M |
| Sonnet 4.6 | 速度与能力平衡 | 1M |
| Haiku 4.5 | 最快,适合轻量任务,无 effort 等级 | 200K |
# 短名选择 claude --model haiku -p "format this JSON" # 完整模型名 claude --model claude-sonnet-4-6-20250929 "review this code" # 会话内快速切换 /fast
选型口诀:重活 Opus、日常 Sonnet、杂活 Haiku、组合 opusplan、兜底 fallback。
五、Agent View(多会话管理器)
claude agents(v2.1.139+,研究预览)把机器上所有会话收进一个列表,实时显示状态(running / blocked on you / done),是后台代理、定时任务、--bg 启动会话的统一"调度台":
claude agents
派发新会话时可带与 claude 相同的配置标志(--cwd/--settings/--mcp-config/--permission-mode/--model/--effort 等),还支持 --json 输出供脚本化使用(状态栏、会话选择器、tmux 集成)。按 Ctrl+T 可钉住某个后台会话——钉住的会话空闲不回收、更新时原地重启、内存压力下最后才被清理。
小结
- 启动四兄弟:REPL 日常用、
-p给机器用、-c接续、-r定向恢复。 - 标志六组:模型、系统提示、权限、工作区、会话、高级,按需取用。
- 最小化调试:
--bare与--safe-mode是排除定制干扰的两把钥匙。 - Agent View:多会话时代的统一调度台。
下一节预告:命令学会了,接下来解决"输出怎么喂给程序"——三种输出格式与 jq 管道。