Claude Code CLI 使用

Claude Code CLI 把项目文件、终端工具、权限规则和会话历史组合成一个可持续的开发循环。稳定使用的关键是先定工作区与权限，再让输出接受 Git 和测试验证。

当前实测版本：2.1.209 (Claude Code) · 当前模型 Fable 5 / Opus 4.8 / Sonnet 5 · 核对日期 2026-07-15

安装与更新

macOS / Linux 原生安装：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

验证和更新：

claude --version
claude update
claude doctor

如果已有 npm 版本，可以用当前 CLI 的原生安装命令迁移：

claude install stable

企业电脑执行在线安装脚本前，应使用批准的软件分发方式或按组织要求审查来源。使用 SuperToken 时继续看 Claude Code 安装与接入。

项目信任与第一次启动

cd /path/to/project
git status --short --branch
claude --permission-mode plan

第一次进入项目时，Claude Code 会要求确认是否信任当前目录。只信任你了解来源的仓库，因为以下内容可能影响会话：

• 项目 CLAUDE.md 和自动记忆。
• .claude/settings.json、Hooks、skills 和 plugins。
• 项目 .mcp.json 中的服务启动命令。
• 仓库脚本、包管理器生命周期脚本和测试命令。

显式 -p，以及 stdout 不是 TTY 的管道或重定向，都会进入非交互模式并跳过 workspace trust 对话，因此只在预先信任的固定目录中使用。Print 模式遇到无法通过校验的 settings 文件时会静默忽略它；自动化必须单独校验设置和实际工具范围。

数据与模型 Endpoint 边界

工具可以在本机读文件和执行命令，但提示词、被选入上下文的代码、图片和工具输出仍会发送到当前配置的模型 endpoint。“本地执行”不等于“内容不出机”。

claude auth status --text

开始敏感项目之前，核对当前认证方式、provider、ANTHROPIC_BASE_URL 或 SuperToken 接入设置。只提供任务必需的文件与日志，不根据未复核资料承诺 provider 的保留策略；客户代码和受监管数据应遵守团队的数据处理政策。

Claude Code CLI 版本与高频参数实测Anthropic Claude Code 2.1.209 来源：SuperToken 本机官方 CLI 实际输出，非 Anthropic 宣传图核对日期：2026-07-14脱敏状态：不含账号与密钥

启动方式

命令	作用
claude	启动交互会话
claude "先解释项目，不要修改"	带第一条任务启动
claude -c	继续当前目录最近一次会话
claude -r	选择历史会话；也可提供会话 ID 或搜索词
claude --fork-session -r SESSION_ID	从历史会话分叉新的会话 ID
claude --from-pr PR_NUMBER_OR_URL	恢复与 Pull Request 关联的会话
claude --name fix-login	为会话设置可搜索名称
claude --add-dir ../shared	额外开放目录访问
claude --no-session-persistence -p "..."	非交互且不保存会话

--add-dir 会扩大工具范围。只添加任务必须的具体目录，不开放整个用户目录或多个客户项目的共同上级目录。

Agent View：管理并行会话

当你同时运行多个长任务时，不必靠一排终端标签记住谁在等待、谁仍在工作。Anthropic 在 2026 年 5 月发布了 Agent View；当前本机 2.1.209 也已实证提供 claude agents 和 --bg。

可用性边界

截至本次核对，Anthropic 将 Agent View 标为 Research Preview，面向 Pro、Max、Team、Enterprise 和 Claude API plans，并受正常 rate limits 约束。账号、组织策略或版本不符合条件时，即使命令存在也可能无法完整使用。

::: note 截图更新说明 Agent View 发布时的官方图显示 Claude Code 2.1.129 和 Opus 4.7。功能步骤已用当前 2.1.209 与最新官方文档复核，但旧模型图不再收入本版手册。 :::

先启动一个边界清楚的后台任务，再打开总览：

claude --bg --permission-mode plan \
  "只读定位支付回调测试失败的根因，列出证据和最小修复建议，不修改文件"

claude agents

也可以在任意前台会话中按左方向键进入 Agent View，或输入 /bg 把当前会话转到后台。总览中的每一行会显示会话名称、最新回复、最后交互时间和当前状态：

• Needs input：Claude 在等待你的决定，应先处理会改变方向或权限边界的问题；
• Working：任务仍在运行，可以继续处理其他会话；
• Completed：任务已经结束，但仍需打开结果、检查 diff 和运行验证。

查看、回复和接管会话

1. 用方向键选中一行，先查看该会话最后一轮，不必离开总览。
2. 会话正在等待决定时，直接在底部输入回复；发送后它会继续运行。
3. 需要查看完整 transcript 或连续操作时，按 Enter 附着到该会话。
4. 在会话中按左方向键回到 Agent View；从总览按右方向键返回原会话。
5. 继续处理下一条，最后逐个检查产物、Git diff 和验证结果。

