02｜CLI 入门：启动、查询、恢复会话与选择模型

通过真实 CLI 命令掌握交互、打印、恢复、模型和配置选项。

终端像一张写着当前房间地址的工作台。安装程序只是把一个新工具放进工具柜；真正危险的不是命令行本身，而是不知道自己在哪个目录、命令将碰哪些文件。

本课交付物

检查 Node 与 Git 版本，在临时练习目录安装并启动 Claude Code；记录 which、pwd、git status 的输出，确认工具位置、当前目录与仓库状态。

---

概览

Claude Code 的 CLI（命令行接口）是与 Claude Code 交互的主要方式。它提供了强大的参数和命令，用于执行查询、管理会话、配置模型，并把 Claude 集成进你的开发工作流。

架构

graph TD
    A["用户终端"] -->|"claude [options] [query]"| B["Claude Code CLI"]
    B -->|Interactive| C["REPL 模式"]
    B -->|"--print"| D["打印模式（SDK）"]
    B -->|"--resume"| E["恢复会话"]
    C -->|Conversation| F["Claude API"]
    D -->|Single Query| F
    E -->|Load Context| F
    F -->|Response| G["输出"]
    G -->|text/json/stream-json| H["终端 / 管道"]

CLI 命令

命令	说明	示例
claude	启动交互式 REPL	claude
claude "query"	带初始提示启动 REPL	claude "解释这个项目"
claude -p "query"	打印模式，查询后退出	claude -p "解释这个函数"
cat file | claude -p "query"	处理通过管道传入的内容	cat logs.txt | claude -p "解释这些日志"
claude -c	继续最近一次会话	claude -c
claude -c -p "query"	在打印模式下继续会话	claude -c -p "检查类型错误"
claude -r "<session>" "query"	通过 ID 或名称恢复会话	claude -r "auth-refactor" "完成这个 PR"
claude update	更新到最新版本	claude update
claude mcp	配置 MCP servers	见 MCP 文档
claude mcp serve	将 Claude Code 作为 MCP server 运行	claude mcp serve
claude agents	列出所有已配置的 subagents	claude agents
claude auto-mode defaults	以 JSON 打印 auto mode 默认规则	claude auto-mode defaults
claude remote-control	启动远程控制服务	claude remote-control
claude plugin	管理插件（安装、启用、禁用）	claude plugin install my-plugin
claude auth login	登录（支持 --email、--sso）	claude auth login --email user@example.com
claude auth logout	注销当前账号	claude auth logout
claude auth status	检查登录状态（已登录返回 0，否则返回 1）	claude auth status

核心标志

参数	说明	示例
-p, --print	不进入交互式模式，直接输出结果	claude -p "query"
-c, --continue	加载最近一次会话	claude --continue
-r, --resume	按 ID 或名称恢复指定会话	claude --resume auth-refactor
-v, --version	输出版本号	claude -v
-w, --worktree	在隔离的 git worktree 中启动	claude -w
-n, --name	设置会话显示名称	claude -n "auth-refactor"
--from-pr <number>	恢复与 GitHub PR 关联的会话	claude --from-pr 42
--remote "task"	在 claude.ai 上创建 web session	claude --remote "implement API"
--remote-control, --rc	使用 Remote Control 进入交互式会话	claude --rc
--teleport	将 web session 恢复到本地	claude --teleport
--teammate-mode	agent team 显示模式	claude --teammate-mode tmux
--bare	极简模式，跳过 hooks、skills、plugins、MCP、自动记忆和 CLAUDE.md	claude --bare
--enable-auto-mode	解锁 auto permission mode	claude --enable-auto-mode
--channels	订阅 MCP channel 插件	claude --channels discord,telegram
--chrome / --no-chrome	启用 / 禁用 Chrome 浏览器集成	claude --chrome
--effort	设置推理强度	claude --effort high
--init / --init-only	运行初始化 hooks	claude --init
--maintenance	运行维护 hooks 后退出	claude --maintenance
--disable-slash-commands	禁用所有 skills 和 slash commands	claude --disable-slash-commands
--no-session-persistence	禁用会话保存（打印模式）	claude -p --no-session-persistence "query"

交互模式 vs 打印模式

