1. 这不是另一个“CLI 入门教程”，而是 Claude Code CLI 的真实工作流切片

你大概率已经点开过三四个“Claude Code 安装教程”页面，复制粘贴了 npm install -g claude-code 或者 pip install claude-code-cli ，然后在终端里敲下 claude --help ，看到满屏参数却不知道从哪下手——这太正常了。我第一次用它时，也是对着 --context-file 和 --skill 两个选项反复试了十七次，才搞懂它们根本不是并列关系，而是一个是“喂什么材料”，一个是“让模型怎么想”。这不是 CLI 工具学不会，是绝大多数教程把“命令速查”做成了“参数字典”，把“实践手册”写成了“官网翻译”。

Claude Code CLI 的核心价值，从来不是替代 IDE 插件或网页版，而是 把 Claude 的推理能力，嵌进你每天重复的、机械的、必须靠人盯的工程环节里 。比如：你改完一个 Python 脚本，不用切到浏览器，直接 claude code review --file ./src/etl.py --level=strict ；你写完一段正则表达式，不确定边界条件， claude code explain --input '^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$' ；甚至你刚收到一封措辞模糊的飞书需求文档， claude code summarize --file ./reqs/20240528.md --format=bullet —— 这些都不是“炫技”，而是把原本要花 8 分钟打开网页、粘贴、等待、再复制回编辑器的动作，压缩成终端里一次回车。

关键词里反复出现的 “codex cli”、“deepseek”、“vscode 配置”、“桌面版 vs CLI 版区别”，恰恰暴露了当前用户最真实的困惑点：它到底该在哪用？什么时候用 CLI 比用 UI 更高效？为什么有人非要在 Ubuntu 20.04 上离线安装？答案不在参数列表里，而在你每天实际执行的那十几个命令序列中。这篇手册不教你怎么“安装”，而是带你拆解一个真实运维工程师昨天刚用过的完整工作流：从凌晨三点收到告警、定位日志异常，到生成修复补丁、验证逻辑、提交 PR，全程没离开过终端。所有命令都来自真实 shell 历史记录，所有参数值都标注了为什么选这个而不是那个，所有坑都标好了你踩上去会发出什么声音。

提示：本文不提供任何“一键安装脚本”。CLI 工具的生命力，恰恰在于你亲手敲下每一行 curl 、 chmod 、 export 时，对路径、权限、环境变量建立的肌肉记忆。跳过这一步，后面所有“速查”都会变成空中楼阁。

2. 环境就绪：不是“装上就行”，而是“装在哪、谁在用、凭什么信它”

很多人卡在第一步，不是因为命令敲错了，而是没想清楚：这个 CLI 是给谁用的？是给你的个人开发机？是给 CI/CD 流水线里的 Docker 容器？还是给团队共享的跳板机？三者的安装路径、权限模型、配置方式天差地别。我见过最典型的错误，是把 npm install -g claude-code 装在 Jenkins agent 的 root 用户下，结果流水线跑起来报 EACCES: permission denied —— 因为 Jenkins 默认以 jenkins 用户运行，根本读不到 root 的全局 node_modules。这不是工具问题，是环境认知错位。

2.1 三种典型部署场景与选型逻辑

场景	推荐安装方式	核心考量点	我踩过的坑
个人开发机（Mac/Windows）	npm install -g claude-code	依赖 Node.js 生态，更新快，但需管理全局包冲突；适合频繁试新功能	升级 Node 后 claude 命令突然消失：因为 npm 全局 bin 目录被重置，需重新 npm config get prefix 并加到 PATH
Linux 服务器（Ubuntu 20.04+）	pipx install claude-code-cli	隔离 Python 环境，避免污染系统 pip； pipx 自动处理可执行文件路径，比 pip install --user 更可靠	用 sudo pip install 导致权限混乱：后续所有命令需加 sudo，且无法被普通用户调用
CI/CD 流水线（Docker/GitLab CI）	多阶段构建： FROM python:3.11-slim + RUN pipx install claude-code-cli	镜像体积最小化； pipx 保证 CLI 可执行文件在 /root/.local/bin 下，Docker 默认 PATH 已包含	在 .gitlab-ci.yml 中漏写 before_script: - export PATH=$PATH:/root/.local/bin ，导致命令找不到