脚本查询状态

claude agents --json
claude agents --json --all
claude agents --json --cwd /path/to/project

--all 只和 --json 配合，用于包含已完成会话。JSON 可能包含绝对目录、会话名称和 session ID，写入日志或分享前先脱敏。

Agent View 解决的是“看见和接续多个会话”，不会自动隔离它们的文件、端口、数据库或云端账号。两个会修改代码的任务应使用不同 worktree；共享同一目录的并行任务至少要做到文件范围不重叠，并禁止同时执行迁移、发布或写入同一个外部环境。

怎样描述复杂任务

使用目标、事实、边界和完成标准：

目标：
修复上传头像后页面仍显示旧图片的问题。

已知事实：
- 上传请求成功，刷新页面后能看到新头像；
- 组件在 src/features/profile/AvatarEditor.tsx；
- 数据请求使用现有 query client。

边界：
- 不修改后端缓存策略；
- 不引入新的状态管理依赖；
- 保持失败重试和错误提示不变。

完成标准：
- 先复现并解释根因；
- 添加回归测试；
- 做最小修改；
- 运行相关测试、类型检查和 lint；
- 最后汇报验证结果与剩余风险。

仍有关键歧义时：

先不要写代码。检查仓库后，只问最多五个会改变实现方向的问题。
同时列出已经能从代码确认的事实，避免询问仓库中已有答案的问题。

权限模式

当前 2.1.209 的 --permission-mode 明确提供：

模式	适合	注意
plan	陌生仓库、架构、复杂任务开局	先调查和规划，不应直接实现
manual	日常稳妥开发	工具动作按当前规则和风险由你确认
acceptEdits	熟悉仓库的连续文件编辑	接受编辑不等于允许所有 Bash、网络和外部动作
dontAsk	只运行预先允许的工具	未授权动作直接失败，不通过弹窗扩大范围
auto	当前版本和组织策略允许的自动判断	仍需保持敏感目录、命令和外部资源边界
bypassPermissions	外部已经严格隔离的 runner	普通本机不要使用

启动示例：

claude --permission-mode plan
claude --permission-mode acceptEdits

DANGER

--dangerously-skip-permissions / bypassPermissions 会绕过正常权限检查。只有外部 sandbox 同时做到无互联网、无敏感数据与凭据、文件系统可丢弃且任务范围被独立限制时才考虑使用。

检查 Auto mode

不要只看模式名称，先检查当前规则：

claude auto-mode defaults
claude auto-mode config
claude auto-mode critique

defaults 输出默认 environment、allow、soft_deny 和 hard_deny；config 输出合并后的有效配置。当前 2.1.209 默认 allow 中可能包含向工作分支执行 Git push，因此 Auto mode 也可能允许外部写入。使用前审查实际规则、仓库远端和凭据，生产发布仍保留独立人工审批。

critique 会调用模型评价自定义规则，不是离线语法检查。只想查看本地有效配置时使用 defaults 和 config 即可。

限制可用工具与权限规则

一次性限制：

claude \
  --tools "Read,Edit,Bash" \
  --allowedTools "Read,Edit,Bash(npm run lint),Bash(npm test *)" \
  --disallowedTools "Bash(git push *),Bash(npm publish *)"

--tools 限制本次会话有哪些内置工具可用。--allowedTools 让匹配项无需再次询问即可执行，并不是“除此之外的工具都不存在”；--disallowedTools 拒绝匹配项。工具名和匹配语法以当前 CLI 与设置文档为准。每一项都应能解释为什么需要；过宽 Bash(*) 会失去审批意义。

这些工具选项接收一个或多个值。后面还要提供位置参数 prompt 时，用独立的 -- 结束选项解析，避免 prompt 被当成额外工具名。

会话内常用入口

输入 / 查看当前安装的完整菜单。常见入口：

命令	用途
/help	查看当前版本帮助
/init	生成项目 CLAUDE.md 初稿
/plan	进入计划工作流
/permissions	查看或调整权限
/model	选择当前可用模型
/context	查看上下文占用
/compact	压缩长会话并保留关键状态
/clear	开始新的对话上下文
/resume	恢复历史会话
/memory	查看或管理记忆
/mcp	查看 MCP 状态
/doctor	完整检查并在允许时修复问题

插件和 skills 会增加斜杠入口，因此手册不把这张表当成完整命令清单。

管理上下文

• 用 @path/to/file 指向关键文件，不一次塞入整个仓库。
• 先让 Claude 搜索定义、调用方和测试，再决定加载哪些内容。
• 用 /context 检查占用；阶段结束后用 /compact。
• 目标、仓库或信任边界改变时开新会话。
• 发现跑偏立即纠正，不等整轮结束。

