论文精读

OpenHarness 深度研究：港大用 1.1 万行 Python 复刻 Claude Code 的启示

HKUDS 开源的轻量级 Agent Harness 框架，以 2.3% 的代码量实现 98% 的核心工具能力。本文从架构拆解、竞品对比、数据价值三个维度展开分析。

OpenHarness Agent Harness Claude Code HKUDS 开源框架 Agent 架构

基本信息

维度内容
项目OpenHarness（oh）
开发方香港大学数据智能实验室（HKUDS），PI：黄超
发布日期2026-04-01（v0.1.0），当前 v0.1.6（04-10）
GitHubHKUDS/OpenHarness，9.3K Stars
许可证MIT
代码量~11,733 行 Python（Claude Code 的 1/44）
附属产品ohmo——基于 OpenHarness 的个人 AI 代理
关联论文Externalization in LLM Agents（2026-04-09，54 页综述）

一、这个项目在做什么

OpenHarness 的核心主张用一句话概括：

“The model is the agent. The code is the harness.”

它不是又一个 Agent 框架，而是对”Agent Harness”这个概念的极简开源实现。Harness 指的是包裹在 LLM 外面的全部工程基础设施——工具调用、权限治理、记忆管理、上下文压缩、多 Agent 协调。模型提供智能，Harness 提供手脚、眼睛、记忆和安全边界。

项目的直接对标物是 Claude Code（Anthropic，~512K 行 TypeScript），OpenHarness 用 ~11.7K 行 Python 复刻了其 98% 的核心工具（43/44）和 61% 的命令集（54/88）。

二、架构拆解

2.1 Agent Loop——心脏

while True:
    response = await api.stream(messages, tools)
    
    if response.stop_reason != "tool_use":
        break  # 模型认为任务完成
    
    for tool_call in response.tool_uses:
        # 权限检查 → PreToolUse Hook → 执行 → PostToolUse Hook → 收集结果
        result = await harness.execute_tool(tool_call)
    
    messages.append(tool_results)

核心循环极简，所有复杂性通过工具注册、Hook 拦截、权限检查外挂。支持流式工具调用、并行执行、指数退避重试、Token 计数和成本追踪。

2.2 10 子系统分层

┌─────────────────────────────────────────────┐
│        Layer 4: 交互层                       │
│   ui/ (React TUI) + commands/ (54 命令)      │
├─────────────────────────────────────────────┤
│        Layer 3: 协调层                       │
│ coordinator/ (多Agent) + tasks/ (后台任务)    │
├─────────────────────────────────────────────┤
│        Layer 2: 能力层                       │
│ tools/ (43工具) + skills/ (知识)             │
│ plugins/ (插件) + mcp/ (MCP协议)             │
├─────────────────────────────────────────────┤
│        Layer 1: 核心层                       │
│ engine/ (Agent Loop) + permissions/ (治理)   │
│ hooks/ (生命周期) + memory/ (记忆)            │
│ prompts/ (上下文) + config/ (配置)            │
└─────────────────────────────────────────────┘

2.3 工具集（43+ 工具，7 大类）

类别工具说明
文件 I/OBash, Read, Write, Edit, Glob, Grep核心文件操作 + 权限检查
搜索WebFetch, WebSearch, ToolSearch, LSPWeb 和代码搜索
NotebookNotebookEditJupyter notebook 编辑
AgentAgent, SendMessage, TeamCreate/Delete子 Agent 生成与协调
任务TaskCreate/Get/List/Update/Stop/Output后台任务管理
MCPMCPTool, ListMcpResources, ReadMcpResourceModel Context Protocol
元工具Skill, Config, Brief, Sleep, AskUser知识加载、配置、交互

每个工具标准化具备：Pydantic 输入验证、JSON Schema 自描述、权限集成、Pre/PostToolUse 生命周期钩子。

2.4 权限治理

三种模式对应不同安全等级：

模式行为适用场景
Default写入/执行前询问确认日常开发
Auto允许所有操作沙箱/CI
Plan阻止所有写入审查阶段

支持路径级规则和命令黑名单。与 Claude Code 的 6 层权限系统相比，实现更轻但覆盖了核心场景。

2.5 记忆系统

