OpenHarness：港大开源的AI Agent轻量级框架，1.1万行代码复刻Claude Code 98%核心能力

一、开篇：一个让GitHub服务器"喘不过气"的项目

2026年4月，一个现象在AI圈悄然发生：AI Agent驱动的代码提交量正在以惊人的速度增长，GitHub的每周commit量已经达到了前所未有的峰值。而在这股浪潮中，有一个项目格外引人注目——OpenHarness。

4月2日开源，两天狂揽1.9K+ GitHub Star，登顶全球Trending榜首。不到一周，Star数突破7000。用1.1万行Python代码，实现了闭源巨头51.2万行代码98%的核心工具能力，体积直接压缩44倍。

这不是一个普通的"轮子"，这是香港大学数据科学研究院（HKUDS）对AI Agent本质的一次深刻回答。

二、什么是 Agent Harness？重新理解AI Agent的边界

在AI圈有一个公认的公式：

Agent = LLM + Harness

LLM提供智能，Harness提供"手、眼、记忆和安全边界"。

OpenHarness给出的定义更加精准：

An Agent Harness is the complete infrastructure that wraps around an LLM to make it a functional agent.

翻译过来就是：Agent Harness是包裹在LLM周围的完整基础设施，使其成为一个功能性的智能体。

这个定义揭示了AI Agent的本质：模型本身只是"大脑"，真正让它能做事的，是围绕它构建的工具调用系统、上下文管理、权限控制、记忆持久化等一整套工程系统。

Harness = Tools + Knowledge + Observation + Action + Permissions

这个公式概括了Harness的五大核心要素：

• Tools：工具能力，让Agent能操作文件、执行命令、调用API
• Knowledge：知识注入，让Agent理解项目上下文、业务规则
• Observation：观察能力，让Agent能感知环境变化、读取输出结果
• Action：行动能力，让Agent能执行操作并产生实际影响
• Permissions：权限控制，让Agent的行为有边界、可审计

三、10大子系统：把黑盒拆成可理解的积木

OpenHarness最难得的一点，是把复杂的Agent Harness拆解成了10个边界清晰、逻辑独立的子系统。每个模块都有完整的类型校验和权限控制，哪怕是新手开发者，也能顺着代码理清Agent的完整运行逻辑。

3.1 Agent Loop（代理循环）——心脏

这是Harness的核心。一个简化的实现如下：

while True:
    response = await api.stream(messages, tools)
    
    if response.stop_reason != "tool_use":
        break  # 模型完成了
    
    for tool_call in response.tool_uses:
        # 权限检查 → Hook → 执行 → Hook → 结果
        result = await harness.execute_tool(tool_call)
    
    messages.append(tool_results)
    # 循环继续，模型基于工具结果继续思考

这个循环实现了"思考-工具调用-结果反馈-再决策"的完整闭环。模型生成工具调用请求，Harness执行并返回结果，模型基于结果继续推理，直到任务完成。

3.2 工具调用系统

内置43种核心工具，覆盖：

• 文件操作：read、write、edit、glob、grep
• Shell执行：exec、bash、terminal
• 网络搜索：web_search、web_fetch
• MCP协议：与外部工具服务的标准化通信
• 代码分析：AST解析、依赖追踪

每个工具都有完整的类型签名、参数校验和权限声明。

3.3 上下文与记忆系统

解决Agent"健忘"的关键设计：

• CLAUDE.md发现与注入：自动发现项目根目录的CLAUDE.md文件，注入项目上下文
• Context Compression（自动压缩）：当上下文超过token限制时，智能压缩历史消息
• MEMORY.md持久化记忆：跨会话保存重要信息，下次对话自动恢复
• 会话恢复：支持断点续聊，不会因为意外中断丢失进度

3.4 权限治理系统

多级权限模式，让Agent的行为可控可审计：

# 权限级别示例
ALLOW_ALL = "allow"          # 允许所有操作
DENY_ALL = "deny"            # 拒绝所有操作
ASK_EACH = "ask"             # 每次操作询问用户
ALLOWLIST = "allowlist"      # 只允许白名单操作

支持细粒度的工具权限控制，比如"只允许读取，禁止写入"，或者"禁止执行网络请求"。

3.5 Hooks系统

在工具执行的各个阶段插入自定义逻辑：

# 执行前Hook
@harness.before_tool("exec")
async def log_command(tool_call):
    logger.info(f"即将执行命令: {tool_call.args['command']}")

# 执行后Hook
@harness.after_tool("write")
async def backup_file(tool_call, result):
    if result.success:
        backup_path = f".backup/{tool_call.args['path']}"
        await backup_file(tool_call.args['path'], backup_path)

3.6-3.10 其他子系统

• Multi-Agent协作：支持子Agent派发、并行任务执行
• Sandbox沙箱：Docker隔离，安全的工具执行环境
• Skill系统：可复用的能力包，支持插件化扩展
• 状态管理：多层状态追踪，支持任务中断恢复
• 日志与可观测性：完整的执行日志、性能追踪

