OpenHarness — 开放智能体运行框架

核心能力

五大 Harness 特性

OpenHarness 通过五个核心子系统，将大语言模型打造为功能完备的智能体。

🔄

智能体循环

流式工具调用循环
API 指数退避重试
并行工具执行
Token 计数与费用追踪

🔧

Harness 工具箱

43 个工具（文件、Shell、搜索、Web、MCP）
按需加载技能（.md）
插件生态系统
兼容 anthropics/skills

🧠

上下文与记忆

CLAUDE.md 发现与注入
上下文压缩（自动精简）
MEMORY.md 持久化记忆
会话恢复与历史记录

🛡️

安全治理

多级权限模式
路径级与命令级规则
PreToolUse / PostToolUse 钩子
交互式审批对话框

🤝

集群协调

子智能体生成与任务委派
团队注册与任务管理
后台任务生命周期
ClawTeam 集成（路线图）

概念

什么是智能体运行框架？

Agent Harness 是围绕大语言模型构建的完整基础设施，使其成为功能完备的智能体。模型提供智能，框架提供双手、眼睛、记忆和安全边界。

OpenHarness 是一个开源 Python 实现，面向研究者、开发者和社区设计。

🔍 理解生产级 AI 智能体底层的工作原理

🧪 实验前沿的工具、技能和智能体协调模式

🔌 扩展框架，添加自定义插件和领域知识

🏗️ 构建基于成熟架构的专用智能体

Harness 公式

🧠 LLM

🔧 工具

📚 知识

👁️ 观察

⚡ 行动

🛡️ 权限

🤖 智能体

开始使用

5 分钟快速上手

一条命令自动处理操作系统检测、依赖检查和安装。

TERMINAL

# 一键安装
$ curl -fsSL https://raw.githubusercontent.com/HKUDS/
    OpenHarness/main/scripts/install.sh | bash

# 或从源码安装（适合贡献者）
$ 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

# 启动 OpenHarness
$ oh
$ oh -p "检查这个仓库并列出前 3 个重构建议"
          

非交互模式

# 单次提示 → 标准输出
$ oh -p "解释这个代码库"

# JSON 输出，适合程序化使用
$ oh -p "列出 main.py 中的所有函数" --output-format json

# 实时流式 JSON 事件
$ oh -p "修复这个 bug" --output-format stream-json
          

环境检测

自动检测操作系统（Linux / macOS / WSL），验证 Python ≥ 3.10 和 Node.js ≥ 18

安装框架

通过 pip 安装 OpenHarness，设置 React TUI（npm install）

初始化配置

创建 ~/.openharness/ 配置目录，生成默认设置

配置提供商

设置 API 密钥，支持 Anthropic、Kimi、DashScope、DeepSeek 等

启动智能体

运行 oh 命令，开始智能体对话，或使用 -p 进行非交互调用

验证安装

通过 oh --version 确认安装成功

兼容性

提供商兼容

支持三种 API 格式，覆盖主流 LLM 服务商。

提供商	检测信号	说明
Anthropic	未设置自定义 BASE_URL	默认 Claude 设置
Moonshot / Kimi	BASE_URL 包含 `moonshot`	Anthropic 兼容端点
Vertex 兼容	URL 包含 `vertex` / `aiplatform`	Vertex 上的 Anthropic 网关
Bedrock 兼容	URL 包含 `bedrock`	Bedrock 风格部署
通用兼容	其他显式 BASE_URL	代理和内部网关

提供商	Base URL	示例模型
阿里云 DashScope	`dashscope.aliyuncs.com`	qwen3.5-flash、qwen3-max
DeepSeek	`api.deepseek.com`	deepseek-chat、deepseek-reasoner
OpenAI	`api.openai.com/v1`	gpt-4o、gpt-4o-mini
GitHub Models	`models.inference.ai.azure.com`	gpt-4o、Llama-3.1-405B
SiliconFlow	`api.siliconflow.cn/v1`	DeepSeek-V3
Groq	`api.groq.com/openai/v1`	llama-3.3-70b-versatile
Ollama（本地）	`localhost:11434/v1`	任意本地模型

功能	详情
认证方式	GitHub OAuth 设备流（无需 API 密钥）
令牌管理	自动刷新短期会话令牌
企业版	通过 `--github-domain` 支持 GitHub Enterprise
模型	使用 Copilot 默认模型选择
API	底层为 OpenAI 兼容 Chat Completions

架构

Harness 架构

通过 10 个子系统实现核心 Agent Harness 模式。

openharness/ engine/ — 🧠 智能体循环：查询 → 流式 → 工具调用 → 循环 tools/ — 🔧 43 个工具：文件 I/O、Shell、搜索、Web、MCP skills/ — 📚 知识系统：按需加载技能（.md 文件） plugins/ — 🔌 扩展：命令、钩子、智能体、MCP 服务器 permissions/ — 🛡️ 安全：多级模式、路径规则、命令拒绝 hooks/ — ⚡ 生命周期：PreToolUse / PostToolUse commands/ — 💬 54 个命令：/help、/commit、/plan 等 mcp/ — 🌐 MCP：Model Context Protocol 客户端 memory/ — 🧠 记忆：持久化跨会话知识 tasks/ — 📋 任务：后台任务管理 coordinator/ — 🤝 多智能体：子智能体、团队协调 prompts/ — 📝 上下文：系统提示词、CLAUDE.md、技能 config/ — ⚙️ 设置：多层配置、迁移 ui/ — 🖥️ React TUI：后端协议 + 前端

