OpenHarness

OpenHarness – 港大开源的轻量级 AI Agent 框架

OpenHarness：香港大学开源的轻量级 Python AI Agent 框架，赋能智能开发新纪元

在人工智能飞速发展的浪潮中，AI Agent 的构建与应用已成为行业焦点。香港大学数据智能实验室（HKUDS）在此背景下，重磅推出了其开源项目 OpenHarness。这款框架以纯 Python 实现，代码量精简至 11,733 行，仅为 Claude Code 体积的 1/44，却成功复刻了 Claude Code 98% 的核心工具能力（涵盖 43 种工具）和 61% 的命令集（共 54 条命令）。OpenHarness 秉持 MIT 许可协议，借鉴了“Agent Harness”的先进架构理念，旨在为大型语言模型（LLM）提供强大的工具调用、持久化记忆、精细化权限管理以及多 Agent 协同工作能力。尤为值得一提的是，它完美兼容 Anthropic Skills 和 Claude Code 的插件生态，并通过简单的环境变量配置，即可无缝切换至包括 Kimi、DeepSeek、Ollama 在内的任何 OpenAI 兼容模型，极大地提升了灵活性和开放性。

OpenHarness 核心亮点解析

• 智能 Agent 核心循环：OpenHarness 精心设计了 Agent 的核心运行机制，支持流式工具调用、指数级退避重试策略、高效的并行执行能力。同时，它具备实时 Token 消耗追踪与成本估算，并能智能地对上下文进行压缩，有效延长对话长度，更支持断点续聊，确保用户体验的流畅性。
• 功能丰富的工具集：框架内置了超过 43 种核心工具，涵盖了文件输入输出、Shell 命令执行、网络搜索、浏览器自动化操作、MCP 协议通信、Notebook 编辑、任务调度以及 Cron 定时任务等广泛领域，几乎完整复现了 Claude Code 的强大工具能力。
• 灵活的技能调用系统：OpenHarness 支持通过 Markdown 文件按需加载技能，并与 anthropics/skills 生态高度兼容。借助 Pydantic 进行类型校验，开发者可以轻松复用 Anthropic 官方及社区提供的海量（1000+）技能库，极大地加速了开发进程。
• 强大的记忆与上下文管理：项目自动注入 CLAUDE.md 文件中的项目规则，并能将跨会话的 MEMORY.md 记忆文件持久化存储。此外，它还支持 MEMORY_PLACEHOLDER 模板化上下文管理，使得 Agent 能够持续学习并保持对话的连贯性。
• 智能多 Agent 协同：OpenHarness 提供了强大的多 Agent 协调能力，支持子 Agent 的生成与任务委派，以及团队注册表的管理。其后台任务生命周期管理功能，为构建复杂的分布式 AI 系统奠定了基础。未来规划中，还将集成 ClawTeam，进一步增强团队协作能力。
• 精细化的权限治理：框架内置了多层级的权限控制模式，包括默认模式、自动模式、计划模式和严格模式，为 Agent 的行为提供了多重安全保障。用户可以设定细致到路径级别的规则、命令白名单，甚至通过交互式审批对话框来控制 Agent 的操作，还可以利用预/后工具钩子进行精细化控制。
• 高度可扩展的插件机制：OpenHarness 兼容 claude-code/plugins 的格式，允许开发者自定义命令、钩子、Agent 类以及 MCP 服务器扩展。这使得用户能够根据自身需求，灵活地扩展 Agent 的功能。

OpenHarness 的技术内核

