Claude Code 从入门到精通（2）：安装、Agentic Loop 与 Harness

Raymond Carver

147人浏览 · 2026-06-27 22:26:11

Raymond Carver · 2026-06-27 22:26:11 发布

本文假设读者具备基本的终端和 Git 使用经验。内容更新于 2026 年 6 月，安装方式和产品能力可能继续变化，请以官方文档为准。

上一篇文章梳理了主流 AI 编程工具，这一篇开始进入 Claude Code 本身。

我最初理解 Claude Code 时，最容易混淆的是两个问题：

它与网页对话中的 Claude 到底有什么不同？
一个语言模型为什么能够读取项目、运行命令并持续完成任务？

答案不只在模型里。模型负责理解和推理，Claude Code 则在模型外提供上下文管理、工具、权限、执行环境和任务循环。Anthropic 官方将这层工程系统称为 agentic harness。[2]

如果只记住一句话，可以记成：

Claude Code = Claude 模型 + Agentic Loop + 上下文 + 工具 + 权限与执行环境。

一、安装 Claude Code

1. 系统要求

Claude Code 当前支持 macOS、Windows 和主流 Linux 发行版。最低要求如下：[1]

项目	要求
macOS	macOS 13.0 或更高版本
Windows	Windows 10 1809+ 或 Windows Server 2019+
Linux	Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+
硬件	4 GB 以上内存，x64 或 ARM64 处理器
Shell	Bash、Zsh、PowerShell 或 CMD
网络	登录和模型调用需要网络连接

这里有一个容易过时的结论：安装 Claude Code 并不一定需要 Node.js。 官方当前推荐原生安装器；只有选择 npm 安装时，才需要 Node.js 18 或更高版本。[1]

2. 推荐方式：原生安装器

macOS、Linux 和 WSL：

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

Windows PowerShell：

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

Windows CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

原生安装器的优势是依赖少，并且默认在后台更新。没有统一使用 npm 管理命令行工具的需求时，我更倾向这种方式。

3. 其他安装方式

macOS 可以使用 Homebrew：

brew install --cask claude-code

Windows 可以使用 WinGet：

winget install Anthropic.ClaudeCode

如果已经有 Node.js 环境，也可以继续使用 npm：

npm install -g @anthropic-ai/claude-code

npm 包目前安装的也是平台对应的原生二进制文件，实际运行 claude 时不会再调用 Node.js。不过 npm 安装本身仍然要求 Node.js 18+，并且不应使用 sudo npm install -g。[1]

不同安装方式的更新命令也不同：

安装方式	更新方式
原生安装器	默认后台自动更新
Homebrew	`brew upgrade claude-code`
WinGet	`winget upgrade Anthropic.ClaudeCode`
npm	`npm install -g @anthropic-ai/claude-code@latest`

4. Windows 原生环境还是 WSL

Claude Code 可以直接运行在 Windows，也可以运行在 WSL 中。选择标准主要取决于项目实际使用的工具链：[1]

环境	更适合的情况	需要注意
Windows 原生	.NET、PowerShell 或其他 Windows 工具链	推荐安装 Git for Windows；当前不支持 Claude Code 沙箱
WSL 2	Linux 工具链、容器和后端项目	支持沙箱；项目和命令应放在 WSL 环境中运行
WSL 1	无法使用 WSL 2 时的兼容方案	不支持沙箱

Git for Windows 在原生 Windows 中是推荐项，而不是硬性前置。如果未安装，Claude Code 会改用 PowerShell 执行命令。

5. 验证、诊断和登录

安装后先检查版本：

claude --version

需要更完整的环境诊断时运行：

claude doctor

然后进入一个项目目录并启动：

cd path/to/your-project
claude

首次启动会进入登录流程。Claude Code 可以使用 Claude 订阅或 Console 账户，也支持通过 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 等平台接入。[1]

二、Claude Code 不只是“终端里的聊天框”

Claude Code 是一个编程 Agent。终端只是它最经典的入口，底层能力也可以出现在 IDE、Desktop、Web、CI/CD 等环境中。[8]

它与普通对话模式的核心差异，不是界面，而是是否拥有真实的项目上下文和行动工具。

维度	普通对话模式	Claude Code 的 Agent 模式
上下文来源	主要依赖用户输入和附件	可以按需读取工作目录、Git 状态和项目说明
输出方式	以解释、文本和代码片段为主	可以直接修改文件、运行命令和执行测试
任务单位	一个问题或一次回答	一个需要多步推进和验证的目标
执行位置	对话产品提供的环境	本机、Anthropic 云端 VM 或远程控制的本机
用户控制	通过后续对话修正	还可以通过权限、diff、测试和中断控制过程

Claude Code 能做的事情包括：

