AIAgent开发新选择：OpenHarness极简入门指南

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

 在 AI Agent 开发领域，Harness 工程已成为打通“模型能力”与“实际应用”的核心基础设施——它为大模型提供工具、记忆、权限边界，让模型从“只能对话”升级为“能落地干活”的功能性 Agent。而 OpenHarness 作为香港大学数据智能实验室（HKUDS）开源的轻量级 AI Agent 框架，以仅 1.1 万行代码的极致轻量化，复刻了 Claude Code 98% 的核心能力，同时支持本地离线部署、多模型灵活切换，成为开发者、极客玩家的首选工具。

本文将从环境准备、部署安装、基础使用到进阶技巧，手把手教你上手 OpenHarness，全程无复杂操作，新手也能快速落地，让你轻松解锁 AI Agent 的高效开发体验。

在接触部署安装前，先简单了解 OpenHarness 的核心优势，帮你明确它的适用场景，避免盲目上手：

极致轻量，开箱即用：仅 1.1 万行 Python 代码，是 Claude Code 代码量的 1/44，无需复杂依赖，安装后可直接启动使用，不用漫长等待编译部署。
多模型兼容，灵活切换：支持 Claude、Kimi、DeepSeek、Ollama 等多种 OpenAI 兼容模型，一个命令就能切换后端模型，适配不同开发需求与隐私场景。
工具与技能生态完善：内置 43+ 实用工具，覆盖文件操作、Shell 命令、Web 搜索等常见场景；同时兼容 Claude Skills 生态，1000+ 技能可即插即用，无需重复开发。
安全可控，支持离线部署：具备四级权限模式，敏感操作需手动确认，避免误操作；配置本地 Ollama 端点后可完全离线运行，数据不出域，适合金融、医疗等敏感行业使用。
记忆持久，会话无缝衔接：通过 SQLite 实现跨会话记忆持久化，能记住项目规则与操作历史，下次启动无需重新配置，提升开发效率。

简单来说，如果你追求轻量可控、需要本地离线部署，或想研究 AI Agent 内部原理，OpenHarness 绝对是比 Claude Code 更合适的选择；若是个人提效、简单自动化任务，它也能快速满足需求。

OpenHarness 基于 Python 开发，部署前需确保环境满足以下要求，避免安装过程中出现兼容性问题，建议严格对照配置：

2.1 硬件要求（最低配置）

CPU：Intel i5 及以上，或 AMD 同等性能处理器（推荐多核心，提升工具并行执行效率）；
内存：8GB 及以上（若需运行本地模型如 Ollama，建议 16GB 及以上，避免内存不足导致卡顿）；
存储：至少 10GB 空闲空间（用于存放安装包、依赖、模型文件及配置）；
网络：在线安装时需稳定网络（用于拉取依赖包）；离线部署可提前下载依赖，无需联网。

2.2 软件要求

操作系统：支持 Linux（Ubuntu 20.04+）、macOS（10.15+）、Windows 10/11（建议通过 WSL2 运行，体验更流畅）；
Python 版本：3.10 及以上（必须满足，低于该版本会导致依赖安装失败）；
包管理器：推荐使用 uv（官方推荐，安装速度更快），也可使用 pip；
可选依赖：Node.js 18+（用于启动 React TUI 界面，无需界面可忽略）；
可选工具：Git（用于克隆源码，一键安装可无需手动克隆）。

2.3 环境检查命令

打开终端（Linux/macOS）或 WSL2 终端（Windows），执行以下命令，检查环境是否达标：

# 检查 Python 版本 python3 --version # 或 python --version，需显示 3.10.0+ # 检查 uv 版本（无则安装） uv --version # 无输出则执行：pip install uv # 检查 Node.js 版本（可选） node --version # 需显示 18.0.0+（无需界面可忽略）

若 Python 版本不达标，需先升级 Python；uv 未安装则通过 pip 安装，确保后续安装流程顺畅。

OpenHarness 提供两种安装方式：一键脚本安装（推荐新手，简单快捷）、源码安装（适合需要自定义配置、二次开发的开发者），两种方式均能实现完整功能，可根据自身需求选择。

3.1 方式一：一键脚本安装（推荐新手）

官方提供了一键安装脚本，可自动检测操作系统、验证环境、安装依赖并配置，全程无需手动干预，步骤如下：

打开终端，执行以下一键安装命令： curl -fsSL

https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh | bash

安装过程中，脚本会自动完成以下操作：
1. 检测操作系统（Linux/macOS/WSL），适配对应安装逻辑；
2. 验证 Python ≥ 3.10 和 Node.js ≥ 18（Node.js 未安装则跳过 TUI 配置）；
3. 通过 pip/uv 安装 OpenHarness 核心依赖；
4. 设置 React TUI 界面（若 Node.js 可用）；
5. 创建 ~/.openharness/ 配置目录，存放权限、技能、记忆等配置文件。
安装完成后，执行以下命令验证安装是否成功： oh --version若输出 OpenHarness 的版本号（如 0.1.0），则说明安装成功；若提示“command not found”，需重启终端或配置环境变量（一般脚本会自动配置，重启即可生效）。