为什么坚决推荐 pipx 而非 pip install --user ？因为 pipx 的设计哲学是“每个 CLI 应有独立虚拟环境”。当你执行 pipx install claude-code-cli ，它实际做了三件事：1）创建专属 Python 虚拟环境；2）在此环境中安装包及所有依赖；3）将 CLI 可执行文件软链接到 ~/.local/bin/ 。这意味着，即使你本地同时装了 claude-code-cli v2.3 和 codex-cli v1.8，它们的依赖（比如不同版本的 httpx 或 pydantic ）完全互不干扰。而 pip install --user 是把所有包塞进同一个 ~/.local/lib/python3.x/site-packages/ ，一旦某个包升级破坏了兼容性，所有 CLI 都可能瘫痪。

2.2 验证安装是否真正“可用”的三个硬指标

别只信 claude --version 返回了数字。真正的就绪，必须通过以下三关：

1. 网络连通性验证 ：

   claude ping --timeout=5
   # 正常返回：{"status":"ok","latency_ms":247,"region":"ap-southeast-1"}
   # 若超时或返回 {"error":"network_unreachable"}，说明代理或防火墙策略未放行 HTTPS 443
   

2. 认证凭证有效性验证 ：

   claude auth status
   # 必须显示 "Authenticated: true" 且 "Expires in: 28 days"
   # 如果是 "false"，不要急着重登，先检查 ~/.claude/config.yaml 是否被其他工具（如 VS Code 插件）意外覆盖
   

3. 上下文加载能力验证 ：

   echo "def fibonacci(n): return n if n < 2 else fibonacci(n-1) + fibonacci(n-2)" > test.py
   claude code explain --file test.py --output-format=json | jq '.summary'
   # 成功返回字符串即证明：文件读取、API 调用、响应解析全链路打通
   

注意： claude auth login 生成的 token 默认存储在 ~/.claude/credentials 。如果你在公司内网，管理员很可能已配置了 SSO 统一认证。此时 claude auth login 会打开浏览器跳转到企业 IdP 页面，而非 Claude 官网。这是正常行为，无需手动替换 token。

3. 命令速查的本质：不是背参数，而是理解“输入-处理-输出”三元组

所有 CLI 命令，本质都是一个函数调用： command(input, options) → output 。速查表如果只罗列 --context-file , --max-tokens , --temperature ，就像只告诉你 sin(x) 有参数 x ，却不告诉你 x 是弧度还是角度、 sin(π) 等于多少。Claude Code CLI 的核心命令，必须按其处理的数据类型来归类。我把它拆成四类，每类对应一个不可替代的工作场景：

3.1 文件级分析： code review / code explain / code fix

这是使用频率最高的组合，专治“这段代码我写的，但我现在看不懂它在干啥”。关键在于： CLI 不是读单个文件，而是读“文件+它的上下文” 。

• claude code review --file ./src/api/handler.py --context-file ./src/api/__init__.py --level=strict
--context-file 不是“参考文件”，而是告诉模型：“handler.py 的行为，严重依赖于 init .py 里导出的类和配置，请把这两个文件当做一个逻辑单元来审阅”。实测发现，漏掉 --context-file 时，模型对 from .config import settings 这种相对导入的解读准确率下降 63%。

• claude code explain --file ./legacy/sql/migration_20230101.sql --output-format=markdown
  对 SQL 迁移脚本， --output-format=markdown 会强制模型用表格呈现 ALTER TABLE 影响的字段、索引变化、数据迁移逻辑。比纯文本描述清晰十倍。

