importzhh

上手篇：安装配置与每一项功能

Claude Code; 教程; 上手 4265 字 22 min read

上一篇讲清楚了”为什么需要 Agent Harness”。这一篇回到地面：怎么装、怎么用、怎么用透。Claude Code 的功能列表很长，但我想强调一句——你只要会安装、启动、对话就足够开始用了，其余都是附加功能。这一篇的价值不在于罗列功能，而在于告诉你每个功能在什么场景下值得用、常见反模式是什么。

一、环境准备（Windows 视角）

Claude Code 与 Codex 是同类工具，只是厂家和默认模型不同（Claude vs GPT），用法几乎一样，可以二选一。下面以 Claude Code 为准。

升级 PowerShell。Win10 默认是 5.x，建议升到 7.x（操作体验差距很大，新版本启动命令是 pwsh，与 5.x 独立共存）。

$PSVersionTable                                        # 查看当前版本
winget install --id Microsoft.PowerShell --source winget  # 安装 PowerShell 7.x
set-ExecutionPolicy RemoteSigned                       # 允许脚本执行

装 Windows Terminal（Win11 自带多窗口，Win10 需手动）。装完把默认配置切成新版 PowerShell。

winget install --id=Microsoft.WindowsTerminal -e

装 Node.js。很多安装命令和环境运行都依赖它，属于必装系统依赖。官网下 Windows 安装包（msi），安装包会自动加环境变量，装完即可用 node / npm / npx。

装 Python（可选但推荐）。许多 Skill 用 Python 编写，想让 AI 有强大能力就得有 Python 环境。装时记得勾选”添加 Path”。

装 Claude Code 本体：

irm https://claude.ai/install.ps1 | iex   # 安装
claude                                      # 进入交互模式

首次启动会让你选登录方式：官方账号登录（网页跳转，容易封号）、API-KEY（贵，不建议）、或第三方中转站（改 ~/.claude/settings.json 里的 env 跳过登录）。

CC Switch（推荐辅助工具）：开源的配置切换工具，支持 Claude Code / Codex 自由切换官方登录或第三方中转，界面化管理 MCP / Skill / API 配置，支持多端同步。GitHub 仓库。

提示：涉及访问官方 API 的命令都需要代理。会话级临时代理用 $env:https_proxy="http://127.0.0.1:7890"，不建议永久化。

二、四种运行方式

无论 Claude Code 还是 Codex 都支持四种形态，大家用得最多的是终端 CLI：

方式优势劣势
终端 CLI完整功能、无界面消耗、可多开并发纯命令行
桌面端有界面显示额外 CPU/内存开销，多开对性能要求高
插件版保留现有 IDE 习惯削弱 AI 存在感、增加人工干预，对 Vibe Coding 是负担
网页版任意设备操作，可随时随地指挥 AI 干活无法操作本机环境，只能改外网可访问的仓库

一个实用经验：网页版做任务规划（Plan 模式），规划好再拉到本地实操——会话可以同步到本地。这就把”随时随地”和”能动手改本机”两者结合了起来。

三、基础交互：六个动作

