最近 AI Agent 很火。
OpenHands、Devin、Claude Code、Cursor、CodeX……

大家天天都在说：

Agent
Harness
Tool Calling
Memory
Multi-Agent

但说实话。

我之前对这些东西的理解，基本属于：

“懂了，但又没完全懂。”

直到我真的把一个 Harness 跑了起来。

这次折腾的是：

OpenHarness

结果非常有意思。

因为它不像普通 AI 项目：

输入 -> 输出

而是：

输入
 ↓
AI 思考
 ↓
调用 Tool
 ↓
执行 Shell
 ↓
读取文件
 ↓
分析代码
 ↓
继续思考
 ↓
再次调用 Tool

那一刻你会突然意识到：

原来 AI Agent 真的是“会行动”的。

而不只是聊天机器人。

---

一、OpenHarness 到底是什么？

简单来说：

OpenHarness = 一个 AI Agent Runtime

它本质上是：

• Tool 调度器
• Agent Loop
• Memory 系统
• Shell 执行器
• Multi-Agent 基础设施

你可以理解成：

“AI 的操作系统”

或者：

“给大模型插上手脚”

它最核心的思想其实很简单：

while True:
    think()
    choose_tool()
    execute_tool()
    observe_result()

但真正难的是：

• 怎么管理上下文
• 怎么做 Tool 权限
• 怎么避免死循环
• 怎么做 Memory
• 怎么做多 Agent 协作

而 OpenHarness 已经把这些东西搭好了。

---

二、为什么我建议本地源码部署（别一上来 Docker）

很多人第一反应：

docker compose up

然后：

报错 × 10086

实际上。

对于学习 Agent Runtime 来说：

本地 Python 部署体验最好

因为：

Harness 本身大量依赖：

• Shell
• 文件系统
• Tool Runtime
• CLI
• 权限

Docker 会多出很多学习成本：

• volume
• tty
• 容器 shell
• 权限映射
• 文件挂载

你最后甚至会分不清：

到底是 Harness 坏了
还是 Docker 坏了。

所以我建议：

先本地跑通

理解架构后再容器化。

---

三、我的环境

我的环境：

Mac
Python 3.11
zsh
uv

OpenHarness 官方也推荐：

uv

这个东西现在非常猛。

可以理解成：

“下一代 Python 包管理器”

速度比 pip 快很多。

---

四、正式开始部署

---

1、安装 uv

Mac：

curl -LsSf https://astral.sh/uv/install.sh | sh

验证：

uv --version

---

2、克隆项目

git clone https://github.com/HKUDS/OpenHarness.git

进入目录：

cd OpenHarness

---

3、创建虚拟环境

uv venv

激活：

source .venv/bin/activate

这时候你会看到：

(OpenHarness)

说明进入虚拟环境了。

---

4、安装依赖

uv sync --extra dev

这里会安装：

• Agent Runtime
• Tool 系统
• CLI
• TUI
• Memory
• 各种依赖

第一次可能稍微久一点。

---

五、第一次启动，果然翻车了

启动：

uv run oh

结果：

Error: No API key configured.

我：

？？？

后来才发现。

OpenHarness 默认优先支持：

• Claude
• OpenAI

所以需要配置模型。

---

六、配置模型（重点）

直接执行：

oh setup

然后会让你配置：

Base URL
Model
API Key

因为我本身在用 OpenAI Compatible 接口。

所以直接填：

Base URL:
https://你的接口/v1

Model:
gpt-5.4 我是选的这个

API Key:
sk-xxxx

配置完之后：

再次启动：

uv run oh

然后。

那个经典界面终于出来了：

当时有一种：

“坏了，好像真进入 AI Agent 世界了。”

的感觉。

---

七、真正震撼的部分来了

我输入：

分析当前项目结构

然后它开始：

• 自己扫描目录
• 自己读 README
• 自己 grep
• 自己分析源码
• 自己总结结构

注意：

这里最关键的不是“回答”。

而是：

它开始主动调用 Tool 了

你会看到类似：

Tool: ls
Tool: glob
Tool: read_file

那一刻你会突然明白：

Agent ≠ 大模型

而是：

Agent = 大模型 + Tool Loop

这就是：

• Cursor
• Devin
• Claude Code
• OpenHands

真正的底层逻辑。

---

八、我第一次真正理解了什么叫 Harness

以前我理解 AI：

AI = 聊天

现在我开始理解：

AI = Runtime
AI = Tool Orchestrator
AI = Operating System

Harness 的核心：

其实就是：

“如何让 AI 安全地调用能力”

这里面最重要的几个目录：

---

1、engine/

这里是：

Agent Loop 核心

你会看到类似：

while True

这就是 Agent 的灵魂。

---

2、tools/

这里特别像：

Java 接口

本质：

@tool
def xxx():

把能力暴露给 AI。

比如：

• Shell
• 文件系统
• Git
• 搜索
• Browser

---

3、permissions/

这个特别重要。

因为企业级 Agent 最大问题不是：

AI 能不能做

而是：

AI 被允许做什么

所以这里会有：

• confirm
• sandbox
• allowlist
• denylist

---

4、coordinator/

这里是：

主Agent
↓
子Agent
↓
任务分发

也就是：

Multi-Agent

---

九、最有意思的一件事

后来我突然意识到。

我最近在做的：

AI项目理解平台

其实本质上：

就是：

给 Agent 增加新的 Tool

比如：

SpringBootProjectAnalyzerTool

能力：

• 扫描 Controller
• 分析 Service
• 提取 Mapper
• 生成调用链
• 输出架构图

这时候我突然有一种：

“原来大家都在造 AI Runtime。”

的感觉。

---

十、最后的感受

以前总感觉：

AI Agent 很玄学

但真正跑起来以后。

你会发现：

它其实非常工程化。

本质就是：

LLM
+
Tool
+
Loop
+
Memory
+
Planning

只是：

真正难的是：

“如何让 AI 稳定地行动”

这也是为什么：

很多 Agent 项目最后都会：

退化成 Workflow

因为：

“让 AI 真正自由行动”

其实是个非常难的工程问题。

---

十一、最后给想入门 Agent 的朋友一个建议

不要天天只看概念。

直接：

跑一个 Harness

因为：

你会在半小时内，
把过去半年听不懂的 Agent 概念全部串起来。

这比看 100 篇：

“什么是 AI Agent”

都有用。

---

项目地址

• OpenHarness：

OpenHarness GitHub 仓库

---

结尾

以前我觉得：

AI 是聊天机器人。

现在我开始觉得：

AI 更像一个正在学会“操作电脑”的数字员工。

而 Harness。

就是它的：

手、脚、工具箱、记忆、以及工作台。