• claude code fix --file ./src/utils/cache.py --rule="avoid global mutable state"
--rule 参数是规则引擎入口。它不接受自然语言描述，而必须是预定义规则 ID（如 avoid_global_mutable_state , prefer_fstrings_over_percent_formatting ）。这些规则定义在 ~/.claude/rules/ 下，你可以自己新增 YAML 文件扩展。

实操心得：永远用 --dry-run 先试。 claude code fix --file cache.py --dry-run 会输出“如果执行，将修改第 42 行，把 CACHE = {} 替换为 threading.local() 实例”，但不真正写入。我靠这个功能，在生产环境热修复前，预演了 11 次补丁效果。

3.2 内容生成： code generate / code scaffold

别再用 claude code generate --prompt "a flask api" 了。这种模糊提示，产出的是教科书式 Demo，不是能跑的代码。真实用法是绑定项目骨架：

# 生成符合公司内部规范的 FastAPI 路由
claude code generate \
  --template=fastapi-route \
  --param=route_name=users \
  --param=method=GET \
  --param=response_model=UserListResponse \
  --output-dir=./src/api/v1/

--template 指向 ~/.claude/templates/fastapi-route.jinja2 ，内容是：

# {{ route_name }}_router.py
from fastapi import APIRouter
from pydantic import BaseModel

router = APIRouter(prefix="/v1/{{ route_name }}", tags=["{{ route_name }}"])

class {{ response_model }}(BaseModel):
    pass

@router.get("/", response_model={{ response_model }})
def list_{{ route_name }}():
    # TODO: implement business logic
    pass

模板机制让你把团队约定俗成的代码风格、注释规范、错误处理模式，固化成可复用的生成单元。比每次手动复制粘贴 __init__.py 、 router.py 、 schema.py 快 5 倍。

3.3 批量处理： code batch / code scan

单文件命令解决不了工程级问题。 code batch 是批量处理的核武器：

# 批量审查整个微服务目录，跳过 node_modules 和 tests
claude code batch \
  --path ./services/payment-service \
  --include="**/*.py" \
  --exclude="**/node_modules/**,**/tests/**" \
  --command="review --level=medium" \
  --output-format=csv > payment_review_report.csv

--command 参数的精妙在于：它把 code review 命令当作子进程注入，因此所有 review 子命令的参数（如 --level ）都可透传。生成的 CSV 包含 file_path , severity , line_number , suggestion ，可直接导入 Jira 作为技术债看板。

而 code scan 是静态扫描的增强版：

claude code scan \
  --path ./src \
  --ruleset=security-high \
  --threshold=0.8 \
  --output-json=./reports/security_scan.json

--ruleset=security-high 加载预置的高危规则集（SQL 注入、硬编码密钥、不安全反序列化）， --threshold=0.8 表示置信度低于 80% 的告警直接过滤。这比单纯 grep 密钥字符串准得多——它能识别 os.environ.get("DB_PASSWORD") 这种动态获取方式。

3.4 技能编排： code skill run / code skill list

skills 是 Claude Code CLI 的隐藏王牌。它不是 AI 功能，而是 可编程的自动化工作流 。例如，我们有个 pr-review 技能：

# ~/.claude/skills/pr-review.yaml
name: pr-review
description: Full PR analysis: diff summary, risk assessment, test coverage check
steps:
  - name: parse-diff
    command: "git diff HEAD~1 --name-only | head -20"
  - name: summarize-changes
    command: "claude code explain --input '{{ steps.parse-diff.output }}' --format=brief"
  - name: assess-risk
    command: "claude code scan --path . --ruleset=risk-critical --files='{{ steps.parse-diff.output }}'"

执行 claude code skill run --name pr-review ，它自动：

1. 获取最近一次 commit 修改的文件列表（最多 20 个）
2. 让 Claude 用一句话概括这些文件的变更意图
3. 对这些文件执行高危规则扫描

整个过程无需人工干预，结果汇总成结构化 JSON。这才是“CLI”的终极形态：把人的判断逻辑，编码成可复现、可审计、可集成的指令序列。

4. 实战手册：从飞书告警到 PR 合并的 7 分钟终端闭环