graph LR
    A["claude"] -->|默认| B["交互式 REPL"]
    A -->|"-p 参数"| C["打印模式"]
    B -->|特性| D["多轮对话<br>Tab 补全<br>历史记录<br>Slash commands"]
    C -->|特性| E["单次查询<br>可脚本化<br>可管道化<br>JSON 输出"]

交互模式（默认）：

# 启动交互式会话
claude

# 带初始提示启动
claude "解释这个认证流程"

打印模式（非交互式）：

# 单次查询后退出
claude -p "这个函数做什么？"

# 处理文件内容
cat error.log | claude -p "解释这个错误"

# 与其他工具串联
claude -p "列出待办事项" | grep "URGENT"

模型与配置

参数	说明	示例
--model	设置模型（sonnet、opus、haiku，或完整模型名）	claude --model opus
--fallback-model	当前模型负载过高时自动切换的后备模型	claude -p --fallback-model sonnet "query"
--agent	为当前会话指定 agent	claude --agent my-custom-agent
--agents	通过 JSON 定义自定义 subagents	见 Agents Configuration
--effort	设置推理级别（low、medium、high、max）	claude --effort high

模型选择示例

# 复杂任务使用 Opus 4.6
claude --model opus "设计一个缓存策略"

# 快速任务使用 Haiku 4.5
claude --model haiku -p "格式化这个 JSON"

# 使用完整模型名
claude --model claude-sonnet-4-6-20250929 "审查这段代码"

# 带后备模型以提升稳定性
claude -p --model opus --fallback-model sonnet "分析架构"

# 使用 opusplan（Opus 负责规划，Sonnet 负责执行）
claude --model opusplan "设计并实现缓存层"

系统提示词自定义

参数	说明	示例
--system-prompt	替换整段默认系统提示词	claude --system-prompt "You are a Python expert"
--system-prompt-file	从文件加载提示词（仅打印模式）	claude -p --system-prompt-file ./prompt.txt "query"
--append-system-prompt	在默认提示词后追加内容	claude --append-system-prompt "Always use TypeScript"

系统提示词示例

# 完整自定义人格
claude --system-prompt "你是一名资深安全工程师，重点关注漏洞。"

# 追加特定指令
claude --append-system-prompt "始终在代码示例中包含单元测试"

# 从文件加载复杂提示词
claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py"

系统提示词参数对比

参数	行为	交互模式	打印模式
--system-prompt	替换整个默认系统提示词	✅	✅
--system-prompt-file	用文件中的提示词替换	❌	✅
--append-system-prompt	追加到默认系统提示词后	✅	✅

仅在打印模式中使用 --system-prompt-file。交互模式请使用 --system-prompt 或 --append-system-prompt。

工具与权限管理

参数	说明	示例
--tools	限制可用的内置工具	claude -p --tools "Bash,Edit,Read" "query"
--allowedTools	无需提示即可执行的工具	"Bash(git log:*)" "Read"
--disallowedTools	从上下文中移除的工具	"Bash(rm:*)" "Edit"
--dangerously-skip-permissions	跳过所有权限提示	claude --dangerously-skip-permissions
--permission-mode	以指定权限模式启动	claude --permission-mode auto
--permission-prompt-tool	用于权限处理的 MCP tool	claude -p --permission-prompt-tool mcp_auth "query"
--enable-auto-mode	解锁 auto permission mode	claude --enable-auto-mode

权限示例

# 代码审查只读模式
claude --permission-mode plan "审查这个代码库"

# 只允许安全工具
claude --tools "Read,Grep,Glob" -p "找出所有 TODO 注释"

# 允许特定 git 命令无需提示
claude --allowedTools "Bash(git status:*)" "Bash(git log:*)"

# 阻止危险操作
claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"

输出与格式

参数	说明	选项	示例
--output-format	指定输出格式（打印模式）	text、json、stream-json	claude -p --output-format json "query"
--input-format	指定输入格式（打印模式）	text、stream-json	claude -p --input-format stream-json
--verbose	启用详细日志		claude --verbose
--include-partial-messages	包含流式事件	需要 stream-json	claude -p --output-format stream-json --include-partial-messages "query"
--json-schema	获取符合 schema 的 JSON 输出		claude -p --json-schema '{"type":"object"}' "query"
--max-budget-usd	打印模式最大花费		claude -p --max-budget-usd 5.00 "query"

输出格式示例

# 纯文本（默认）
claude -p "解释这段代码"

# 供程序使用的 JSON
claude -p --output-format json "列出 main.py 中的所有函数"