搜索并理解项目结构；
跨文件修改代码；
运行构建、测试、Lint 和 Git 命令；
读取 CLAUDE.md 和项目记忆；
通过 MCP 访问数据库、文档或工单系统；
把独立任务交给 subagent；
在用户允许的边界内持续迭代。

需要注意，Agent 的“自主”不是无限权限。它能访问哪些目录、可以执行哪些工具、命令是否需要确认，都受权限配置和沙箱边界约束。[5]

三、Claude Code 的运行核心：Agentic Loop

早期对话式 AI 的典型流程是：

用户提问 → 模型回答 → 本轮结束

Claude Code 面向的则是多步任务。官方把其 Agentic Loop 概括为三个不断交织的阶段：收集上下文、采取行动、验证结果。[2]

flowchart LR
    A["用户目标"] --> B["收集上下文"]
    B --> C["模型判断下一步"]
    C --> D{"需要调用工具？"}
    D -- "是" --> E["权限检查并执行工具"]
    E --> F["读取工具结果"]
    F --> G["验证当前结果"]
    G -- "仍未完成" --> B
    G -- "已完成或需要用户决定" --> H["返回结果 / 请求反馈"]
    D -- "否" --> H

以“修复登录接口的空指针错误”为例，Claude Code 可能依次执行：

查看项目说明和 Git 状态；
搜索登录接口和错误类型；
读取调用链上的关键文件；
修改实现并补充测试；
运行相关测试；
根据失败信息继续修改；
汇总改动和验证结果。

这里最关键的一点是：模型本身并不直接运行 shell 命令。

模型会生成一次工具调用请求，例如读取文件或执行测试；Harness 检查权限后调用对应工具，再把输出放回上下文。模型根据新结果继续判断，直到任务完成、遇到阻塞，或需要用户做决定。

用户也始终在循环中。我们可以随时中断、补充信息、修改方向或拒绝操作。因此，与其说“主动权完全交给 AI”，更准确的说法是：用户从逐步操作转向设定目标、控制边界和验收结果。

四、什么是 Harness

Harness 原意是“挽具”或“控制装置”。放在 Agent 系统里，它不是某一个具体功能，而是包裹在语言模型外部的一整套运行系统：负责组织上下文、暴露工具、执行工具调用、检查权限、保存会话，并把执行结果重新送回模型。

Anthropic 官方对 Claude Code 的描述很直接：模型负责推理，工具负责行动，而 Claude Code 作为 Agentic Harness 提供工具、上下文管理和执行环境。[2] 因此，一个编程 Agent 的能力不能只看模型：

Agent 能力 ≈ 模型能力 × Harness 的上下文质量 × 工具与验证闭环。

乘法的意思是，只要其中一项明显不足，整体表现就会迅速下降。模型再强，如果拿到错误文件、无法运行测试，或者工具输出无法反馈回来，也很难稳定完成工程任务。

1. 模型与 Harness 的边界

模型和 Harness 经常被混为一谈，但二者承担的职责不同。

模型负责	Harness 负责
理解自然语言目标	组装系统指令、项目规则和会话历史
根据当前上下文推理	决定哪些工具及其 schema 对模型可见
生成回答或结构化工具调用	校验参数、检查权限并执行工具
根据工具结果判断下一步	把 stdout、错误、diff 等结果送回模型
判断任务是否可以结束	管理会话、压缩、恢复、回退和中断

模型不会直接打开文件，也不会直接在操作系统里执行 git。它输出的是“希望调用哪个工具、传入什么参数”这样的结构化请求。真正接触文件系统、终端和网络的是 Harness 管理的工具运行时。

这也解释了为什么同一个模型放在不同编程工具中，表现可能差异明显：模型相同，不代表上下文选择、工具设计、权限策略和验证方式相同。

2. 一次工具调用是怎样完成的

从用户输入一个任务，到 Claude Code 返回结果，中间大致会经过下面的消息管线：

Agent SDK 的官方说明把这个过程描述为：接收 prompt，模型判断，调用工具，接收结果，再重复执行，直到返回最终结果。[9] 这里有几个值得注意的细节：

工具失败也属于有效反馈。 命令退出码、测试错误和权限拒绝都会回到上下文，模型可以据此改换方案。
一次用户请求可能包含多个模型 turn。 每次工具调用及其结果都会推动下一轮，而不是重新开始一场无关对话。
互不依赖的工具可能并行执行。 是否并行取决于模型给出的调用关系和 Harness 的执行策略。[9]
终止条件不只有“成功”。 用户中断、权限拒绝、达到预算或轮次限制、环境故障，都可能结束循环。
LLM Loop 是 Agent 的运行逻辑：模型根据目标、当前上下文和工具返回结果，不断决定下一步是读文件、改代码、运行命令，还是重新分析。
Harness 是支撑这个循环的外部执行框架：它提供文件系统、终端、工具接口、权限控制、沙箱环境、日志记录和测试验证。