• “Agent Harness”架构模式：OpenHarness 采用了创新的“Harness”设计模式，将 LLM 的“智能层”（即模型本身）与“执行层”（包括工具、记忆、安全边界等）进行了清晰的解耦。模型专注于决策“做什么”，而 Harness 则负责安全、高效地执行“如何做”，并提供全面的可观测性。
• 标准 ReAct Agent 循环：框架实现了标准的 ReAct（Reasoning and Acting）工具调用循环。LLM 输出 JSON 格式的工具调用指令，Harness 解析并并行执行，然后将结果流式返回。这一循环持续进行，直到模型明确停止调用工具，期间自动处理重试和 Token 计数。
• 模块化子系统设计：OpenHarness 由超过 10 个且接口明确的子系统构成，包括核心的 Engine（循环引擎）、Tools（工具注册表）、Skills（技能加载器）、Plugins（扩展钩子）、Permissions（权限管理）、Hooks（生命周期）、Memory（记忆模块）、Coordinator（多 Agent 协调）以及 MCP（模型上下文协议客户端）等。这种模块化设计极大地提高了代码的可维护性和可扩展性。
• 智能上下文与记忆管理：通过 Token 预算机制（例如将 128k Token 限制压缩至 80k），OpenHarness 能够有效管理上下文长度。它会自动集成 CLAUDE.md 项目规则，利用 SQLite 持久化 MEMORY.md 文件以实现跨会话记忆，并支持上下文自动压缩和断点续聊。
• 钩子驱动的权限与治理：通过 PreToolUse 和 PostToolUse 生命周期钩子，OpenHarness 能够对工具调用进行拦截和干预。这支持了多层权限模式、路径级规则匹配、命令白名单以及交互式审批流程，确保了 Agent 操作的安全性与可控性。
• Swarm 模式下的多 Agent 协调：Swarm 模式通过注册表管理子 Agent 身份，利用 JSON Payload 进行任务委派。基于 Python 的 Asyncio 协程，它能够高效管理后台任务和并行研究子任务，特别适用于需要并行处理的复杂场景。
• 模型中立与广泛兼容性：通过环境变量（如 ANTHROPIC_BASE_URL/ANTHROPIC_MODEL）的设置，OpenHarness 可以轻松切换至任意 OpenAI 兼容的 API 端点，如 Kimi、DeepSeek、Ollama 等。其工具调用采用标准的 JSON Schema，技能和插件格式也与 anthropics/skills 和 claude-code/plugins 生态兼容。
• 极致轻量化工程实践：OpenHarness 完全采用 Python 3.10+ 开发，并使用 uv 包管理器实现零锁文件安装。其 11,733 行代码，剔除了企业级应用中常见的遥测、OAuth 等冗余功能，只保留了核心的 Agent 能力。它甚至保留了 React TUI 作为可选的前端界面，并通过标准输入输出协议与后端进行通信。

OpenHarness 的使用指南

• 环境准备：确保您的系统安装了 Python 3.10 或更高版本。使用 pip install uv 安装 uv 包管理器。同时，准备好您选择的大型语言模型 API 密钥（支持 Anthropic 或任何 OpenAI 兼容端点）。
• 项目安装：在您的项目目录下，执行 uv init my-project && cd my-project 来初始化项目。随后，运行 uv add "hkuds/openharness[cli]" 来安装 OpenHarness 及其命令行接口依赖。
• 配置 API 密钥：通过设置环境变量 export ANTHROPIC_API_KEY=sk-... 来配置您的 API 密钥。如果您使用的是 Moonshot、DeepSeek 等其他模型，还需要设置 export ANTHROPIC_BASE_URL=... 指向其对应的 API 端点。
• 项目初始化配置：执行 oh init 命令。该命令会自动生成 CLAUDE.md（项目规则文件）和 MEMORY.md（记忆文件模板），完成项目的初始配置。
• 启动交互式会话：运行 oh run --model claude-3.5-sonnet 来进入交互式会话模式。您也可以执行 oh demo 来运行内置的演示任务，快速体验 OpenHarness 的核心功能。
• 加载自定义技能：将您的 .md 技能文件放置在 skills/ 目录或用户配置的 ~/.openharness/skills/ 目录下。系统将自动识别并按需加载，确保与 anthropics/skills 生态的无缝衔接。
• 精细化权限管理：通过运行 oh run --permissions strict 来启用严格的治理模式。对于自动化或 CI/CD 场景，可以使用 oh -p "提示词" --output-format json 命令，实现无头模式下的结构化结果输出。
• 实现多 Agent 协作：利用 Swarm 模式创建子 Agent 并进行任务委派。通过 Asyncio 协程管理后台任务的生命周期，并支持并行研究子任务，构建更复杂的 Agent 协作系统。

OpenHarness 的独特优势

• 极致轻量与高效：代码量仅为 Claude Code 的 1/44，163 个文件，纯 Python 3.10+ 技术栈，摒弃了企业级开发中的冗余功能，实现了真正的轻量级。
• 广泛的生态兼容性：高度复刻 Claude Code 的工作流，支持 12+ 官方插件，Skills 即插即用，显著降低了迁移和学习成本。
• 模型选择的度：不局限于 Anthropic 模型，通过简单的 ANTHROPIC_BASE_URL 配置，即可轻松切换至 Moonshot、DeepSeek 等任意兼容的 OpenAI 端点。
• 内置的安全保障：提供预/后工具钩子、路径级权限规则、敏感操作交互确认等机制，本地运行模式下可配置严格模式，确保 Agent 操作的安全可控。
• 完善的测试覆盖：拥有 114 个单元测试和 6 个端到端（E2E）测试套件，为项目的稳定性和可靠性提供了有力保障（Claude Code 缺乏此类测试覆盖）。