# 用于实时处理的流式 JSON
claude -p --output-format stream-json "生成一份长报告"

# 使用 schema 验证的结构化输出
claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \
  "找出这段代码中的 bug，并以 JSON 返回"

工作区与目录

参数	说明	示例
--working-directory	设置工作目录	claude --working-directory /path/to/project
--add-dir	追加额外工作目录	claude --add-dir /path/to/other/project

多目录示例

# 在多个项目目录中协作
claude --working-directory ~/projects/app --add-dir ~/projects/shared

# 加载自定义设置
claude --working-directory ./backend --add-dir ./frontend

MCP 配置

参数	说明	示例
--mcp-config	从文件加载 MCP 配置	claude --mcp-config ./mcp.json
--mcp	启用 / 配置 MCP 服务	claude --mcp github
--mcp-list	列出可用 MCP 配置	claude --mcp-list

MCP 示例

# 加载 GitHub MCP server
claude --mcp-config ./configs/github-mcp.json

# 严格模式，只允许指定的 server
claude --mcp-config ./configs/strict-mcp.json --mcp github

---

本站实战工作台

安装前先认识三个地址

很多新手不是卡在 Claude Code，而是卡在“我现在到底在哪”。终端提示符所在的目录、Claude Code 可执行文件所在的位置、Git 仓库的根目录，是三个不同地址。

• 当前工作目录决定相对路径会指向哪里，可用 pwd 查看。
• 程序路径决定你实际启动的是哪个版本，可用 command -v claude 查看。
• 仓库根目录决定 Git 把哪些文件视为同一个项目，可用 git rev-parse --show-toplevel 查看。

先弄清这三者，能避免把实验文件写进家目录、在错误仓库执行命令，或升级后仍调用旧版本。

建一个可以整间扔掉的练习室

不要用公司的生产仓库做第一次启动。创建独立目录，并让 Git 记录基线：

mkdir -p ~/aihubhub-labs/claude-install
cd ~/aihubhub-labs/claude-install
git init
printf '# Claude Code 安装实验\n' > README.md
git add README.md
git commit -m "chore: create safe installation lab"

如果 Git 因身份配置拒绝提交，只为这个练习仓库设置本地 user.name 与 user.email，不要不理解地覆盖全局配置。

检查依赖，再按官方渠道安装

Claude Code 的安装方式会演进，因此命令应以当前官方安装页为准，而不是复制一年前博客里的片段。安装前记录操作系统、shell、Node/Git 版本；安装后记录程序路径和版本。关键不是背命令，而是让变化可追溯。

uname -a
echo "$SHELL"
node --version
git --version
command -v claude
claude --version

不要把登录令牌、Cookie 或完整环境变量贴进聊天。可以记录“认证成功”和账号环境名称，但不要记录秘密值。

第一次启动时观察什么

在练习目录启动后，先让 Claude Code回答当前目录与可见文件，不授权写入。然后提出一个只读问题：“解释 README，并告诉我 git status 是否干净。”你要观察四件事：它是否识别当前仓库、权限请求是否与动作匹配、工具输出是否可见、退出后目录是否保持干净。

pwd
git status --short
git diff --stat

三条命令都应与启动前基线一致。若出现陌生文件，先检查内容和来源，不要直接用清理命令抹掉证据。

PATH 问题为什么最常见

“安装成功但找不到 claude”通常表示安装目录没有进入 PATH，或图形终端与登录 shell 读取了不同配置。先比较 command -v、shell 配置文件和新终端结果。不要为了省事把多个可疑目录全部追加到 PATH；这会让同名程序的优先级更难解释。

如果存在多个版本，用 type -a claude 列出候选，再明确保留哪一个。修正后关闭并重新打开终端，重新记录版本与路径。

卸载与恢复也属于安装

一次专业安装必须回答如何撤销：程序由哪个包管理器安装、配置保存在何处、项目文件有没有变化。不要删除账号数据或全局配置来证明“能卸载”；在练习中只验证包管理器的卸载说明和项目目录无残留。

本课交付物

创建 install-report.md，写下环境摘要、官方安装来源、安装前后版本、二进制路径、首次只读交互、Git 基线对比与卸载路径。敏感字段只写“已配置/未配置”。这份报告能让未来的你解释工具从哪里来，也能让团队复现同样环境。