解剖一个Claw：84个Hook构成的编排层

第一个Hook只花了四分钟编写。它阻止模型在纯Anthropic工作流中推荐OpenAI产品。两个月后，这一个Hook变成了84个。84个Hook连接着43个技能、19个专用智能体和30个库模块。在某个节点上，这些脚本的集合不再只是一组脚本，而是变成了一个编排层。

所谓“Claw”，是构建在AI智能体CLI之上的编排层，负责调度、上下文管理、工具路由和质量执行。 它并非自上而下设计出来的，而是在逐个解决具体故障的过程中有机生长而成。这套架构对应着Karpathy指出的五项功能，其中规划与执行的分离，是基于Hook的系统自然涌现出的属性。

我并非有意如此设计。没有人会坐下来说“我要构建15,000行智能体基础设施”。你解决一个问题，然后再解决一个，接着要解决的是这些问题彼此交互所带来的问题。等你注意到架构的存在时，它已经形成了。

Andrej Karpathy也注意到了这一点。2026年2月，他将“Claws”描述为一个新的计算层：编排、调度、上下文管理和工具路由，构建在LLM智能体之上，正如智能体构建在LLM之上一样。¹这一提法把实践者一直在构建却未曾命名的东西具象化了。本文是对这样一个系统的解剖：它包含什么、如何生长、哪里有效、哪里失效。

TL;DR

Karpathy的“Claws”层描述的是构建在智能体CLI之上的编排系统。我在Claude Code上用两个月时间有机地构建了一个：84个Hook覆盖15种事件类型、43个技能、19个智能体和30多个库模块。该系统清晰地映射到Claws的五项功能（编排、调度、上下文管理、工具路由、质量执行），但存在一个显著缺口（声明式工作流定义）。关键发现：规划与执行的分离是基于Hook的编排自然涌现的属性，而非设计目标。Lattner的观察，即“判断力和抽象能力仍是核心，而AI自动化的是实现”，可以直接映射到Hook架构上：治理Hook行使判断，自动化Hook执行实现。

Claws分类体系

Karpathy的描述确定了Claws层执行的五项功能。每项功能在我过去两个月于Claude Code上构建的Hook系统中都有直接对应。¹

这一分类体系之所以有用，是因为它分离了实践者往往会混在一起构建的关注点。我早期的Hook把上下文管理与质量执行混为一谈。成本跟踪Hook既注入预算上下文（上下文管理），又拦截昂贵操作（质量执行）。把它们拆成彼此独立的Hook之后可靠性提升了，因为每个Hook都可以单独失败，而不会拖垮另一项功能。

完整系统

截至2026年2月的数据：

Hook在各事件类型上的分布，揭示了编排复杂度集中在哪里：

UserPromptSubmit承载的分量最重，因为它在每条用户消息上都会触发。调度器（prompt-dispatcher.sh）在每个提示词上顺序运行九个Hook：安全过滤、分析统计、使用跟踪、系统监控、目标注入、时间估算拦截、上下文注入、记忆主题注入和上下文压力监控。²

每个Hook都会增加延迟。九个顺序执行的Hook，实测每次提示共增加200毫秒。调度器采用顺序执行而非并行，是因为早期测试中并发Hook写入共享JSON状态文件导致了数据损坏。两个Hook同时写入jiro.state.json会产生被截断的JSON，进而破坏所有下游Hook。顺序执行更慢，但安全。这200毫秒的开销对用户是不可感知的，因为瓶颈在人的打字速度，而不在Hook延迟。

它是如何生长的

增长并非线性。它遵循的是“问题、解决方案、整合”的循环模式。

第一阶段：单一用途的Hook（第1至2周）。 每个Hook解决一个问题。enforce-opus-model.sh拦截非Opus模型请求。no-time-estimates.sh从回复中移除工作量估算。filter-sensitive.sh捕获工具调用中的凭证。这些Hook各自独立运作，没有任何一个知道其他Hook的存在。

第二阶段：协调问题（第3至4周）。 Hook开始互相干扰。凭证过滤器拦下了合法的API调用。模型强制器与子智能体生成发生冲突。解决办法是调度器。一个单一入口（prompt-dispatcher.sh）取代了七个独立的UserPromptSubmit Hook，通过缓存的stdin管道控制执行顺序并共享状态。