进入 claude 后，掌握这六个动作就够日常用了：

  • 自然对话：直接输入自然语言让 AI 干活。
  • 复制粘贴：粘贴长文本会显示 [Pasted text #1 +14 lines] 折叠，避免干扰交互。
  • 提供文件：输入 @ 弹出当前目录文件列表，可多选。
  • 提供图片：复制图片后粘贴，显示 [Image #2]，↑ 键选中后 Del 可删除。
  • 终端命令：按 ! 前缀直接执行终端命令（claude 不介入），比如 !ls 看目录。
  • 管道输入：命令 | claude 把命令结果直接喂给 claude。例如 git diff | claude -p "审查这些改动"，省 token。

四、CLAUDE.md：最高 ROI 的一个文件

在代码库里高效使用 Claude Code，最重要的文件就是根目录下的 CLAUDE.md。它是 Agent 的行为准则，是了解这个仓库运作方式的首要依据。作用域分两种：全局（C:\Users\<用户>\.claude\CLAUDE.md）和项目（项目目录下的 CLAUDE.md），首次用 /init 初始化。

随着时间推移，会形成一套有主见的写作哲学：

1. 先设限制，而不是写指南。 从小处着手，根据 Claude 常犯的错误逐步记录。不要一上来就写百科全书。

2. 别在 CLAUDE.md 里到处 @ 引用文档。 在别处已有大量文档时，很容易想在 CLAUDE.md 里 @ 这些文件。这会在每次运行时把整份文件塞进上下文窗口，导致臃肿。但如果你只在文中提到路径，Claude 通常会忽略它。正确做法是向 Agent 推销**“为什么”和”什么时候”**需要读这份文件：

遇到复杂用法或碰到 FooBarError 时，请参见 path/to/docs.md 获取最佳问题排查步骤。

3. 不要只说”禁止”。 避免纯粹的负面约束，例如”绝对不要使用 --foo-bar 标志”。当 Agent 认为它必须使用该标志时，就会左右脑互搏卡住。永远要提供可行的替代方案。

4. 把 CLAUDE.md 当成强制性手段。 如果你的 CLI 命令复杂又冗长，与其写长篇大论解释它们，不如写一个简单的 bash 包装器，提供清晰直观的 API，然后记录这个包装器。保持 CLAUDE.md 尽可能短，是迫使你精简代码库和内部工具的绝佳手段。

一句话：把 CLAUDE.md 当作一套高层次、精心策划的护栏和指引，用它来指导你在哪里需要投入更多精力打造对 AI（和人类）更友好的工具，而不是试图把它变成一本无所不包的百科全书。建议不超过 200 行，避免 token 浪费。维护时同步一份 AGENTS.md 以兼容其他 AI IDE。

五、上下文管理：不要相信自动压缩

在编码会话中至少运行一次 /context，了解你那 200k token 的上下文窗口是如何被使用的。一个全新会话在 monorepo 里的基线成本大约是 20k token（10%），剩下 180k 用于你的实际修改——很快就会被填满。

三个主要工作流程，按推荐度排序：

1. /clear + /catchup（简单重启，默认方式）。 用 /clear 清除状态，然后运行一个自定义的 /catchup 命令，让 Claude 读取当前 git 分支中所有已更改的文件。

2. “记录并清除”（复杂重启，用于大型任务）。 让 Claude 把它的计划和进展输出到一个 .md 文件，然后 /clear 清除上下文，接着通过读取那个 .md 文件来开始新会话继续工作。这相当于创建一份持久的外部”记忆”。

3. /compact（避免使用）。 自动压缩过程不透明、容易出错、优化得不好。能用前两种就别用这个。

一句话：不要相信自动压缩。对简单重启用 /clear，对复杂任务用”记录并清除”。

六、斜杠命令：保持精简

斜杠命令看作是常用提示的简单快捷方式，仅此而已。例如：

  • /catchup：读取当前 git 分支所有已更改文件。
  • /pr：清理代码、暂存改动、准备 PR。

自定义命令放在 .claude/commands/*.md，文件名即命令名，用 $ARGUMENTS 接收参数。

反模式：如果你有一长串复杂的自定义斜杠命令，你就制造了一个反模式。Agent 的全部意义在于你可以输入几乎任何想要的东西并得到可合并的结果。一旦你强迫工程师为了完成工作去学习一个需要查文档的魔法命令列表，你就失败了。把斜杠命令当简单、个人化的快捷方式，而不是用它替代构建更直观的 CLAUDE.md 和更好的工具化 Agent。

七、SubAgent：主-克隆 优于 主导-专家

理论上 SubAgent 是上下文管理最强大的功能：一个复杂任务需要 X token 输入、累积 Y token、产出 Z token 答案，跑 N 个就吃掉 (X+Y+Z)*N。SubAgent 把 (X+Y)*N 外包给专门 Agent，只返回最终 Z token，保持主窗口清爽。

但实践中它带来两个新问题：

  1. 把上下文”关起来”了。你创建一个 PythonTests SubAgent，就把所有测试相关的上下文从主 Agent 那里隐藏了。主 Agent 再也无法对变更做整体性思考，被迫调用 SubAgent 才能验证自己的代码。
  2. 强迫 Agent 遵循人类的工作流。你在指令它必须如何委派任务，而这正是希望 Agent 帮你解决的问题。

更推荐的替代方案是使用 Claude 内置的 Task(...) 功能生成通用代理的克隆体。把所有关键上下文放在 CLAUDE.md 里，让主 Agent 自己决定何时以及如何将工作委派给它的副本。这叫”主-克隆”模式——既享受 SubAgent 节省上下文的好处，又避免其缺点，Agent 动态管理自己的协作流程。

子代理放在 .claude/agents/ 目录，用 /agents 命令查看或创建。常用场景：

  • 角色设定：A 是开发角色（可编辑文件）、B 是复核角色（只读），主会话让 A 开发、B 复核。
  • 控制消耗：haiku 规划、sonnet 执行、opus 复核，三模型协作省 token。
  • 语言切换：多语言项目给不同语言建不同子代理，避免一次性描述所有规则撑爆上下文。

八、Hooks：提交时阻断，别在写入时阻断

Hooks 是用户定义的 shell 命令，在 Claude Code 生命周期特定点执行。它是确定性的**“必须做”规则，与 CLAUDE.md 中的”应该做”**建议互补。输入 /hooks 查看已有钩子，保存在 .claude/settings.json。

两种推荐用法：

1. 提交时阻断钩子（主要策略）。 一个 PreToolUse 钩子包裹所有 Bash(git commit)，检查一个 /tmp/agent-pre-commit-pass 文件——这个文件只有在所有测试通过时才会被测试脚本创建。如果文件不存在，钩子就阻止提交，迫使 Claude 进入”测试并修复”循环直到构建通过。

2. 提示钩子（非阻塞）。 Agent 在做次优操作时提供”即发即忘”式反馈。

刻意不用的：写入时阻断（在 Edit/Write 操作上阻断）。在 Agent 执行计划中途阻断它，会使它困惑甚至”沮丧”。更有效的方法是让它完成工作，在提交阶段检查最终完整结果。

九、Plan 模式：复杂变更必备

对于任何”大型”功能变更，规划都是必不可少的。进入会话后按 Shift+Tab 进入 Plan 模式（再按返回普通模式），此时 AI 不会做任何修改，只与你对话给出执行方案并生成 plan.md。确认可行后返回普通模式让 AI 按计划执行。

Plan 模式的价值是在 Agent 开始工作前与它对齐——既定义了如何构建，也定义了它需要停下来向你展示工作的”检查点”。经常使用能培养一种直觉：需要提供多少最少的上下文才能得到一个好计划，而不让 Claude 在实现阶段搞砸。

一句话：对于复杂变更，总是先用 Plan 模式在 Agent 开始工作前就计划达成一致。

十、Skills 与 MCP 的取舍

Skills 是正确的抽象（同意 Simon Willison 的判断：“Skills 也许比 MCP 更重要”）。Agent 自主性的心智模型可以分三阶段演进：

  1. 单次提示：一个巨大提示给所有上下文（脆弱、无法扩展）。
  2. 工具调用：经典 Agent 模型，手动制作工具为 Agent 抽象现实（更好，但创造新抽象和上下文瓶颈）。
  3. 脚本化：给 Agent 访问原始环境的权限——二进制、脚本、文档——它动态地编写代码与之交互。

Agent Skills 显然是下一个重要功能，它是”脚本化”这一层的正式产品化。SKILL.md 文件只是一个更有组织、可共享、可发现的方式来记录这些 CLI 和脚本，并暴露给智能体。Skills 放在 .claude/skills/，每个文件夹是一个技能，AI 会根据场景自动识别使用。

Skills 不意味着 MCP 已死，但 MCP 的角色要变。以前许多人构建了糟糕的、上下文沉重的 MCP，几十个工具只是简单镜像 REST API（read_thing_a()、read_thing_b()、update_thing_c()）。

正确的 MCP 不应是臃肿的 API，而是简单、安全的网关，提供几个强大的高层次工具：

  • download_raw_data(filters…)
  • take_sensitive_gated_action(args…)
  • execute_code_in_environment_with_state(code…)

MCP 的工作不是为智能体抽象现实，而是管理认证、网络和安全边界，然后让开。它提供入口点，智能体利用脚本能力和 markdown 上下文完成实际工作。一个经验法则：无状态工具（Jira、AWS、GitHub）迁移到简单 CLI；有状态复杂环境（Playwright 控制浏览器）才用 MCP。

十一、恢复、SDK 与 GitHub Action

会话恢复。claude --continue（简写 -c）继续上一次会话；claude --resume（简写 -r）展示会话列表选择进入。所有会话历史存在 ~/.claude/projects/，可以对日志做元分析，寻找常见异常、权限请求和错误模式来改进面向 Agent 的上下文。我常常 --resume 一个几天前的会话，只为问 Agent 它当时如何克服某个特定错误，然后用这些信息改进 CLAUDE.md。

Claude Agent SDK。Claude Code 不只是交互式 CLI，也是强大的 SDK（现为 Claude Agent SDK），可用来构建新 Agent——编码或非编码任务。三个主要用法：大规模并行脚本（claude -p "in /pathA change all refs from foo to bar" 并行跑比让主 Agent 管理几十个子任务更可控）、构建内部聊天工具、快速 Agent 原型设计。对大多数新个人项目，它已经值得作为默认 Agent 框架，而不是 LangChain/CrewAI。

GitHub Action（最被低估的功能）。在 GHA 中运行 Claude Code，与 Cursor Background Agent 或 Codex 托管 Web UI 类似但可定制性强得多——你控制整个容器和环境，沙盒和审计控制比任何其他产品都强，且支持 Hooks 和 MCP。可以构建”随处可发 PR”的工具：用户从 Slack、Jira、甚至 CloudWatch 告警触发一个 PR，GHA 修复 bug 或添加功能并返回完整测试过的 PR。由于 GHA 日志就是完整 Agent 日志，可以定期审查这些日志寻找常见错误，形成数据驱动的飞轮：Bugs → 改进的 CLAUDE.md / CLIs → 更好的 Agent。

十二、settings.json 值得知道的环境变量

  • HTTPS_PROXY / HTTP_PROXY：调试时检查 Claude 实际发送了什么 Prompt；对 Background Agent 是细粒度网络沙盒工具。
  • MCP_TOOL_TIMEOUT / BASH_MAX_TIMEOUT_MS：调高，默认超时通常过于保守。
  • ANTHROPIC_API_KEY：企业密钥把”按席位付费”转为”按使用量付费”。
  • permissions.allow / deny：预授权已知安全的命令（Bash(ls:*)、WebFetch）减少确认；把 rm -rf 加黑名单避免删库。定期自我审计这个列表。

十三、功能速查表

按场景分类，方便回头查：

场景功能要点
项目初始化/init生成 CLAUDE.md
加上下文@文件提及文件加入上下文
跑命令!命令前缀直接执行 bash，AI 不介入
回退双 Esc回退到之前的消息
反向搜索Ctrl+R搜索历史输入
看上下文占用/contextToken X 光透视
看用量/stats、/usage使用仪表盘
深思考Ultrathink触发扩展思考
大变更前Plan 模式（Shift+Tab）先想后做
长任务YOLO（--dangerously-skip-permissions）绕过权限，配 Docker 用
恢复会话claude -c / -r继续/选择历史会话
无头模式claude -p "..."不进交互，管道+JSON 输出
导出记录/export获取对话记录
Vim 党Vim 模式设置里开启
自定义状态栏/statusline自定义底部视图
远程会话claude --remote / --teleport跨端同步

不要一开始就去学所有功能——点到为止即可。等你用得多了、觉得想提效时再回头来看，你会很快明白其使用场景。如果那时还不明白，说明你用不到，忽略它继续对话即可。

十四、Claude Code 还是 Codex？

一个实战体感参考：GPT 通用理解能力强于 Claude，它总能按照你设想的方式运行或回答问题；Claude 在代码具体实现上强于 GPT，总能写出完好可用的代码，但有时候它做的事情不是你原本想要的。简单说——Claude 写的代码更好，但有时候跑偏；Codex 更听话，但代码略逊。两者都值得装，按任务性质切换。

下一篇「配置篇」会钻进 Claude Code 的内部机制：六层配置优先级链、四阶段权限管线、26 个生命周期事件的钩子系统——把”能用”升级到”能改透”。

主要参考