3. 我对完整系统的七部分拆解

下面的“七部分”是为了理解系统所做的工程归纳，不是 Anthropic 官方定义的固定七层架构。

部分	代表组件	核心职责	典型失败表现
① 模型	Claude Sonnet、Claude Opus	理解代码、推理和选择下一步	误解需求、生成错误方案
② Loop 控制器	收集上下文、行动、验证	驱动多轮工具调用并判断是否继续	过早结束、无效重复
③ 上下文系统	会话、`CLAUDE.md`、Auto Memory、压缩	维护当前工作的有效信息集	规则遗漏、上下文污染
④ 工具运行时	Read、Edit、Glob、Grep、Bash、Web、LSP	把推理转换成可观察的操作	参数错误、命令失败、输出过大
⑤ 安全边界	permissions、sandbox、PreToolUse Hooks	控制文件、命令和网络的影响范围	误放行或过度阻断
⑥ 扩展系统	Skills、Hooks、MCP、Plugins	增加领域知识、外部连接和自动化	扩展冲突、上下文膨胀、连接失效
⑦ 会话与委派	Subagents、Agent Teams、worktree、resume	隔离上下文、并行任务和恢复进度	委派信息不足、合并冲突

严格来说，模型不是 Harness 的组成部分；Harness 是第 ②～⑦ 部分围绕模型形成的系统。把模型列进表格，是为了强调：模型决定推理能力的上限，Harness 决定模型看到什么、能做什么，以及结果能否被验证。

4. 上下文系统：维护工作集，而不是塞入整个仓库

上下文窗口可以理解为模型当前的“工作内存”。Harness 的重要职责不是尽可能多地装入内容，而是让与当前决策相关的信息及时出现。

Claude Code 的上下文大致分为四类：[3][6][10]

类型	何时进入上下文	示例
启动时加载	会话启动	系统指令、项目根目录 `CLAUDE.md`、Auto Memory、Skill 描述、MCP 工具名
交互中累积	每轮对话和工具执行后	用户消息、模型回答、文件内容、命令输出、diff
按需加载	任务触发时	Skill 正文、嵌套 `CLAUDE.md`、路径规则、MCP 工具 schema
隔离加载	创建 subagent 时	委派任务、指定 Skills、独立读取的文件和输出

这套分层加载解决的是两个矛盾：

模型需要足够的上下文才能做出正确判断；
上下文过多又会增加成本、淹没重点，并降低工具选择质量。

因此，CLAUDE.md 适合放每次都需要的短规则，Skills 适合放按需方法，MCP 只在需要时加载完整工具 schema。当前 Claude Code 还会延迟加载 MCP 工具定义：启动时只保留工具名称，真正使用时再发现并加载 schema。[11]

当上下文接近上限时，Harness 会清理旧工具输出并压缩会话。压缩不是“无损扩容”：项目根 CLAUDE.md 和 Auto Memory 会重新注入，但路径规则、嵌套说明和较早的细节可能需要重新读取。[10] 所以，稳定规则不能只在很早的一句对话里说一次。

5. 工具运行时：把推理变成可检查的动作

工具是模型与真实环境之间的接口。一个设计良好的工具至少需要满足三点：

输入结构明确：模型知道参数名称、类型和约束；
输出可观察：返回结果、错误、退出码或修改内容；
影响范围可控制：权限系统能够识别和限制它。

Claude Code 的内置工具覆盖文件读取、编辑、搜索、命令执行和 Web 操作；LSP 提供定义、引用和诊断等代码智能；MCP 则把数据库、文档、浏览器或工单系统暴露成额外工具。[3][4]

工具越多不一定越强。大量工具定义会占用上下文，也会增加模型选错工具的概率。MCP Tool Search 采用按需发现机制，本质上是在工具丰富度和上下文噪声之间做平衡。[11]

对工程任务而言，最重要的工具往往不是“写文件”，而是“验证结果”：测试、类型检查、Lint、构建和浏览器检查让 Agent 能够根据证据继续循环。没有验证工具的 Harness，只是把一次性代码生成包装成了自动写文件。

6. 安全层：权限、沙箱和 Hooks 不是一回事

Claude Code 的安全控制至少包含三个层次：

机制	作用位置	主要作用
Permissions	工具调用层	用 allow / ask / deny 决定工具、路径或域名是否可访问
Sandbox	操作系统层	限制 Bash 及其子进程可以访问的文件系统和网络范围
PreToolUse Hooks	工具调用前	根据组织规则或命令内容执行确定性检查与拦截

Permissions 控制“Claude Code 是否应尝试这次调用”，Sandbox 控制“进程即使尝试了，操作系统是否允许”。二者是互补关系：仅禁止 Read 工具访问某文件，并不能自动阻止任意 Bash 子进程读取它；需要 OS 级强制边界时，应使用沙箱。[5]