机制说明
CLAUDE.md Discovery自动发现项目根目录规则文件并注入上下文
Auto-Compact上下文超限时自动两阶段压缩（裁剪旧工具结果 → LLM 摘要）
MEMORY.md跨会话持久化记忆
Session Resume会话恢复和历史回溯

2.6 多模型支持

这是与 Claude Code 最核心的差异化。OpenHarness 通过 Provider 工作流机制原生支持：

  • Anthropic 格式：Claude 官方、Moonshot/Kimi、智谱 GLM、MiniMax
  • OpenAI 格式：OpenAI、OpenRouter、DashScope（通义千问）、DeepSeek、Groq、Ollama（本地）
  • 订阅桥接：Claude CLI / Codex CLI 本地凭据复用
  • GitHub Copilot：设备流 OAuth 认证

2.7 ohmo 个人代理

基于 OpenHarness 构建的长期运行个人助手，不是聊天机器人——能在消息平台里 fork 分支、写代码、跑测试、提 PR。

支持频道：Telegram / Slack / Discord / 飞书，可复用已有的 Claude Code 或 Codex 订阅。

核心配置文件：soul.md（人格）、identity.md（身份）、user.md（用户档案）、memory/（记忆）。

三、OpenHarness 证明了什么

3.1 Agent Harness 的核心复杂度远低于想象

这是最重要的结论。Claude Code 512K 行代码中，真正定义”Agent 是什么”的部分可能只有 2.3%。剩下的 97.7% 是：

被剥离的部分估算占比说明
遥测系统~5%Sentry、指标上报、用户分析
OAuth/认证~3%企业 SSO、多租户、API key 管理
React UI 组件~15%数百个 UI 组件
企业级基础设施~35%配置迁移、Feature Flag、i18n、兼容性
utils/辅助~35%第 15 章的”18 万行 utils”
Agent 核心~2.3%Loop + Tools + Memory + Permissions

这与我在《Claude Code 源码解构》第 15 章的判断一致：Harness 决定产品，Model 只决定上限——但 Harness 的”核心”和 Harness 的”工程化包装”是两回事。OpenHarness 剥离了后者，保留了前者。

3.2 生态兼容性是聪明的策略

OpenHarness 没有另起炉灶，而是兼容了：

  • anthropics/skills 生态——.md 文件直接复制即用
  • claude-code/plugins 生态——已测试 12 个官方插件
  • CLAUDE.md 约定——自动发现并注入

这意味着它不需要建立自己的内容生态，直接继承了 Claude Code 社区的资产。

3.3 但它没有证明的东西

  1. 没有 benchmark 数据。GitHub Issue #51 有人问过 SWE-bench 对比，团队未正式回复。一个声称”98% 工具覆盖”的项目，没有任何端到端任务完成率的证据。
  2. 生产级稳定性未经验证。v0.1.6 是第 6 个版本，12 天发了 6 版，迭代极快但也意味着 API 不稳定。
  3. 多 Agent 协调只是骨架。Swarm Coordination 目前是 Asyncio 级别，ClawTeam 集成还在路线图里。
  4. 上下文压缩效果不明。Auto-Compact 声称两阶段压缩（128k→80k），但没有公开的信息保留率测试。

四、竞品全景对比

4.1 核心维度对比表

维度OpenHarnessClaude CodeOpenClawHermes AgentAiderCodex CLI
开发方港大 HKUDSAnthropic开源社区Nous ResearchPaul GauthierOpenAI
定位轻量 Agent 框架生产级编程助手通用 Agent 平台自进化个人助手终端编程搭档终端编程助手
开源✅ MIT❌ 闭源✅ MIT✅ MIT✅ Apache 2.0✅ Apache 2.0
代码量~11.7K 行~512K 行~430K 行-~30K 行~25K 行
语言PythonTypeScript (Bun)TypeScript/NodePythonPythonTypeScript
Stars9.3KN/A247K28K35K45K
工具数43 (98%)44插件式40+~10~15
模型支持任意（18+ 后端）仅 Anthropic多模型任意（18+ 后端）多模型仅 OpenAI
记忆MEMORY.md + SQLite三层压缩 + Kairos白盒 MarkdownMEMORY.md + USER.md（有限空间）Git 历史会话内
多 AgentSwarm (Asyncio)CoordinatorCell Isolation子 Agent 并行❌❌
自学习❌❌被动记录✅ 闭环自学习❌❌
消息平台4（Telegram/Slack/Discord/飞书）❌2214❌❌
部署门槛pip install订阅较高一行 curlpip installnpm install
成熟度v0.1.6 早期生产级生产级v0.5+稳定稳定

