港大开源轻量级AI Agent框架OpenHarness使用指南

近日，AI Agent 领域迎来一款值得关注的开源新框架。香港大学数据智能实验室（HKUDS）正式发布了 OpenHarness，这是一个采用纯 Python 编写的轻量级 AI Agent 开发框架。其核心代码仅约 1.2 万行，却实现了与 Claude Code 近 98% 的核心工具能力兼容。对于寻求强大工作流能力，同时又希望框架保持简洁、易于理解和二次开发的工程师与研究者而言，OpenHarness 提供了一个极具吸引力的新选择。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

OpenHarness是什么

OpenHarness 是一个致力于实现“轻量级”与“高性能”平衡的 AI Agent 框架。其核心设计目标是：在保留企业级功能的同时，追求极致的代码简洁性与运行效率。该项目采用宽松的 MIT 开源协议，其架构哲学基于“Agent Harness”（智能缰绳）理念，即将大语言模型的“决策思考”层与“工具执行”层进行清晰分离。模型专注于规划“做什么”（What），而框架则负责安全、可靠地处理“如何做”（How）。

该框架的一大亮点是其卓越的生态兼容性。它不仅原生兼容 Anthropic 的 Skills 技能格式与 Claude Code 的插件生态，更能通过简单的环境变量配置，无缝切换至 Kimi、DeepSeek、Ollama 等任何符合 OpenAI API 标准的模型服务端点，真正实现了后端模型的灵活中立。

OpenHarness的主要功能

尽管代码量精简，但 OpenHarness 的功能模块却相当完备，主要涵盖以下核心能力：

1. 健壮的 Agent 核心循环：框架内置了流式工具调用、指数退避重试、并行执行等生产级特性，并集成了实时的 Token 消耗统计与成本追踪功能。同时支持上下文自动压缩与“断点续聊”机制，有效管理长对话场景。

2. 丰富的内置工具集：提供了超过 43 个开箱即用的工具，覆盖文件读写、Shell 命令执行、网络搜索、浏览器自动化、MCP 协议支持、Notebook 交互等常见开发场景，宣称复现了 Claude Code 98% 的实用工具能力。

3. 即插即用的技能系统：技能以 Markdown 文档形式存储，支持动态加载。该系统完全兼容 anthropics/skills 官方仓库，开发者可直接复用社区上千个成熟技能，并利用 Pydantic 实现严格的参数类型校验。

4. 持久的记忆与上下文管理：项目初始化时会自动注入 CLAUDE.md 中定义的项目规则，并通过 SQLite 数据库持久化保存 MEMORY.md 记忆文件，实现跨会话的长期记忆。上下文管理支持模板化配置，灵活性高。

5. 多 Agent 协同工作流：支持创建子 Agent 并进行任务委派，通过 Swarm 模式进行多智能体团队协作与调度。后台任务的生命周期管理已内置，未来计划集成 ClawTeam 以增强协同能力。

6. 细致的权限治理体系：提供了从宽松到严格的四级权限模式（默认、自动、计划、严格），支持路径级访问规则、命令白名单控制，甚至交互式审批弹窗。通过预执行和后执行工具钩子，可对敏感操作进行拦截与审计。

7. 高度可扩展的插件系统：兼容 claude-code/plugins 插件格式，允许开发者自定义命令、钩子函数、Agent 类型以及集成 MCP 服务器，具备强大的扩展能力。

OpenHarness的技术原理

理解其底层技术设计，便能知晓其实现轻量化的秘诀。

架构设计：Harness 模式：这是框架的核心思想。框架作为“缰绳”（Harness），将 LLM 的智能决策与具体的工具执行、记忆存储、安全边界解耦。这种分离带来了清晰的职责划分与完整的系统可观测性。

核心循环：标准的 ReAct 范式：其工作流遵循经典的 ReAct（推理-行动）模式：LLM 输出 JSON 格式的工具调用指令 → Harness 解析并安全执行 → 流式返回结果给 LLM。此循环持续进行，直至模型主动终止。

模块化子系统：整个框架由超过 10 个独立的子系统构成，包括引擎、工具注册表、技能加载器、权限治理等。各层通过明确定义的接口解耦，这是其保持架构清晰与高可维护性的关键。

轻量级工程实现：这是与 Claude Code 最显著的差异。它完全采用 Python 3.10+ 编写，总计 11,733 行代码，体积仅为 Claude Code 的 1/44。它有意剔除了企业级应用中常见的遥测、OAuth 认证和数百个 React 组件等“臃肿”部分，仅保留一个可选的 React TUI 前端，通过标准输入输出与后端通信。