Hooks 则适合表达更具体的工程政策，例如禁止改动生成目录、在写入后运行格式化、记录审计日志。PreToolUse Hook 可以在权限提示前阻断调用，但它不是模型建议，而是一段确定执行的规则。[5] 这类确定性机制尤其适合处理“绝对不能发生”的约束。

权限系统解决的是影响范围，不是代码正确性。一次命令被允许执行，只代表它符合当前安全策略，并不代表它的技术方案正确。因此，安全控制之后仍然需要测试、diff 审阅和回退机制。

7. 扩展系统：在 Loop 的不同位置插入能力

Skills、Hooks、MCP 和 Plugins 经常一起出现，但它们并不处在同一层：

组件	插入点	上下文成本	更适合解决
`CLAUDE.md`	会话启动	每轮持续占用	项目级长期规则
Skills	模型需要方法时	描述常驻，正文按需加载	可复用知识和工作流
MCP	工具选择阶段	工具名启动加载，schema 按需加载	外部数据和操作能力
Hooks	生命周期事件	默认不占上下文	格式化、审计、拦截和通知
Plugins	安装与分发层	取决于内部组件	打包共享 Skills、Hooks、Agents、MCP 和 LSP
LSP	工具运行时	调用时产生结果	代码导航和静态诊断

所以，Plugin 更像“分发容器”，不是新的推理机制；MCP 提供连接，Skill 教模型如何正确使用连接；Hook 负责确定性触发，不能替代需要语义判断的 Agent Loop。[3][13]

扩展越多，维护成本也越高。规则可能冲突，Skill 描述可能重叠，MCP 连接可能在会话中断开，工具输出也可能挤占上下文。Harness 的成熟度不只体现在“能接多少插件”，也体现在能否看见加载状态、诊断失败并控制上下文成本。

8. Subagent：隔离上下文，而不只是增加并发

Subagent 最有价值的能力不是“多开一个 Claude”，而是创建独立上下文。它不会自动继承主会话的完整历史、已经读取的文件或调用过的 Skills；主 Agent 需要通过委派消息明确传递目标、范围和交付格式。完成后，通常只有摘要和少量元数据回到主会话。[3][12]

这带来两个好处：

大量搜索和日志不会污染主会话；
可以给不同任务配置不同工具、模型、权限和 Skills。

代价是上下文隔离也会造成信息损失。如果委派只写“检查一下这个模块”，subagent 可能缺少验收标准和关键背景。好的委派应该像一张完整的 Issue：说明目标、边界、相关路径、禁止事项和期望输出。

Agent Teams 更偏向多个独立会话之间的并行协作；worktree 解决的是文件系统和 Git 分支隔离。它们与 subagent 的上下文隔离相关，但解决的问题并不完全相同。

9. 怎样判断一个 Harness 是否成熟

在我看来，可以从五个问题判断：

上下文是否准确？ 能否找到真正相关的文件，并让长期规则在需要时持续生效。
动作是否可观察？ 每次工具调用、文件修改和验证结果是否可以审阅。
失败是否可恢复？ 命令报错、上下文压缩或工具断线后，能否调整、重试或回退。
权限是否分层？ 是否同时具备模型侧规则、确定性 Hooks 和 OS 级沙箱。
结果是否可验证？ 是否能运行测试、构建和静态检查，而不是只相信模型的完成声明。

Harness 不能消除模型幻觉，也不会自动把模糊需求变成正确实现。它真正提供的是一个受约束、可观察、可反馈的执行闭环。理解这一点后，Claude Code 的很多设计就更容易解释：CLAUDE.md 在管理输入，Tools 在提供行动，Permissions 在限制影响，Hooks 在加入确定性规则，subagent 在隔离工作集，而测试负责给 Loop 提供可以相信的反馈。

五、Claude Code 如何“读懂”代码库

Claude Code 的内置工作方式不是先把整个仓库建立成向量索引，而是围绕当前任务按需探索。本文把这种方式简称为 Agentic Search：模型根据已获得的信息决定下一次应该搜索、读取还是跟进引用。

其中，Glob 用于按文件名模式查找文件，Grep 基于 ripgrep 搜索文件内容；配置 LSP 后，还可以获得定义跳转、引用查找和诊断信息。[4]

这种按需探索与预建语义索引各有特点：

维度	预建语义索引 / RAG	Claude Code 的按需探索
准备过程	先切分、嵌入并维护索引	可以直接从当前工作目录开始
查找依据	语义相似度	文件名、精确文本、代码关系和模型推理
代码变化	依赖索引刷新策略	下一次读取直接看到当前工作树
主要成本	建索引、存储和同步	多轮搜索、工具调用和上下文消耗
更擅长	大范围模糊语义召回	围绕明确任务追踪实时代码