4.2 定位差异分析

这六个项目其实分属三个赛道，不应简单横向比较：

赛道 A：Agent 基础设施框架

  • OpenHarness：极简 Harness 参考实现，面向研究者和二次开发
  • OpenClaw：全功能 Agent 运营平台，面向团队和企业

赛道 B：编程助手产品

  • Claude Code：生产级 IDE 内编程助手，体验最佳
  • Aider：轻量终端编程搭档，Git-first 设计
  • Codex CLI：OpenAI 官方终端编程工具

赛道 C：自主智能体

  • Hermes Agent：自进化个人助手，越用越聪明

OpenHarness 最准确的竞品是 OpenClaw（同为框架），而不是 Claude Code（产品）或 Hermes（自主智能体）。

4.3 关键差异深挖

OpenHarness vs Claude Code：框架 vs 产品

维度优势方分析
可读性OpenHarness1.1 万行 Python 可在一天内通读
可扩展性OpenHarness新工具只需 Pydantic Model + 执行逻辑
模型自由度OpenHarness18+ 后端即切即用
稳定性Claude Code数百万用户验证的生产级产品
IDE 集成Claude CodeVS Code / JetBrains 原生插件
企业功能Claude CodeSSO、审计日志、合规

判断：Claude Code 是成品汽车，OpenHarness 是汽车底盘图纸。两者服务的人群不同。

OpenHarness vs Hermes Agent：框架 vs 自进化

Hermes Agent 在三个维度上与 OpenHarness 有本质差异：

  1. 自学习闭环：Hermes 完成 5+ 次工具调用的任务后自动评估，将成功工作流沉淀为 SKILL.md。每 15 次调用暂停反思总结。实测一个月后同类任务工具调用数从 ~25 压缩到 8-10（60-70%）。OpenHarness 没有这个能力。

  2. 有限记忆设计：MEMORY.md 上限 2,200 字符，USER.md 上限 1,375 字符，合计 ~1,300 token 恒定空间。空间有限迫使 Agent 学会筛选、压缩、合并——OpenHarness 的记忆没有这种约束设计。

  3. 原生调度：cron 调度 + daemon 常驻，全天候自主运行。OpenHarness 需要外部 CI/CD 配合。

判断：如果目标是”越用越懂你的个人助手”，Hermes Agent 在设计哲学上领先一代。但 OpenHarness 作为底层框架，理论上可以在上面实现 Hermes 的自学习机制。

OpenHarness vs OpenClaw：轻量 vs 全能

维度OpenHarnessOpenClaw
技能生态兼容 anthropics/skillsClawHub 1.3 万+ 技能
消息平台4 个22 个
记忆哲学基础持久化白盒 Markdown + SpatialRAG
安全模型3 级权限Cell Isolation 沙箱
代码量11.7K 行430K 行

判断：OpenClaw 是”瑞士军刀”，OpenHarness 是”手术刀”。选型取决于需求：快速搭建定制 Agent 选 OpenHarness，需要完整运营平台选 OpenClaw。

五、学术背景：外化理论

2026-04-09 发布的综述论文 Externalization in LLM Agents（54 页）为 Harness 概念提供了学术框架：

LLM Agent 能力来源的三阶段演进：
  Weights（权重内化）→ Context（上下文注入）→ Harness（运行时外化）

论文将外化分为四层：

外化模块外化对象说明
Memory跨时间状态从上下文窗口中解放长期信息
Skills程序性知识模块化可复用操作能力
Protocols交互结构Agent 间交互模式标准化（如 MCP）
Harness Engineering治理化执行统一协调层，编排上述模块为受治理的系统

论文明确将 self-evolving harnesses（自进化框架） 列为前沿方向——Harness 不再是静态工程制品，而是在运行中自主适应和改进的动态系统。这与 Hermes Agent 的自学习闭环、以及我在 harness-is-the-dataset 中提出的”Harness 执行轨迹即训练数据”的思路形成共振。