四、44倍体积压缩的秘密：工程哲学的胜利

Claude Code有51.2万行TypeScript代码，OpenHarness只有1.1万行Python代码。为什么能做到98%的功能覆盖，体积却只有1/44？

4.1 语言层面的优势

Python的动态特性让代码更简洁。一个简单的对比：

// TypeScript: Claude Code中的工具定义
interface ToolDefinition {
  name: string;
  description: string;
  parameters: {
    type: "object";
    properties: Record<string, JSONSchema>;
    required?: string[];
  };
}

class ToolRegistry {
  private tools: Map<string, ToolDefinition> = new Map();
  
  register(tool: ToolDefinition): void {
    this.tools.set(tool.name, tool);
  }
  
  get(name: string): ToolDefinition | undefined {
    return this.tools.get(name);
  }
}

# Python: OpenHarness中的工具定义
@tool
def read_file(path: str, limit: int = None) -> str:
    """读取文件内容"""
    return open(path).read()[:limit]

# 自动推断参数类型和描述

Python的装饰器语法让工具定义变成了一行代码。

4.2 架构层面的极简

OpenHarness没有做"大而全"的平台，而是聚焦核心能力：

• 不做复杂的前端UI，只提供CLI和API
• 不做自己的模型，只做模型适配层
• 不做重型框架，只提供可组合的模块

4.3 兼容而非重新发明

OpenHarness完全兼容Claude Code生态：

• 支持anthropics/skills协议
• 支持Claude Code的CLAUDE.md格式
• 支持MCP协议标准

这意味着你现有的Claude Code配置、Skills、插件，可以直接迁移到OpenHarness使用。

五、实战：用OpenHarness构建你的第一个Agent

5.1 安装

git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness
pip install -e .

5.2 基础配置

创建配置文件 config.yaml：

model:
  provider: "openai"  # 或 "anthropic"
  api_key: "${API_KEY}"  # 从环境变量读取
  
harness:
  permission_mode: "ask"  # 每次工具调用询问用户
  
memory:
  persistence: true
  memory_file: "./MEMORY.md"

5.3 编写第一个Agent

from openharness import Agent, Tool

# 定义自定义工具
@Tool
def search_web(query: str) -> str:
    """搜索互联网获取信息"""
    import requests
    response = requests.get(f"https://api.search.com?q={query}")
    return response.json()["results"]

# 创建Agent
agent = Agent(
    name="research-assistant",
    tools=[search_web],
    system_prompt="你是一个研究助手，帮助用户搜索和整理信息。"
)

# 启动对话
async def main():
    response = await agent.run("帮我研究一下2026年AI Agent的发展趋势")
    print(response)

import asyncio
asyncio.run(main())

5.4 添加记忆能力

from openharness import Memory

agent = Agent(
    name="personal-assistant",
    tools=[...],
    memory=Memory(
        persistence=True,
        context_injection=True  # 自动注入MEMORY.md
    )
)

# 跨会话记忆
agent.remember("用户偏好使用Python，不喜欢JavaScript")
# 下次对话时，Agent会自动应用这个偏好

六、适用场景：谁应该用OpenHarness？

6.1 想要深入理解AI Agent的开发者

OpenHarness的代码结构清晰，文档完善，是学习AI Agent工程实现的最佳教材。相比闭源的Claude Code，你可以看到每一个设计决策背后的代码。

6.2 需要定制化Agent的企业

Claude Code是一个"黑盒"，很难深度定制。OpenHarness提供了：

• 完全可修改的代码
• 灵活的工具注册机制
• 可定制的权限控制
• 支持私有部署

6.3 研究人员和学者

MIT开源协议，支持学术研究和商业使用。OpenHarness提供了：

• 完整的测试套件（114个测试全部通过）
• 清晰的架构文档
• 可复现的实验环境

6.4 预算有限的个人开发者

Claude Code需要订阅Claude Pro，而OpenHarness支持任意LLM：

• OpenAI（GPT-4、GPT-4o）
• Anthropic（Claude）
• 本地模型（Ollama、LM Studio）
• 国内模型（DeepSeek、智谱、Kimi）

七、OpenHarness vs Claude Code：功能对比

八、总结：AI Agent开发的"乐高时代"

OpenHarness的出现，标志着AI Agent开发进入了一个新阶段——从"使用黑盒"到"理解原理"，从"被动接受"到"主动定制"。

1.1万行代码实现了51.2万行代码98%的核心能力，这不是简单的"压缩"，而是对AI Agent本质的深刻洞察——智能来自模型，能力来自架构，安全来自边界控制。

如果你正在探索AI Agent的世界，OpenHarness是一个绝佳的起点。它不会给你"开箱即用"的完美体验，但会给你"理解透彻"后的掌控感。

正如OpenHarness的slogan所说：

OpenHarness: Open Agent Harness — 让每个开发者都能构建自己的AI Agent。

项目地址：https://github.com/HKUDS/OpenHarness
文档：https://openharness.readthedocs.io
协议：MIT License

本文作者：三哥 | 发布时间：2026年4月8日