如何使用OpenHarness

上手 OpenHarness 的步骤非常清晰：

1. 环境准备：确保 Python 版本在 3.10 以上，并通过 pip install uv 安装 uv 包管理器。同时，准备好你的 LLM API 密钥。
2. 安装项目：使用 uv init my-project && cd my-project 初始化项目，然后运行 uv add "hkuds/openharness[cli]" 安装框架和 CLI。
3. 配置密钥：通过环境变量 export ANTHROPIC_API_KEY=sk-... 设置密钥。如果想用 Kimi、DeepSeek 等其他模型，还需额外设置 ANTHROPIC_BASE_URL 指向对应端点。
4. 初始化项目：运行 oh init，它会自动生成 CLAUDE.md（项目规则）和 MEMORY.md（记忆文件）的模板。
5. 启动与体验：使用 oh run --model claude-3.5-sonnet 开始交互，或用 oh demo 快速体验演示任务。
6. 扩展使用：将 .md 技能文件放入指定目录即可自动加载；通过 --permissions strict 参数开启严格管控模式；在 Swarm 模式下进行多 Agent 任务委派。

OpenHarness的项目地址

• GitHub仓库：https://github.com/HKUDS/OpenHarness

OpenHarness的核心优势

综合来看，OpenHarness 的优势集中在以下几点：

• 极致轻量：44 倍的代码压缩比是其最大卖点，让阅读源码、二次开发和学习 Agent 原理的门槛大幅降低。
• 生态兼容：几乎无缝对接 Claude Code 的工作流和技能生态，对于已有相关经验的开发者来说迁移成本极低。
• 模型中立：不绑定任何特定厂商，通过一个环境变量就能切换后端模型，提供了极大的灵活性。
• 开箱即用的安全：内置了多层权限治理和交互确认机制，在本地运行时可以设定严格模式，让人更放心。
• 测试完备：包含了 114 个单元测试和 6 个端到端测试套件，这在开源 AI Agent 项目中难能可贵，也为代码质量提供了保障。

OpenHarness的关键信息和使用要求

在决定采用前，有几个关键点需要明确：

• 项目状态：由香港大学数据智能实验室于 2026 年 4 月初开源，目前版本为 v0.1.0，处于早期但活跃阶段。
• 技术栈：强制要求 Python 3.10+ 和 uv 包管理器，不支持传统的 pip 直接安装。
• 模型配置：虽然支持多模型，但配置上统一使用 ANTHROPIC_* 系列环境变量来指向不同的端点，需要稍加适应。
• 网络要求：部分工具如网络搜索需要联网，但若完全使用本地模型（如 Ollama），核心功能可离线运行。

OpenHarness的同类竞品分析

要看清 OpenHarness 的定位，最好的方式是与当前主流方案进行对比。

从对比中不难看出，OpenHarness 在“轻量”、“灵活”和“学习成本”上找到了一个独特的平衡点，尤其适合那些希望深入 Agent 内部机制，或需要高度定制化、模型无关解决方案的开发者。

OpenHarness的应用场景

基于其特性，OpenHarness 能在多个场景中发挥作用：

• AI Agent 研究与原型开发：其精简的代码库是研究 Agent 核心机制（如工具调用、记忆、多 Agent 协调）的理想沙盒，避免了从数十万行企业级代码中抽丝剥茧的痛苦。
• 本地私有化智能助手：结合 Ollama 等本地模型，可以在完全离线的环境中部署一个功能强大的代码助手，满足金融、医疗等行业对数据隐私的苛刻要求。
• CI/CD 自动化流水线：其无头模式能输出结构化 JSON，非常适合集成到 GitHub Actions 等 CI/CD 流程中，自动执行代码审查、生成测试用例或更新文档。
• 多 Agent 协作系统：Swarm 模式使得构建一个能分解复杂任务、并行执行的智能团队成为可能，可用于竞品分析、多源信息调研等场景。
• 技能驱动的领域专用工具：通过加载现成的或自建的 Markdown 技能，可以快速打造一个精通特定领域（如数据分析、DevOps）的专属助手。
• 开发者 CLI 工作流增强：直接嵌入终端工作流，用自然语言替代复杂的 Shell 命令，处理文件批量操作、代码重构等日常开发任务，提升效率。

总而言之，OpenHarness 的出现，为 AI Agent 领域提供了一个“小而美”的新选项。它未必适合所有场景，但对于追求可控性、轻量化和模型自由的开发者及研究者而言，无疑是一个值得投入时间探索的框架。