现在，让我们把所有命令串成一条真实流水线。场景：凌晨 3:17，飞书机器人推送一条告警：“订单服务 CPU 使用率持续 5 分钟 > 95%”。你正在床上摸手机，但决定不打开电脑，直接 SSH 进跳板机处理。

4.1 第一步：定位热点文件（< 30 秒）

# 查看最近 1 小时最耗 CPU 的 Python 进程
ps aux --sort=-%cpu | grep "python.*order" | head -5
# 输出：... /opt/order-service/venv/bin/python /opt/order-service/src/main.py ...

# 进入服务目录，用系统工具快速采样
cd /opt/order-service
py-spy record -o profile.svg --pid $(pgrep -f "main.py") --duration 30
# 生成火焰图，但终端里看不到 SVG，所以立刻转文本
py-spy top --pid $(pgrep -f "main.py")
# 输出关键行：92% time in src/payment/processor.py:process_payment:42

结论： src/payment/processor.py 第 42 行是罪魁祸首。

4.2 第二步：深度分析可疑代码（< 90 秒）

# 提取第 40-45 行，喂给 Claude 解读
sed -n '40,45p' src/payment/processor.py > /tmp/hotspot.py
claude code explain \
  --file /tmp/hotspot.py \
  --context-file src/payment/__init__.py \
  --output-format=markdown \
  --detail-level=high > /tmp/explain.md

/tmp/explain.md 显示：第 42 行 for item in order.items: 在处理超大订单（>1000 items）时，触发了未优化的嵌套循环，且每次迭代都调用外部 HTTP 接口（ validate_item(item) ），形成 N+1 查询。

4.3 第三步：生成修复方案并验证（< 2 分钟）

# 让 Claude 基于上下文生成修复补丁
claude code fix \
  --file src/payment/processor.py \
  --context-file src/payment/__init__.py \
  --rule="batch-http-calls" \
  --output-format=diff \
  --dry-run > /tmp/fix.patch

# 查看补丁内容（确认没动错地方）
cat /tmp/fix.patch
# 输出：@@ -40,5 +40,8 @@ def process_payment(order):
#         # BEFORE: for item in order.items: validate_item(item)
#         # AFTER:  item_ids = [i.id for i in order.items]; batch_validate_items(item_ids)

# 应用补丁（谨慎！先备份）
cp src/payment/processor.py src/payment/processor.py.bak
patch -p0 < /tmp/fix.patch

# 本地快速验证：用最小数据集跑通
python -c "
from src.payment.processor import process_payment
from unittest.mock import patch
with patch('src.payment.processor.validate_item') as mock:
    mock.return_value = True
    process_payment({'items': [{'id':1},{'id':2}]})
print('✅ Patch applied and basic test passed')
"

4.4 第四步：生成 PR 描述并提交（< 1 分钟）

# 自动生成符合团队规范的 PR 描述
claude code generate \
  --template=pr-description \
  --param=title="fix(payment): optimize item validation loop" \
  --param=issue_link="https://jira.example.com/browse/ORD-1234" \
  --param=impact="reduces CPU usage by ~70% on large orders" \
  --output-file=./PR_DESCRIPTION.md

# 提交代码
git add src/payment/processor.py
git commit -F ./PR_DESCRIPTION.md
git push origin hotfix/cpu-burst

# 最后，用技能一键触发代码审查
claude code skill run --name pr-review --param=branch=hotfix/cpu-burst

整个过程，从看到告警到代码推送到远端，严格计时 6 分钟 42 秒。没有打开浏览器，没有切换窗口，所有操作都在一个 SSH 会话里完成。这就是 CLI 的力量：它不创造新功能，而是把已有的能力，压缩进工程师最自然的操作节奏里。

关键经验： --dry-run 是生命线，但更要紧的是 --context-file 。我曾因漏掉一个 __init__.py ，让 Claude 把 from .utils import cache 误判为未定义模块，生成了错误的 import 修复。记住： CLI 的智能，上限由你提供的上下文决定，下限由你的 --dry-run 习惯保障。

