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

本文假设读者具备基本的终端和 Git 使用经验。内容更新于 2026 年 6 月安装方式和产品能力可能继续变化请以官方文档为准。上一篇文章梳理了主流 AI 编程工具这一篇开始进入 Claude Code 本身。我最初理解 Claude Code 时最容易混淆的是两个问题它与网页对话中的 Claude 到底有什么不同一个语言模型为什么能够读取项目、运行命令并持续完成任务答案不只在模型里。模型负责理解和推理Claude Code 则在模型外提供上下文管理、工具、权限、执行环境和任务循环。Anthropic 官方将这层工程系统称为agentic harness。[2]如果只记住一句话可以记成Claude Code Claude 模型 Agentic Loop 上下文 工具 权限与执行环境。一、安装 Claude Code1. 系统要求Claude Code 当前支持 macOS、Windows 和主流 Linux 发行版。最低要求如下[1]项目要求macOSmacOS 13.0 或更高版本WindowsWindows 10 1809 或 Windows Server 2019LinuxUbuntu 20.04、Debian 10、Alpine Linux 3.19硬件4 GB 以上内存x64 或 ARM64 处理器ShellBash、Zsh、PowerShell 或 CMD网络登录和模型调用需要网络连接这里有一个容易过时的结论安装 Claude Code 并不一定需要 Node.js。官方当前推荐原生安装器只有选择 npm 安装时才需要 Node.js 18 或更高版本。[1]2. 推荐方式原生安装器macOS、Linux 和 WSLcurl -fsSL https://claude.ai/install.sh | bashWindows PowerShellirm https://claude.ai/install.ps1 | iexWindows CMDcurl -fsSL https://claude.ai/install.cmd -o install.cmd install.cmd del install.cmd原生安装器的优势是依赖少并且默认在后台更新。没有统一使用 npm 管理命令行工具的需求时我更倾向这种方式。3. 其他安装方式macOS 可以使用 Homebrewbrew install --cask claude-codeWindows 可以使用 WinGetwinget install Anthropic.ClaudeCode如果已经有 Node.js 环境也可以继续使用 npmnpm install -g anthropic-ai/claude-codenpm 包目前安装的也是平台对应的原生二进制文件实际运行claude时不会再调用 Node.js。不过 npm 安装本身仍然要求 Node.js 18并且不应使用sudo npm install -g。[1]不同安装方式的更新命令也不同安装方式更新方式原生安装器默认后台自动更新Homebrewbrew upgrade claude-codeWinGetwinget upgrade Anthropic.ClaudeCodenpmnpm install -g anthropic-ai/claude-codelatest4. Windows 原生环境还是 WSLClaude Code 可以直接运行在 Windows也可以运行在 WSL 中。选择标准主要取决于项目实际使用的工具链[1]环境更适合的情况需要注意Windows 原生.NET、PowerShell 或其他 Windows 工具链推荐安装 Git for Windows当前不支持 Claude Code 沙箱WSL 2Linux 工具链、容器和后端项目支持沙箱项目和命令应放在 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”更准确的说法是用户从逐步操作转向设定目标、控制边界和验收结果。四、什么是 HarnessHarness 原意是“挽具”或“控制装置”。放在 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 则适合表达更具体的工程政策例如禁止改动生成目录、在写入后运行格式化、记录审计日志。PreToolUseHook 可以在权限提示前阻断调用但它不是模型建议而是一段确定执行的规则。[5] 这类确定性机制尤其适合处理“绝对不能发生”的约束。权限系统解决的是影响范围不是代码正确性。一次命令被允许执行只代表它符合当前安全策略并不代表它的技术方案正确。因此安全控制之后仍然需要测试、diff 审阅和回退机制。7. 扩展系统在 Loop 的不同位置插入能力Skills、Hooks、MCP 和 Plugins 经常一起出现但它们并不处在同一层组件插入点上下文成本更适合解决CLAUDE.md会话启动每轮持续占用项目级长期规则Skills模型需要方法时描述常驻正文按需加载可复用知识和工作流MCP工具选择阶段工具名启动加载schema 按需加载外部数据和操作能力Hooks生命周期事件默认不占上下文格式化、审计、拦截和通知Plugins安装与分发层取决于内部组件打包共享 Skills、Hooks、Agents、MCP 和 LSPLSP工具运行时调用时产生结果代码导航和静态诊断所以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]这种按需探索与预建语义索引各有特点维度预建语义索引 / RAGClaude Code 的按需探索准备过程先切分、嵌入并维护索引可以直接从当前工作目录开始查找依据语义相似度文件名、精确文本、代码关系和模型推理代码变化依赖索引刷新策略下一次读取直接看到当前工作树主要成本建索引、存储和同步多轮搜索、工具调用和上下文消耗更擅长大范围模糊语义召回围绕明确任务追踪实时代码两者不是互斥关系。大型知识库或跨仓库检索仍可能适合语义索引Claude Code 的优势在于可以根据任务结果动态调整下一步而不是只接收一次检索结果。还要区分“无需预先索引整个仓库”和“代码完全不会离开本机”。本地 Claude Code 的命令和文件操作在本机执行但为了调用模型用户提示、模型输出以及任务所需的上下文仍会通过网络发送到模型服务。具体训练和保留政策取决于账户类型、隐私设置和模型提供商。[7]六、一次任务如何流经整个系统把前面的概念放到一起可以用一个具体任务理解修复登录接口偶发返回 500 的问题不改变公开 API补充回归测试并运行认证模块测试。Claude Code 可能这样工作上下文系统加载CLAUDE.md、当前会话和项目记忆。Agentic Loop判断先收集信息而不是立即改代码。工具运行时通过 Glob、Grep、Read 和 Git 找到认证模块与最近改动。模型根据调用链提出修改方案。权限系统决定文件编辑和测试命令是否可以执行。工具运行时写入修改并运行测试。测试失败后结果重新进入上下文Loop继续下一轮。如果需要调查独立模块可以交给subagent主会话只接收结论。最终由用户审阅 diff、测试结果和行为是否符合验收标准。这也是我认为理解 Harness 比背命令更重要的原因。命令会随着版本变化但“模型如何获得上下文、调用工具、接收反馈并受安全边界约束”是使用编程 Agent 的稳定心智模型。参考资料Claude Code DocsAdvanced setupClaude Code DocsHow Claude Code worksClaude Code DocsExtend Claude CodeClaude Code DocsTools referenceClaude Code DocsConfigure permissionsClaude Code DocsHow Claude remembers your projectClaude Code DocsData usageClaude Code DocsPlatforms and integrationsClaude Code DocsHow the agent loop worksClaude Code DocsExplore the context windowClaude Code DocsConnect Claude Code to tools via MCPClaude Code DocsCreate custom subagentsClaude Code DocsCreate plugins