用户提示

→

CLI / React TUI

RuntimeBundle

→

QueryEngine

API 客户端

→

tool_use

工具注册表

→

权限 + 钩子

执行工具

→

结果 → 循环

智能体循环核心

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)
          

工具与能力

43+ 内置工具

涵盖文件操作、搜索、智能体协调、任务管理、MCP 集成等全方位能力。

📁 文件 I/O

Bash · Read · Write · Edit · Glob · Grep

带权限检查的核心文件操作

🔍 搜索

WebFetch · WebSearch · ToolSearch · LSP

Web 和代码搜索能力

📓 笔记本

NotebookEdit

Jupyter 笔记本单元格编辑

🤖 智能体

Agent · SendMessage · TeamCreate/Delete

子智能体生成与协调

📋 任务

TaskCreate · Get · List · Update · Stop · Output

后台任务管理

🌐 MCP

MCPTool · ListMcpResources · ReadMcpResource

Model Context Protocol 集成

🔀 模式

EnterPlanMode · ExitPlanMode · Worktree

工作流模式切换

⏰ 调度

CronCreate · List · Delete · RemoteTrigger

定时与远程执行

⚙️ 元操作

Skill · Config · Brief · Sleep · AskUser

知识加载、配置、交互

📚 技能系统

技能是按需加载的知识 — 仅在模型需要时加载。兼容 anthropics/skills，只需将 .md 文件复制到 ~/.openharness/skills/

commit review debug plan test simplify pdf xlsx 40+ 更多

🔌 插件系统

兼容 claude-code 插件。已测试 12 个官方插件。

commit-commands命令
security-guidance钩子
hookify命令 + 智能体
code-review智能体
pr-review-toolkit智能体
feature-dev命令

安全

权限系统

多级安全机制，细粒度控制每一次工具调用。

默认默认模式

写入 / 执行前询问，适用于日常开发

自动自动模式

允许所有操作，适用于沙箱环境

计划计划模式

阻止所有写入，适用于大型重构前审查

settings.json

{
  "permission": {
    "mode": "default",
    "path_rules": [
      {"pattern": "/etc/*", "allow": false}
    ],
    "denied_commands": [
      "rm -rf /",
      "DROP TABLE *"
    ]
  }
}
          

质量保障

测试结果

全面的测试覆盖，确保每一个 Harness 子系统稳定可靠。

114

单元 + 集成测试

核心逻辑覆盖

✓ 全部通过

CLI 参数 E2E

真实模型调用

✓ 全部通过

Harness 功能 E2E

重试、技能、并行、权限

✓ 全部通过

React TUI E2E

欢迎界面、对话、状态

✓ 全部通过

TUI 交互 E2E

命令、权限、快捷键

✓ 全部通过

真实插件测试

anthropics/skills + claude-code/plugins

✓ 全部通过

扩展

扩展 OpenHarness

通过自定义工具、技能和插件，让框架适应你的需求。

🔧 自定义工具

基于 Pydantic 的类型安全工具定义，继承 BaseTool 即可快速创建。

my_tool.py

class MyTool(BaseTool):
    name = "my_tool"
    description = "执行有用操作"

    async def execute(self, args, ctx):
        return ToolResult(
            output=f"结果: {args.query}"
        )
          

📚 自定义技能

创建 Markdown 文件，定义领域专家知识，按需加载。

my-skill.md

---
name: my-skill
description: 领域专家指导
---

# 我的技能

## 何时使用
当用户询问关于 [领域] 的问题时
          

🔌 自定义插件

在 commands/ 中添加命令，在 hooks/ 中添加钩子，在 agents/ 中添加智能体。

plugin.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description":
    "我的自定义插件"
}
          

社区

参与贡献

OpenHarness 是一个社区驱动的研究项目，我们欢迎各领域的贡献。

🔧

工具

面向特定领域的新工具实现

📚

技能

金融、科学、DevOps 等领域知识

🔌

插件

命令、钩子、智能体工作流

🤖

提供商

支持更多 LLM 后端

🤝

多智能体

协调协议、团队模式

🧪

测试

E2E 场景、基准测试

📖

文档

架构指南、教程、翻译

开发环境设置

$ git clone https://github.com/HKUDS/OpenHarness.git
$ cd OpenHarness
$ uv sync --extra dev
$ uv run pytest -q  # 验证一切正常
      

开放智能体运行框架 oh

五大 Harness 特性

智能体循环

Harness 工具箱

上下文与记忆

安全治理

集群协调

什么是智能体运行框架？

Harness 公式

5 分钟快速上手

环境检测

安装框架

初始化配置

配置提供商

启动智能体

验证安装

提供商兼容

Harness 架构

43+ 内置工具

📁 文件 I/O

🔍 搜索

📓 笔记本

🤖 智能体

📋 任务

🌐 MCP

🔀 模式

⏰ 调度

⚙️ 元操作

📚 技能系统

🔌 插件系统

权限系统

默认 默认模式

自动 自动模式

计划 计划模式

测试结果

扩展 OpenHarness

🔧 自定义工具

📚 自定义技能

🔌 自定义插件

参与贡献

工具

技能

插件

提供商

多智能体

测试

文档

开放智能体
运行框架 oh

默认默认模式

自动自动模式

计划计划模式