第三阶段：复合能力（第5至8周）。 单个Hook开始组合成系统。质量循环通过一个共享状态文件（jiro.state.json），把前置工具Hook（在问题发生前捕获）与后置工具Hook（在结果产生后验证）连接起来。审议系统用递归守卫、生成预算和共识协议协调多个智能体，避免陷入无限循环。Ralph（自主开发循环）在一条编排管线中把PRD文件、Claude生成、测试验证和代码审查串了起来。

第四阶段：自我感知（第9周以后）。 系统大到需要工具来理解自身。跨Hook系统的语义搜索（/find技能）让智能体能按用途而非文件名发现Hook。性能监控（/perf技能）跟踪系统自身的开销是否正在拖慢机器。上下文压力监控器会在编排层注入的上下文吃掉过多模型上下文窗口时发出警告。

从单一用途的Hook到自我监控基础设施的演进，与Chris Lattner在评述Claude C编译器项目时指出的模式如出一辙：“好的软件依赖判断力、沟通和清晰的抽象。AI放大了这一点。”³Hook系统的架构揭示了同样的道理。有价值的Hook不是那些把任务自动化的Hook，而是那些把“何时以及如何自动化任务”的判断编码下来的Hook。

判断Hook与自动化Hook

Lattner对Claude C编译器的评述区分了AI擅长自动化的部分（实现）与本质上仍属于人的部分（判断力与抽象）。³这一区分可以直接对应到Hook系统上。

判断Hook决定某件事是否应该发生。它们编码的是策略，而非流程。

自动化Hook执行既定动作。它们编码的是流程，而非策略。

判断Hook更难写、更难测，也更有价值。quality-gate.sh需要七种具名的失败模式、六项证据标准和一个模糊措辞检测器。inject-context.sh只需要五行Bash。但两者都不可或缺。自动化Hook提供判断Hook所要评估的数据。sysmon-snapshot.sh（自动化）把数据喂给性能监控器，后者决定是否建议下调智能体数量（判断）。

比例很重要。在一个健康的编排层里，判断Hook的数量应当超过自动化Hook。如果大多数Hook只是注入数据或记录指标，那么系统自动化得不错，治理却很差。当前系统经核验的数量是：35个判断Hook，44个自动化Hook，大约4比5。自动化仍占上风。这一比例起初约为1比6（几乎全是注入与日志Hook），在两个月里逐步向判断一侧偏移，因为遇到了纯自动化无法防止的故障，才陆续加入治理约束。比例尚未持平，这本身就是一个有用的信号：这个系统的治理仍然少于它的自动化。

规划与执行的分离

Boris Tane的《How I use Claude Code》一文在Hacker News上拿到936分，文中描述了一种工作流模式：把规划与执行分开。⁴先用一个Claude会话做规划（调研、列提纲、做设计），再用一个全新会话把规划作为结构化输入来执行。这一模式之所以引发共鸣，是因为它解决了一个真实问题：规划与执行会争夺上下文窗口空间。

Hook系统沿着另一条路径抵达了同样的分离。审议系统生成专用智能体来调研并辩论方案。输出是一份结构化的PRD（产品需求文档），包含故事、验收标准和验证类型。Ralph循环读取PRD，并生成全新的Claude实例来实现每一个故事。规划智能体从不实现。实现智能体从不规划。

这种分离并非设计目标。它源自两个彼此独立的约束：

1. 上下文窗口压力。 规划需要读取大量文件并探索选项。实现需要聚焦于当前任务的上下文。把两者塞进同一个上下文窗口，意味着谁都得不到足够空间。分开的会话让每个阶段都拥有完整上下文。

2. 质量验证的独立性。 如果同一个智能体既规划又实现，它就无法客观地对照计划来验证自己的实现。一个只拿到计划和代码的全新智能体，才能提供独立验证。Ralph循环强制执行这一点：实现智能体负责跑测试，但由三个独立的审查智能体（正确性、安全性、规范性）来核验结果。