推荐压缩指令：

/compact 保留：原始需求、已确认根因、修改文件、验证命令、失败结果、未完成步骤和剩余风险。
删除已被实验否定的假设和无关探索过程。

恢复会话后先复核目录、分支、Git diff 和未完成项。历史内容可能正确，但工作区已经变化。

非交互执行

非交互运行应同时固定可信工作目录、permission mode 和 --tools。不需要项目 CLAUDE.md、Hooks、MCP 或插件的纯 stdin 任务，使用 --safe-mode --tools ""；内容不应写入本地会话历史时再加 --no-session-persistence。

只读摘要：

claude -p \
  --permission-mode plan \
  --tools "Read,Glob,Grep" \
  -- "概括仓库架构、关键命令和三个主要风险；引用文件，不修改"

JSON 输出：

claude -p --output-format json --permission-mode plan \
  --tools "Read,Glob,Grep" \
  -- "分析仓库并返回摘要与风险，不修改文件" > report.json

结构化结果：

claude -p --output-format json \
  --permission-mode plan \
  --tools "Read,Glob,Grep" \
  --json-schema '{"type":"object","properties":{"summary":{"type":"string"},"risks":{"type":"array","items":{"type":"string"}}},"required":["summary","risks"]}' \
  -- "分析当前仓库，不修改文件" > report.json

流式自动化使用 --input-format stream-json 和 --output-format stream-json；只有 --print 模式支持，当前 2.1.209 的 stream-json 输出还要求 --verbose。--include-partial-messages 输出增量消息，--include-hook-events 把 Hook 生命周期事件加入 stream-json，--replay-user-messages 只在输入和输出都为 stream-json 时回显输入确认。调用方必须解析事件、处理部分消息、检查最终状态和退出码。

成本、模型与回退

当前 CLI 在非交互模式支持预算上限：

claude -p --max-budget-usd 2 --permission-mode plan \
  --tools "Read,Glob,Grep" \
  -- "只读分析这个仓库，不修改"

--model 可以使用当前账号支持的别名或完整模型名；--fallback-model 仅用于 --print，主模型不可用时按配置尝试回退。

别名	Anthropic API 当前含义
best	组织有权限时使用 Fable 5，否则使用最新 Opus
fable	Claude Fable 5，适合最长、最困难的自主任务；不是默认模型
opus	Claude Opus 4.8
sonnet	Claude Sonnet 5
haiku	当前快速、轻量的 Haiku

例如 claude --model fable 或 claude --model claude-opus-4-8。Fable 5 需要 Claude Code 2.1.170+，Opus 4.8 需要 2.1.154+，Sonnet 5 需要 2.1.197+；本机 2.1.209 已满足。第三方 provider、自定义 ANTHROPIC_BASE_URL 和组织 allowlist 可能改变可用模型或别名映射，不要在团队脚本中假设所有账号完全相同。

--effort 可以选择 low、medium、high、xhigh 或 max。当前 --help 只确认这些取值，没有给出每个模型下的质量、时延或用量换算；应在实际账号与模型上验证，不把 max 假定为所有任务的最佳默认值。

Safe mode 与 Bare mode

排查项目定制：

claude --safe-mode

Safe mode 暂时禁用 CLAUDE.md、skills、plugins、Hooks、MCP、自动记忆和其他自定义，但保留认证、模型、内置工具与管理员策略。它适合判断异常是否来自定制层。

最小运行模式：

claude --bare

Bare mode 跳过 Hooks、LSP、插件同步、自动记忆、后台预取、keychain 读取和 CLAUDE.md 自动发现。它不会读取 OAuth 或 keychain 凭据，只接受 ANTHROPIC_API_KEY，或通过 --settings 提供的 apiKeyHelper；Bedrock、Vertex 和 Foundry 等第三方 provider 使用各自凭据。它对自动化缓存和最小环境有用，但你必须显式提供需要的认证、设置、目录和上下文。

无障碍终端输出

屏幕阅读器模式：

claude --ax-screen-reader

它使用扁平文本，减少装饰边框和动画。团队文档和 CI 日志也应避免只靠颜色表达状态。

CLI 交付检查清单

• 工作目录、分支和已有修改清楚。
• 权限模式与任务风险匹配，没有危险绕过。
• 结论来自代码、命令和测试证据。
• 完整 diff 已审查，无密钥、无关文件和调试产物。
• 非交互调用校验退出码、JSON、预算和必需字段。
• 最终结果区分通过、失败、未运行和人工验证。

官方资料

• Model configuration
• CLI reference
• Agent view in Claude Code
• Agent View documentation
• Interactive mode
• Permissions
• Common workflows