项目概述
香港大学数据科学研究所（HKUDS）近期开源了一个新项目 OpenHarness，短短两天就获得了 1.9K Star。这个团队之前已经有不少知名项目，包括 LightRAG、AutoAgent、Nanobot 和 CLI-Anything。
OpenHarness 的定位非常独特：它不是一个新的 Agent，而是一个"Agent Harness"——给模型穿上的"马甲"。模型负责思考，Harness 提供手、眼、记忆和安全边界。
什么是 Agent Harness？
OpenHarness 的核心理念可以用一句话概括：The model is the agent. The code is the harness.
这个理念把 Agent 系统清晰地拆分为两个层次：
- 模型层（Agent）：提供推理、规划、决策能力
- 框架层（Harness）：提供工具调用、权限控制、记忆存储、多 Agent 协调
一个纯聊天模型只能输出文本。当模型接入 Harness 后，它获得了文件读写、命令执行、网络请求、持久记忆等能力——从"会说"变成"能做"。
苏米注：这个设计思路非常清晰，把模型和框架的职责边界划分得很明确，便于开发者理解和扩展。
为什么需要 OpenHarness？
看看这组数据对比：
- Claude Code：Anthropic 官方代码助手，51 万行代码、1884 个文件
- OpenHarness：1.1 万行 Python 代码，重新实现核心架构
Claude Code 功能强大，但庞大的代码库让想学习 Agent 架构的开发者望而却步。OpenHarness 砍掉了遥测、OAuth、重型 React UI 等企业级功能，只保留最核心的 Harness 架构，让开发者能够真正理解 Agent 内部是如何工作的。
10 大核心子系统
1. Engine（智能体循环）
这是整个框架的心脏，一个简洁的循环处理无限组合：
while True:
response = await api.stream(messages, tools)
if response.stop_reason != "tool_use":
break # 模型完成任务
for tool_call in response.tool_uses:
result = await harness.execute_tool(tool_call)
messages.append(tool_results)模型决定"做什么"，Harness 负责"怎么做"——包括权限校验、执行、结果格式化。
2. Tools（43 个工具）
涵盖文件 I/O、Shell、搜索、Web、MCP 协议等：
- 文件操作：Read、Write、Edit、Glob、Grep
- Shell 执行：Bash 命令，带权限控制
- 搜索：WebFetch、WebSearch、ToolSearch
- Agent 协作：Agent、SendMessage、TeamCreate
- 任务管理：TaskCreate/Get/Update/Stop/Output
- MCP 协议：MCPTool、ListMcpResources
每个工具都自带 Pydantic 输入验证、JSON Schema 自描述、权限集成和钩子支持。
3. Skills（按需加载的技能）
Skills 是按需加载的领域知识，只用.md 文件就能定义。OpenHarness 兼容 anthropics/skills 格式，只需把.md 文件复制到~/.openharness/skills/目录即可。
内置技能包括：
commit：创建清晰的 git 提交review：代码审查debug：系统地诊断和修复 bugplan：编码前设计实现方案test：编写和运行测试simplify：重构代码使其更简洁可维护
4. Plugins（插件系统）
OpenHarness 兼容 claude-code 插件生态，已测试 12 个官方插件：
| 插件 | 类型 | 功能 |
|---|---|---|
| commit-commands | Commands | Git 工作流 |
| security-guidance | Hooks | 文件编辑安全警告 |
| hookify | Commands + Agents | 创建自定义行为钩子 |
| feature-dev | Commands | 功能开发工作流 |
| code-review | Agents | 多 Agent PR 审查 |
| pr-review-toolkit | Agents | 专业 PR 审查 Agent |
5. Permissions（权限管控）
三级权限模式：
| 模式 | 行为 | 适用场景 |
|---|---|---|
| Default | 写入/执行前询问 | 日常开发 |
| Auto | 全部允许 | 沙箱环境 |
| Plan | 阻止所有写入 | 代码审查 |
还支持路径级规则配置：
{
"permission": {
"mode": "default",
"path_rules": [{"pattern": "/etc/*", "allow": false}],
"denied_commands": ["rm -rf /", "DROP TABLE"]
}
}6. Hooks（生命周期钩子）
支持 PreToolUse/PostToolUse 生命周期钩子，可以在工具执行前后插入自定义逻辑。
7. Commands（54 个斜杠命令）
像聊天一样控制 Agent，支持/help、/commit、/plan、/resume等常用命令。
8. MCP（Model Context Protocol）
支持 Model Context Protocol 客户端，可以接入外部 MCP 服务器。
9. Memory（持久记忆）
用 MEMORY.md 存储跨会话的持久知识，支持会话恢复和历史记录。
10. Coordinator（多 Agent 协调）
支持子 Agent 派发、团队管理、任务调度，ClawTeam 集成也在路线图中。
快速上手
安装
# 克隆项目
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness
# 安装依赖（包含开发工具）
uv sync --extra dev配置模型
以 Kimi 为例：
export ANTHROPIC_BASE_URL=https://api.moonshot.cn/anthropic
export ANTHROPIC_API_KEY=your_kimi_api_key
export ANTHROPIC_MODEL=kimi-k2.5一键启动
# 如果激活了虚拟环境
oh
# 或者直接用 uv 运行
uv run oh非交互式模式
# 单次提示 → 标准输出
oh -p "Explain this codebase"
# JSON 输出，用于编程使用
oh -p "List all functions in main.py" --output-format json
# 实时流式 JSON 事件
oh -p "Fix the bug" --output-format stream-json插件管理
# 列出插件
oh plugin list
# 安装插件
oh plugin install
# 启用插件
oh plugin enable 扩展 OpenHarness
添加自定义工具
from pydantic import BaseModel, Field
from openharness.tools.base import BaseTool, ToolExecutionContext, ToolResult
class MyToolInput(BaseModel):
query: str = Field(description="Search query")
class MyTool(BaseTool):
name = "my_tool"
description = "Does something useful"
input_model = MyToolInput
async def execute(self, arguments: MyToolInput, context: ToolExecutionContext) -> ToolResult:
return ToolResult(output=f"Result for: {arguments.query}")添加自定义技能
创建~/.openharness/skills/my-skill.md：
---
name: my-skill
description: Expert guidance for my specific domain
---
# My Skill
## When to use
Use when the user asks about [your domain].
## Workflow
1. Step one
2. Step two
...添加自定义插件
创建.openharness/plugins/my-plugin/.claude-plugin/plugin.json：
{
"name": "my-plugin",
"version": "1.0.0",
"description": "My custom plugin"
}在commands/*.md中添加命令，在hooks/hooks.json中添加钩子，在agents/*.md中添加 Agent。
总结
OpenHarness 的出现，让人想起了 Linux 刚诞生时的那句话："Just for fun"。
它不是要取代 Claude Code，而是给开发者一个可理解、可修改、可扩展的 Agent 框架参考。在 AI Agent 这个领域，我们需要的不只是好用的产品，更需要清晰的架构、可学习的代码、开放的生态。
苏米注：OpenHarness 把 Agent 从黑盒变成了白盒，用 1.1 万行代码重新实现了 Claude Code 的核心架构。对于想学习 Agent 开发或构建自己 Agent 的开发者来说，这是一个非常宝贵的学习资源。代码不长，但信息量很大，值得深入研读。
项目地址：https://github.com/HKUDS/OpenHarness