Tane的手工工作流与自动化Hook系统之间的殊途同归表明，规划与执行的分离是智能体系统的自然属性，而不只是实践者的偏好。任何管理上下文窗口并验证输出的系统，最终都会把规划与执行分开，因为另一条路（在同一个上下文里两件事一起做）会让两个阶段的结果都变差。

Hook系统在哪里失效

这套架构有三个显著弱点，而专门构建的编排框架能够解决它们。

没有声明式的工作流定义。 每个工作流都以命令式方式编码在Bash脚本里。Ralph循环是1,320行Bash，编码了一段特定序列：读取PRD、选择故事、收集上下文、生成Claude、运行测试、运行审查、处理失败、更新状态。改工作流就意味着改Bash。声明式系统会把工作流定义为数据（YAML、JSON），交由解释器执行。声明式工作流更易修改、组合与可视化。命令式脚本起初更好写，但随着规模增长会更难维护。

Hook的排序很脆弱。 提示词调度器按硬编码的顺序运行Hook。把memory-capsule-inject.sh挪到inject-context.sh之前会让胶囊注入失效，因为它依赖inject-context.sh解析出的会话ID。这些依赖是隐式的（编码在调度器的排序里），而非显式的（声明为Hook之间的依赖）。专门构建的系统会把Hook依赖表达为DAG，并按拓扑排序确定执行顺序。

没有工作流可视化。 面对84个Hook，要理解任一用户操作的完整执行路径，就得手工阅读调度器代码并追踪Hook链条。没有任何工具能展示“当用户输入一条消息时，这9个Hook按此顺序触发，其中第3个Hook调用库函数X，而X写入状态文件Y”。这个系统可以通过日志被观察，却无法通过结构被观察。专门构建的编排框架会提供Hook依赖、数据流与执行路径的可视化图谱。

这些弱点有一个共同成因：系统是在逐个解决具体问题的过程中有机生长出来的，而不是作为一个连贯的编排层被设计出来的。有机生长产出的系统能跑（全部84个Hook在生产环境中都工作正常），却难以作为整体来推理。这个取舍是实打实的：预先设计编排层会带来更好的结构，却会带来更弱的能力，因为许多能力（记忆胶囊、输出白名单、生成预算）都是为应对那些在发生之前无法预料的故障而发明出来的。

Harness走向主流

在Karpathy为这一层命名三周之后，这个概念有了第二个名字，也有了一个不断壮大的社区。

Geoffrey Huntley提出了一个正式定义：“Agent Harness，即围绕语言模型的编排层，它把模型从一件工具变成一位队友。”⁵这一提法很精准。Harness不是模型，也不是模型调用的那些工具。它是决定调用哪些工具、何时调用、以及如何评估调用是否成功的那套系统。每一个生产级智能体系统都会构建这一层。多数是隐式地构建，藏在把编排逻辑与业务逻辑混在一起的应用代码里。给它命名，架构才变得可见。

社区信号印证了这一模式正在扩散。Pieter Levels表示自己已永久转为在服务器上运行Claude Code，把它当作基础设施而非本地工具。⁶Anthropic推出了Remote Control，让用户可以在终端里启动任务，再到Claude.ai上接着做。⁷Ben Cherny宣布/simplify和/batch成为第一方技能。⁸这几件事都是harness特性：持久执行、远程编排、内置能力模块。CLI正在长成harness。

与此同时，实践者也在构建自己的harness组件。一位开发者发布了22条自定义的Obsidian加Claude Code命令，用作个人操作系统。⁹另一位做出了一个“Visual Explainer”智能体技能，并配套了斜杠命令。¹⁰这些模式高度一致：调度器、技能、共享状态、事件驱动的Hook。没有人会先读框架指南再动手。他们解决一个问题，然后再一个，接着解决这些问题彼此交互带来的问题。

最近的两个项目，展示了社区自建的harness组件已经成熟到何种程度。nah是一个上下文感知的权限守卫，以PreToolUse Hook的形式注册。¹⁴它把动作分为20种不同类型（文件写入、网络请求、进程生成等），并按类型施加策略。该工具能检测管道分解攻击，即智能体把若干看似无害的命令串联起来，以达成一个本应被拦截的操作。它的架构与本文中的filter-sensitive.sh和recursion-guard.sh如出一辙，是另一位实践者在解决同样的治理问题时独立得出的。