六、对 HarnessForge 的影响

站内已有的 HarnessForge 开发文档 将 OpenHarness 列为技术选型之一。需要更新几个判断：

6.1 OpenHarness 作为 Dev Agent 运行时

优点确认：

  • 43+ 内置工具覆盖代码开发全场景
  • Docker 沙箱后端提供安全隔离
  • 事件级轨迹粒度（每个 tool call 独立记录），优于 Claude Code CLI 的轮级粒度
  • pip install openharness-ai 安装简单

需要注意的风险：

  • API 仍在快速迭代（12 天 6 版），harness.run() 接口可能变化
  • 无公开 benchmark，端到端任务完成率不明
  • 社区 12 天，长期维护承诺未知

6.2 轨迹数据价值

OpenHarness 的事件级轨迹结构天然适合 HarnessForge 的数据收集需求。每个 tool call 都是独立事件（工具名、输入参数、输出结果、耗时、Token 消耗），不需要事后解析日志。这比 Claude Code CLI 的轮级 JSON 更适合做细粒度的轨迹拆分和中训练数据提炼。

6.3 建议

维持 开发文档 中的”双轨策略”不变——OpenHarness 作为主选项，Claude Code CLI 作为 fallback。但将 API 稳定性检查作为 Phase 0 门控：在 v0.2.0 之前，核心 API 若发生 breaking change，自动切换到 CLI 版本。

七、判断与展望

7.1 OpenHarness 的真正价值

不在于替代 Claude Code，而在于三件事：

  1. 教育价值。对于想理解”生产级 Agent 到底在做什么”的研究者，1.1 万行可通读的 Python 比 50 万行闭源 TypeScript 有用得多。
  2. 框架价值。模型中立的 Harness 底座，适合在上面构建领域专用 Agent（比如 HarnessForge 的代码任务工厂）。
  3. 证明价值。用 2.3% 的代码量证明了 Agent 核心架构的极简性，倒逼行业思考”你的 50 万行代码里有多少是真正需要的”。

7.2 它缺什么

  1. 端到端验证。需要在 SWE-bench 等标准 benchmark 上证明自己。“98% 工具覆盖”不等于”98% 任务完成率”。
  2. 自学习机制。Hermes Agent 证明了自进化是可行且有效的设计方向，OpenHarness 完全没有触碰这个维度。
  3. 长期维护。学术团队开源项目的常见问题——热度退潮后是否还有持续投入。HKUDS 在这方面的 track record（LightRAG → OpenSpace → CLI-Anything → OpenHarness）算是正面信号。

7.3 数据视角：对我们意味着什么

从中训练/后训练数据的角度，OpenHarness 生态的启示是：

  1. Harness 执行轨迹是新的数据资产。正如 Philipp Schmid 所言”The Harness is the Dataset”——Agent 在 Harness 中的执行轨迹本身就是高质量的训练数据。OpenHarness 的事件级轨迹结构让这种数据的收集成本大幅降低。

  2. 多 Harness 对比是数据质量信号。同一个任务在 OpenHarness vs Claude Code vs Aider 中的不同执行轨迹，其差异本身就是有价值的训练信号——它编码了”什么样的工具调用策略更高效”这类隐式知识。

  3. 自进化轨迹是更高阶的数据。Hermes Agent 的自学习闭环产生的”Agent 改进自己做法”的轨迹（meta-trajectory），比 object-level 的任务执行轨迹具有更高的数据价值——这与今天早些时候的 递归式自进化轨迹数据提案 方向一致。

参考

  1. HKUDS/OpenHarness — GitHub 仓库
  2. Externalization in LLM Agents — 外化综述论文（2026-04-09，54 页）
  3. OpenHarness 深度解析 — 智柴网技术分析
  4. OpenClaw、Hermes Agent 与 OpenHarness 对比 — SegmentFault 三方对比
  5. Hermes Agent vs OpenClaw 深度对比 — WMW 技术对比
  6. OpenHarness vs Claude Code 比较 — CSDN 对比分析
  7. Harness Engineering — 站内 Harness 工程化研究
  8. The Harness is the Dataset — 站内”Harness 即数据”研究
  9. HarnessForge 开发文档 — 站内 OpenHarness 实现规划