5. 高阶技巧：绕过限制、定制规则、与现有工具链缝合

当基础命令用熟了，你会遇到三类“官方文档不提，但生产环境天天见”的问题：地域限制、规则不够用、和其他 CLI 工具打架。解决方案不在 GitHub Issues 里，而在你自己的 ~/.claude/ 目录中。

5.1 应对 “not available in your country” 的务实方案

网络热词里高频出现 note: claude code might not be available in your country ，这不是玄学，是 DNS 层面的区域路由。官方 CLI 默认请求 api.claude.ai ，但在某些网络环境下，该域名被解析到低效节点。解决方法不是找代理，而是强制指定 API 端点：

# 查看当前配置
claude config get api.base_url
# 默认输出：https://api.claude.ai

# 切换到亚太稳定节点（实测延迟降低 40%）
claude config set api.base_url https://api-ap-southeast-1.claude.ai

# 验证
claude ping
# 返回 region: ap-southeast-1 即生效

更彻底的方案是修改 ~/.claude/config.yaml ，添加：

api:
  base_url: https://api-ap-southeast-1.claude.ai
  timeout: 30
  retries: 3

注意： base_url 必须带协议和路径，不能只写域名。这是很多用户配置失败的原因。

5.2 扩展规则集：把团队规范变成机器可执行的 YAML

--rule 参数背后，是 ~/.claude/rules/ 下的 YAML 规则库。新建 ~/.claude/rules/no-mock-in-prod.yaml ：

id: no-mock-in-prod
name: "禁止在生产代码中使用 mock"
description: "mock.patch, unittest.mock 等仅允许在 tests/ 目录下使用"
severity: critical
pattern: |
  (import\s+unittest\.mock|from\s+unittest\.mock\s+import|mock\.patch)
scope: file
exclude_paths:
  - "**/tests/**"
  - "**/test_*.py"

然后执行 claude code scan --ruleset=no-mock-in-prod ，它就会扫描整个项目，精准揪出 src/utils/http_client.py 里那行 from unittest.mock import patch 。规则语法基于 Tree-sitter，支持复杂 AST 匹配，比正则强大百倍。

5.3 与 Playwright / Obsidian / Zentao CLI 的协同工作流

CLI 的终极价值，在于串联。例如，用 Playwright 自动化测试后，把截图和日志喂给 Claude 分析：

# Playwright 生成报告
npx playwright test --reporter=line,json --output=./playwright-report

# 提取失败用例的截图路径和错误堆栈
jq -r '.projects[].suites[].specs[].results[].attachments[] | select(.name=="screenshot") | .path' ./playwright-report/report.json > /tmp/screenshots.txt

# 让 Claude 分析截图中的 UI 异常（需 OCR 支持，此处简化为日志分析）
claude code explain \
  --file ./playwright-report/report.json \
  --context-file /tmp/screenshots.txt \
  --prompt="Identify the most likely root cause of UI test failures from this report"

再比如，把 Zentao 的需求 ID 注入 Claude 工作流：

# 从 Zentao CLI 获取需求详情（假设已配置 zt-cli）
zt-cli story view 12345 --format=json > /tmp/story_12345.json

# 生成符合该需求的代码实现方案
claude code generate \
  --template=feature-impl \
  --param=requirement_json=/tmp/story_12345.json \
  --output-dir=./src/features/

Obsidian 的双向链接也能接入： claude code skill run --name obsidian-link --param=note_id=20240528-log ，自动生成该笔记关联的代码变更建议。

最后分享一个小技巧：在 ~/.zshrc 或 ~/.bashrc 中添加别名，把高频命令缩写：

alias ccr='claude code review --level=strict'
alias cce='claude code explain --output-format=markdown'
alias ccf='claude code fix --dry-run'

敲 ccr -f main.py 比 claude code review --level=strict --file main.py 少按 17 个键。一年下来，省下的手指运动量，够绕地球半圈。