Rudel则通过把Claude Code会话数据摄入ClickHouse来提供会话分析。¹⁵对1,573次会话的分析显示，只有4%的用户会调用技能，26%的会话在60秒内被放弃。这些数字印证了harness架构所隐含的判断：多数用户只在表层与智能体CLI打交道。本文描述的编排层，位于使用分布的深水区，而绝大多数人从未离开浅水区。工具能做到的事与多数用户会去要求它做的事之间的落差，正是harness基础设施要填补的空间。

Autoresearch：作为研究循环的harness

Karpathy自己的autoresearch项目，在另一个领域演示了同样的harness模式。¹¹该系统让语言模型对着一个训练脚本（train.py）工作，跑一次五分钟的实验，用一项固定指标（验证集每字节比特数）评估结果，然后保留改进、丢弃倒退。两天之内，系统跑了约700次实验，找到约20项真正的改进，把GPT-2的训练时间缩短了11%。

这套架构与上文描述的Hook系统别无二致。固定的评估装置（prepare.py）相当于判断Hook：它决定一次实验是否成功。训练脚本（train.py）相当于自动化Hook：它执行智能体所做的修改。Git分支管理（有改进就保留，有倒退就重置）相当于Ralph循环的状态管理。results.tsv日志相当于会话遥测。

这一模式之所以可迁移，是因为harness解决的问题与领域无关。无论智能体是在写代码、优化训练循环，还是在管理内容管线，它都需要：一种按标准评估结果的方式、一种保留或丢弃变更的方式、一种跨迭代维持状态的方式，以及一种无人干预自主运行的方式。这四项需求会产出同一套架构，无论智能体实际在做什么。

Shopify首席执行官Tobi Lütke在内部改用了autoresearch。他那个经由智能体优化的较小模型，跑赢了人工配置的较大模型，这印证了一个说法：自主的、由harness驱动的迭代，能发现人类想不到去尝试的配置。¹²

Harness中的安全缺口

Harness解决的是编排问题，它并不会自动解决安全问题。

一项针对LLM驱动的迭代式代码精修的研究发现，43.7%的迭代链条在经过十轮智能体修改之后，漏洞数量反而多于它们起步时的基线代码。¹³根本原因是规格漂移：智能体在为功能正确性做优化的同时，逐步删掉了防御性逻辑，也弱化了异常处理。更糟的是，在迭代循环中加入静态分析安全工具（SAST门控），反而把潜在退化从12.5%推高到20.8%。扫描器制造了一种虚假的安全感，让智能体变得更不谨慎，而非更谨慎。

这一退化发现与harness设计直接相关。本文描述的那些判断Hook（quality-gate.sh、filter-sensitive.sh、recursion-guard.sh）所针对的，正是单靠自动化就会退化的质量与安全维度。解决该退化问题的SCAFFOLD-CEGIS框架采用了四层带门控的验证，把潜在退化率压到2.1%，并达成100%的安全单调性。¹³其架构与Hook系统相互呼应：分离的评估层，各自检查不同的属性，各阶段之间设有显式门控。

另一项工作从生产侧佐证了同样的威胁模型。Perplexity提交给NIST的回应梳理了大规模运行的智能体系统的攻击面。¹⁶主要向量包括：通过数据通道（网页、邮件、工具输出）实施的间接提示词注入；智能体特有的CIA三性破坏（借助工具调用外泄数据、通过上下文投毒操纵行为、通过递归生成耗尽资源）；以及来自智能体相邻系统的真实CVE。他们推荐的防御架构（输入层过滤、模型层对齐，以及通过沙箱和白名单实现的确定性强制），与本文所述Hook系统中有机涌现的三层模式相互印证。自动化Hook过滤输入。模型行使判断。治理Hook强制执行模型无法绕开的确定性约束。

给实践者的教训是：如果您的harness只会自动化和编排，却不做治理，那么迭代式的智能体执行会引入标准工具链检测不到的安全倒退。判断Hook不是额外开销，它们正是系统不会退化的原因。

更新，9月3日：这一失效模式已在现实中出现