OpenHarness 的关键信息与使用要求

• 项目背景与许可：由香港大学数据智能实验室（HKUDS）于 2026 年 4 月 1 日开源，采用 MIT 许可协议。目前版本 v0.1.0 处于早期发展阶段，GitHub 社区已有约 1,300 颗星的关注。
• 技术规格概览：纯 Python 3.10+ 实现，代码量 11,733 行，163 个文件。使用 uv 包管理器进行安装，支持零锁文件依赖。
• 架构定位：遵循“Agent Harness”架构，将 LLM 的智能层与执行层进行分离。复刻了 Claude Code 98% 的工具能力（43 个工具）和 61% 的命令集（54 条命令）。
• 模型兼容性：原生支持 Anthropic API，通过 ANTHROPIC_BASE_URL 环境变量可无缝切换至 Moonshot、DeepSeek、OpenRouter、Ollama 等任意 OpenAI 兼容端点。
• 生态系统集成：兼容 anthropics/skills 技能生态（1000+ 插件）和 claude-code/plugins 扩展格式，并支持 MCP 协议集成。
• 测试覆盖率：包含 114 个单元测试和 6 个 E2E 测试套件，显著优于 Claude Code。
• 环境依赖项：要求 Python 3.10+，必须安装 uv 包管理器（pip install uv），不支持直接通过 pip 安装。
• API 配置要求：需要准备 LLM API 密钥并设置 ANTHROPIC_API_KEY 环境变量。使用非 Anthropic 模型时，需额外配置 ANTHROPIC_BASE_URL 和 ANTHROPIC_MODEL。
• 项目初始化步骤：首次使用前，必须运行 oh init 命令，生成 CLAUDE.md（项目规则）和 MEMORY.md（记忆文件）模板。
• 网络连接需求：Web 搜索、浏览器自动化、MCP 服务器等工具需要互联网连接。但核心功能在配置本地 Ollama 时，可完全离线运行。

OpenHarness 与同类竞品的对比分析

OpenHarness 的应用场景展望

• AI Agent 的研究与原型开发：得益于其精简的代码库（11,733 行 Python 代码），研究人员可以深入理解 Agent 的循环机制、工具调用逻辑以及记忆管理。这为快速验证多 Agent 协同、上下文压缩等前沿 AI 思想提供了便利，无需应对 TypeScript 和复杂企业级代码的挑战。
• 本地化与私有化的智能助手：通过配置本地 Ollama 模型，OpenHarness 可以在内网或离线环境下运行，满足金融、医疗等对数据安全有严格要求的行业需求。同时，它保留了 Claude Code 级别的代码编辑和文件操作能力，为用户提供强大的本地智能助手。
• CI/CD 自动化流水线集成：借助其无头模式（oh -p "提示词" --output-format json），OpenHarness 可以无缝集成到 GitHub Actions、GitLab CI 等自动化流程中。它能够执行代码审查、自动化测试用例生成、文档更新等任务，并将结构化结果反馈给下游步骤，实现高效的开发运维一体化。
• 构建复杂的多 Agent 协作系统：利用 Swarm 模式，用户可以创建并协调多个子 Agent，委派它们并行执行任务，例如同时检索多个代码库信息或对比不同技术方案。这使得 OpenHarness 成为构建复杂研发任务分解与协作系统的理想选择，能够替代部分传统的流程编排工具。
• 开发领域专用工具：通过加载 anthropics/skills 生态中的 Markdown 技能文件（如数据分析、网络、API 测试等），可以快速构建针对特定技术栈（Python、React、Docker 等）的定制化 AI 助手，极大地提升了开发效率。
• 增强开发者终端工作流：将 OpenHarness 集成到日常的命令行操作中，可以替代部分手动执行的 Shell 命令。它支持自然语言指令转换为命令执行、批量文件重命名、代码重构建议、Git 提交信息自动生成等高频开发任务，显著优化了开发者的工作流程。