3.2 方式二：源码安装（适合开发者）

若需要自定义配置、修改源码或集成其他工具，可通过 Git 克隆源码安装，步骤如下：

克隆 OpenHarness 源码（需提前安装 Git）：
```
 git clone https://github.com/HKUDS/OpenHarness.git
```
进入源码目录：
```
 cd OpenHarness
```
使用 uv 安装依赖（推荐，速度更快）： uv install若未安装 uv，可使用 pip 安
```
pip install -r requirements.txt
```
安装完成后，验证安装： python -m openharness --version输出版本号即安装成功，后续可通过修改源码目录下的 config 文件夹，自定义权限、工具、模型等配置。

3.3 安装后初始化配置

安装成功后，需简单配置模型接口，才能正常使用 OpenHarness（核心是关联 LLM 模型，提供智能能力），步骤如下：

进入 OpenHarness 配置目录：
```
 cd ~/.openharness
```

 { "api_format": "anthropic", // 模型格式，支持anthropic、openai、copilot等 "anthropic_api_key": "你的Claude API Key", // 替换为自己的API Key "default_model": "claude-3-5-sonnet-", // 默认使用的模型 "permission": { "mode": "default", // 权限模式：default（需确认）、auto（允许所有）、plan（禁止写入） "path_rules": [{"pattern": "/etc/*", "allow": false}], // 禁止操作/etc目录 "denied_commands": ["rm -rf /", "DROP TABLE *"] // 禁止危险命令 } }

编辑配置文件（config.json），添加模型 API 信息（以 Claude 为例）：

{ "api_format": "openai", "openai_api_base": "http://localhost:11434/v1", // Ollama默认接口地址 "openai_api_key": "ollama", // Ollama无需真实API Key， 填写任意值即可 "default_model": "llama3:8b" // 本地运行的Ollama模型 }

若使用本地模型（如 Ollama），需修改配置为：

保存配置文件，初始化完成，即可启动 OpenHarness。

OpenHarness 支持 CLI 模式（核心）和 TUI 界面模式（可选），新手可先从 CLI 模式入手，熟悉核心操作后再尝试 TUI 界面，下面重点讲解 CLI 模式的基础使用。

4.1 启动 OpenHarness

打开终端，执行以下命令启动 OpenHarness（CLI 模式）：

oh # 一键脚本安装可直接执行oh # 源码安装需执行：python -m openharness

启动成功后，终端会显示欢迎信息，并进入交互模式（类似 ChatGPT 交互界面），此时可输入指令，让 OpenHarness 执行任务。

若启动 TUI 界面（需 Node.js 18+），执行命令：oh tui，即可打开可视化界面，操作更直观。

4.2 核心基础操作（3个常用场景）

OpenHarness 的核心是“指令驱动+工具调用”，无需复杂命令，直接输入自然语言指令即可，以下是3个最常用的场景，帮你快速入门：

场景1：文件操作（创建/编辑/读取文件）

输入指令，让 OpenHarness 自动完成文件操作，示例：

# 输入指令帮我创建一个名为test.py的文件，内容是打印"Hello OpenHarness"，然后读取该文件的内容 # OpenHarness 执行流程 1. 解析指令，调用文件写入工具（write）； 2. 创建test.py文件并写入指定内容； 3. 调用文件读取工具（read），读取文件内容； 4. 输出执行结果。 # 最终输出文件test.py创建成功，内容如下： print("Hello OpenHarness") 读取文件内容完成：Hello OpenHarness

注：若操作涉及敏感目录（如 /etc），OpenHarness 会弹出权限确认提示，确认后才会执行，保障安全。

场景2：Shell 命令执行（终端操作）

输入指令，让 OpenHarness 执行 Shell 命令，无需手动输入终端命令，示例：

# 输入指令帮我查看当前目录下的所有文件，统计文件数量，然后创建一个名为docs的文件夹 # 执行结果当前目录文件列表： test.py README.md 文件数量：2个文件夹docs创建成功

危险命令（如 rm -rf /）会被 OpenHarness 直接拦截，即使权限模式为 auto，也会禁止执行，避免误操作。

场景3：代码生成与调试

作为开发者，可让 OpenHarness 生成代码、调试 bug，结合其技能生态，效率更高，示例：

# 输入指令帮我生成一个Python函数，实现两个数的加法，然后编写单元测试，测试该函数是否正常运行 # 执行结果生成加法函数（add.py）： def add(a, b): return a + b 生成单元测试（test_add.py）： import unittest from add import add class TestAdd(unittest.TestCase): def test_add(self): self.assertEqual(add(1, 2), 3) self.assertEqual(add(-1, 1), 0) self.assertEqual(add(0, 0), 0) if __name__ == "__main__": unittest.main() 执行单元测试结果： .... OK 测试通过，函数运行正常

4.3 核心命令（常用快捷键）

在 CLI 交互模式下，可使用以下命令快速操作，提升效率：

/help：查看所有可用命令和工具，了解详细用法；
/exit：退出 OpenHarness 交互模式；
/memory：查看当前会话的记忆内容，可手动编辑或清除；
/skill list：查看所有已加载的技能，输入 /skill load 技能名 加载新技能；
/model switch 模型名：切换后端模型（如 /model switch kimi）；
/commit：创建结构化的 Git 提交记录（需提前初始化 Git 仓库）。

掌握基础使用后，可通过以下技巧，充分发挥 OpenHarness 的优势，适配更复杂的开发场景：

5.1 技能扩展（适配个性化需求）

OpenHarness 兼容 Claude Skills 生态，只需将技能的 .md 文件复制到 ~/.openharness/skills/ 目录，即可加载使用，示例：

# 下载 Claude Skills 技能文件 git clone https://github.com/anthropics/skills.git # 复制技能到 OpenHarness 技能目录 cp skills/*.md ~/.openharness/skills/ # 加载技能 oh /skill load review # 加载代码审查技能

也可自定义技能，创建 .md 文件，编写技能描述和执行逻辑，放入技能目录即可，满足个性化开发需求。

5.2 多 Agent 协同（处理复杂任务）

OpenHarness 支持子 Agent 生成和团队协调，可将复杂任务拆分给多个子 Agent 并行执行，提升效率，示例：

# 输入指令创建两个子Agent，Agent1负责生成FastAPI项目结构，Agent2负责编写项目的单元测试，完成后合并结果

OpenHarness 会自动生成子 Agent，分配任务，并行执行，最后汇总结果，适合处理大型项目开发、多任务协同等场景。

5.3 上下文压缩与记忆优化

当会话历史过长，导致 Token 用量过高时，OpenHarness 会自动触发上下文压缩（Auto-Compact），清除冗余信息，保留核心内容；也可手动触发压缩：

oh /compact # 手动压缩上下文

同时，可通过编辑 ~/.openharness/MEMORY.md 文件，手动添加持久化记忆（如项目架构、编码规范），让 OpenHarness 记住项目规则，无需每次重复说明。

5.4 离线部署优化（数据安全）

若需完全离线使用，除了配置本地 Ollama 模型，还需提前下载所有依赖和技能文件，步骤如下：

在线环境下，下载依赖包：pip download -r requirements.txt -d ./deps
下载 Claude Skills 技能文件，放入 ~/.openharness/skills/；
离线环境下，安装依赖：pip install --no-index --find-links=./deps -r requirements.txt；
配置本地 Ollama 模型，启动 OpenHarness 即可完全离线运行。

安装或使用过程中，可能会遇到一些问题，以下是常见问题及解决方案，帮你快速排查：

6.1 安装失败：提示“Python 版本过低”

解决方案：升级 Python 到 3.10 及以上，Linux/macOS 可通过 pyenv 管理版本，Windows 可直接下载安装包升级，升级后重启终端再重新安装。

6.2 启动失败：提示“API Key 无效”

解决方案：检查 config.json 中的 API Key 是否正确，Claude/OpenAI 等模型的 API Key 需在官方平台获取；若使用本地 Ollama 模型，确保 openai_api_key 填写为“ollama”，且 Ollama 已启动。

6.3 工具调用失败：提示“权限不足”

解决方案：检查权限模式，若为 plan 模式，会禁止所有写入操作，可修改 config.json 中 permission.mode 为 default；若涉及敏感目录，需在 path_rules 中添加允许规则。

6.4 启动 TUI 界面失败：提示“Node.js 版本过低”

解决方案：升级 Node.js 到 18 及以上，可通过 nvm 管理 Node.js 版本，升级后重新启动 TUI 界面。

6.5 会话记忆丢失：重启后忘记之前的操作

解决方案：确认 config.json 中启用了记忆持久化，检查 ~/.openharness/MEMORY.md 文件是否存在，若不存在，手动创建该文件，重启 OpenHarness 即可。

OpenHarness 作为轻量级 AI Agent 框架，以“轻量、灵活、安全、可控”的优势，打破了 Harness 工程的使用门槛，无论是新手开发者、极客玩家，还是需要本地离线部署的团队，都能快速上手使用。

本文从环境准备、部署安装、基础使用到进阶技巧，覆盖了 OpenHarness 的核心操作，按照步骤操作，就能快速实现部署并投入使用。后续可结合自身需求，扩展技能、优化配置，充分发挥其工具调用、多模型兼容、多 Agent 协同的优势，让 AI Agent 真正成为提升开发效率的“好帮手”。

最后，附上 OpenHarness 官方资源，方便大家获取更多信息和支持：

官方 GitHub 地址：https://github.com/HKUDS/OpenHarness
官方文档：https://openharness.dev/
技能生态：Claude Skills 仓库

如果在使用过程中遇到其他问题，欢迎在评论区留言交流，一起探索 OpenHarness 的更多用法～