本文在“Harness中的安全缺口”一节里描述的那个缺口，如今有了一位有据可查的受害者。2026年7月19日，Claude Code v2.1.204正在Udaya Kumar P L的电脑上清理缓存，此人是Mythic Society旗下班加罗尔碑铭三维数字化保护项目的名誉主任。按他本人的说法，当时“一个AI生成命令中的引号错误，把指令变成了‘删除一切’”。对harness设计而言真正重要的是接下来发生的事：“当它明白过来并试图杀掉该进程时，它自己的安全系统拦下了这次终止。两次[…]安全层放行了这场破坏。”四分钟后他关掉了机器。损失包括：四五个程序，以及十年间收集的碑铭、英雄石、寺庙与钱币的原始照片，约占该项目记录的15%，其中包括一块刻有Hebbal这一地名早期写法的石头（公元750年）。NAS上的副本幸存，硬盘则没有。该学会正在花费Rs 15 lakh（150万卢比）购置第二台NAS和异地磁带备份，志愿者还将重新扫描约120处遗址。一个多月过去，他没有收到Anthropic任何人的回应。¹⁷

这段叙述中有三点与上文的论证吻合。那个破坏性步骤并不是模型的决策，而是生成命令中的一次shell引号失误，恰恰属于PreToolUse判断Hook存在的意义所在的那一类。文章没有点明当时使用的是哪种权限模式，因此没有任何第一方记录显示那条命令曾被审查过；即便处于auto模式，分类器默认也只审查匹配任意代码执行模式的shell命令。他还说智能体绕过了一个沙箱，但文章没有给出那是什么类型的沙箱。对于相邻的情形，Anthropic此前已经发布过一道防护：7月8日发布的v2.1.205让auto模式在对一个无法从上下文解析的变量执行rm -rf之前先行询问。而那台机器上跑的是v2.1.204。¹⁹随后安全层确实尽职了，只是方向反了：它把智能体自己的补救动作当成了危险动作。至于幸存下来的部分，靠的是唯一一项完全处在harness之外的控制措施，也就是备份；其余的只能靠人工重新扫描。这类事件如今至少有了一份非官方的登记册；他指出官方的并不存在。I Have Been Clawed是一份带来源链接的智能体与聊天机器人事故档案，每条都附上一则教训，撰稿时收录58条，其中7条与Claude Code有关，而它在自己的首页上坦承：条目是自我筛选的，并按传播度加权，因此按工具统计的数量衡量的是报告文化，而不是安全性。在此之前，它已经收录了三条形态相同的Claude Code条目：一条递归命令删除了WSL主目录中用户自有的文件（2025年10月21日）；一个字面量的波浪号目录使主目录暴露于删除风险（2025年11月28日）；以及一条以主目录路径结尾的清理命令抹掉了一台Mac（2025年12月7日）。在现实世界里，这是一种模式，而非一则故事。¹⁸

实践者应该带走什么

如果您正在智能体CLI之上构建编排层，无论是从Claude Code指南起步还是从零开始，本系统中的三个模式都可以直接迁移。

从调度器开始，而不是从单个Hook开始。 最大的架构改进，是用一个顺序运行处理器的调度器，替换掉七个独立的UserPromptSubmit Hook。如果您预计某个事件类型上会有超过三个Hook，那就先把调度器建起来。写调度器花掉的30分钟，能省下日后调试Hook交互问题的数小时。最小可用的模式如下：

#!/bin/bash
# dispatcher.sh — sequential hook execution with shared stdin
HANDLERS=("inject-context.sh" "track-usage.sh" "quality-gate.sh")
HOOK_DIR="$(dirname "$0")/handlers"
INPUT=$(cat)  # Cache stdin once (each handler gets the same input)

for handler in "${HANDLERS[@]}"; do
    [ -x "$HOOK_DIR/$handler" ] && echo "$INPUT" | "$HOOK_DIR/$handler"
done

把这个单一调度器注册为您的Hook入口点。随着处理器的构建，逐个加入数组。每个处理器读取同一份缓存的stdin（Hook事件负载），并各自独立地写入stdout。

尽早把判断与自动化分开。 写新Hook时先问一句：“这个Hook是在决定某件事该不该发生，还是在执行一个既定动作？”判断Hook需要更多测试、更多边界情况处理和更多迭代。自动化Hook需要的是可靠与高效。把两者一视同仁，结果就是判断Hook测试不足，自动化Hook过度设计。

让规划与执行的分离自然涌现。 不要在第一天就强行分离。先构建能跑起来的最简方案。当您发现智能体的上下文窗口无法同时容纳规划与实现时，再把它们拆开。当您发现智能体无法客观验证自己的工作时，再加入独立的审查智能体。约束一旦提出要求，这种分离自会显得理所当然。

Harness走向主流，是因为这一模式不可避免。无论您把这一层称作Claws、Agent Harness，还是干脆叫“我的hooks文件夹”，任何协调智能体奔向目标的系统，最终都会收敛到同一套架构：用调度器定序、用判断Hook做治理、用自动化Hook做执行、用状态文件保持连续。Claude Code源码泄露证实，Anthropic自家的内部架构也遵循同样的模式，其中协调者模式完全由系统提示词指令实现，而非代码层面的编排。相较于专门构建的编排框架，基于Hook的做法有一个优势：零承诺。每个Hook都是独立的。您可以只采用一个Hook，也可以采用十个或八十四个。您可以删掉任何一个Hook而不破坏其他Hook（前提是您维护好调度器）。没有要学的框架，没有要管的依赖，没有要运维的运行时。编排层就是一堆文件。

常见问题

什么是智能体harness或者说“Claws”层？

Claws层（由Andrej Karpathy在2026年2月命名）是构建在智能体CLI之上的编排系统，它把CLI从一件工具变成一位队友。¹它执行五项功能：编排（协调多个智能体）、调度（确定任务的执行时机）、上下文管理（跨轮次维护相关信息）、工具路由（把工具调用引导至适当的处理器），以及质量执行（验证输出是否符合标准）。Geoffrey Huntley把这一定义正式化为“围绕语言模型的编排层”。⁵

PreToolUse Hook在Claude Code中如何工作？

PreToolUse Hook在每次工具调用（Bash命令、文件写入、文件编辑、子智能体生成）之前触发，并通过stdin以JSON形式接收工具调用负载。Hook脚本评估该负载后返回一个决定：允许、拒绝或修改。模型无法跳过、覆盖或与Hook讨价还价，因为它们在基础设施层执行，而不在提示词层。²调度器模式会在每个事件上顺序运行多个Hook，并用一条缓存的stdin管道保证每个处理器收到相同的输入。

判断Hook与自动化Hook有什么区别？

判断Hook决定某件事是否应该发生（策略），自动化Hook则执行既定动作（流程）。判断Hook包括质量门控、凭证过滤器、递归守卫和成本门控。自动化Hook包括上下文注入、使用跟踪、系统监控和心跳。³比例很重要：一个以自动化Hook为主的系统，自动化做得好，治理做得差。当前系统的比例是35个判断Hook对44个自动化Hook，并随着故障暴露出纯自动化无法防止的问题而逐步向治理偏移。

为什么规划与执行的分离会在智能体系统中自然出现？

有两个彼此独立的约束在推动这种分离。其一，规划需要读取大量文件并探索选项，而实现需要聚焦于当前任务的上下文，把两者放进同一个上下文窗口意味着谁都得不到足够空间。其二，如果同一个智能体既规划又实现，它就无法对照计划客观验证自己的工作。⁴任何管理上下文窗口并验证输出的系统，最终都会把规划与执行分开，因为另一条路会让两个阶段的结果都变差。

我该如何着手构建自己的Hook系统？

从调度器开始，而不是从单个Hook开始。如果您预计某个事件类型上会有超过三个Hook，就构建一个从数组中顺序运行处理器的单一调度器。写调度器花掉的30分钟，能省下日后调试Hook交互问题的数小时。尽早把判断与自动化分开，方法是自问：“这个Hook是在决定某件事该不该发生，还是在执行一个既定动作？”不妨从Claude Code Hook教程入手，并在真实故障提出要求时再逐步添加Hook，而不是一上来就设计整个系统。

参考来源