Agent Harness是什么？OpenClaw用Rust构建的Agent体外循环系统

1. Harness不是Agent，它是Agent的"体外循环系统"

1.1 一次Agent裸奔的教训

我最早动手做个人AI助手的时候，想法特别简单：用一个循环调大模型API，给它配几个工具函数，让它"自己决定"调哪个、怎么调。前几次跑起来还挺像那么回事，问天气、列日程、记笔记，都能完成。直到有一天，我让这个Agent去整理一份本地表格，再根据整理结果给几个同事发通知脚本。结果它突然开始反复调用同一个工具，参数越填越离谱，甚至捏造了一些表格里根本不存在的字段名。我没设调用次数上限，它就这么空转了几分钟，把token烧掉一大截，最后程序死在了一个毫无意义的无限循环里。

这件事之后我翻了很多资料，才发现问题不在模型，也不在工具定义，而在于我压根没有给Agent配一套"体外循环系统"——也就是现在圈子里常说的Harness。模型只是大脑，它能思考、能生成文字，但要让它稳定地使用工具、持久地记住上下文、在出错时能停下来、在被恶意输入诱导时不越权，必须有一层专门负责"运行控制"的中间件。这层中间件，就是Harness。

如果你也写过半吊子的Agent脚本，应该能秒懂我说的场景：代码只做到"把用户问题丢给模型，把模型返回的tool call丢给函数"，但函数调用失败怎么重试？上下文超过窗口怎么裁？模型突然决定调用一个不存在工具怎么办？工具执行结果太长了怎么压缩？这些问题单独看都是小坑，堆在一起就是灾难。Harness存在的全部意义，就是把这些脏活累活统一管起来。

1.2 Harness的核心职责：模型协议、行动执行、上下文管理、安全边界

如果用一句话概括，Harness是连接大模型与外部世界的那层"身体"。人没有身体，大脑再聪明也无法倒水、走路、拿东西；Agent没有Harness，模型再强也只是一个文本生成接口，没法真正"做事"。

具体拆开，Harness至少要承担四件事：

• 模型协议层：把DeepSeek、OpenAI、Anthropic以及本地Ollama之类的推理服务，统一成一套模型访问接口。Agent写业务逻辑时不需要关心后端是API还是本地模型，换供应商只是改配置的事。
• 行动执行层：模型输出的结构化工具调用（function calling / tool use）在这里被解析、校验、执行。它要检查参数是否符合工具定义的schema，执行超时了怎么处理，返回结果要截断到多长，这些全在这一层完成。
• 上下文管理层：对话历史不可能无限累积，Harness负责滚动窗口、压缩摘要、写入向量记忆。这决定了Agent是"聊几句就失忆"还是"能记住你上周交代的事"。
• 安全边界层：哪些目录可写、哪些命令可执行、涉及删除和支付等操作要不要二次确认、每一步操作有没有日志可审计。没有这一层，Agent就是一头没拴绳的猛兽。

为了让你更直观理解Harness和裸脚本的差别，我做了个对比：

1.3 Harness工程和Agent框架怎么区分

热搜里总有人问"Harness和Agent区别是什么"，我现在的理解是：Agent是一个逻辑概念，它代表一个能自主感知、决策、行动的软件体；Harness是这个软件体的运行载体和工程化外壳。同一个Agent逻辑，可以用一百种方式实现，但能不能在真实环境里稳定、安全、可控地跑起来，取决于Harness够不够扎实。

很多Agent框架也在做类似的事，但它们更强调"怎么搭出Agent的结构"，比如定义Agent、工具、流程这些上层对象。Harness则更强调"运行期控制"：Agent跑起来之后，谁给它提供模型服务、谁执行工具、谁管记忆、谁守边界、怎么在不同设备上跑、怎么集成到现有系统里。OpenClaw把自己定位成"Agent Harness + All-in-One Runtimes"，翻译成大白话就是：我不仅给你Agent的骨架，还把Agent跑起来所需要的一整套运行环境都打包好了。

这个概念理清楚了，后面看OpenClaw的架构就不会晕。因为你会发现，它所有的组件设计，都对应着上面说的某一项职责。

2. OpenClaw：一个用Rust写的Agent Harness，把"随处运行"当卖点

2.1 为什么选Rust，而不是Python

我第一次看到OpenClaw的项目介绍时，第一反应是：居然有人用Rust做Agent运行时。但仔细想想，这确实是个合理的选型。

Agent Harness本质上是一个长时间运行的守护进程，它要同时处理网络请求、工具执行、上下文读写、多任务并发。Python在这种场景下的问题在于打包分发太痛苦，而且并发模型依赖异步框架，部署到不同平台上动不动就是各种依赖冲突。Rust则恰好相反：编译成一个单文件二进制，丢到哪都能跑；内存安全特性让长时间运行不容易出现内存泄漏；标准库和生态对于网络、文件、进程管理这些基础能力覆盖得很完整。

这带来的直接好处就是部署成本极低。Windows、macOS、Linux、安卓（通过Termux）都可以跑同一个二进制或者相近的构建产物，这也是OpenClaw强调"Agent Anywhere"的底气所在。对于需要在内网服务器部署的人来说，拷一个二进制文件进去，可比在服务器上配Python虚拟环境、装一堆依赖包省心太多。

2.2 核心架构拆解：四层各管什么

从架构上看，OpenClaw大致可以分为四层，每一层对应一个职责域：

• 大脑连接层：负责接入各种模型服务。OpenClaw兼容常见的API供应商，也支持连本地推理服务。切换模型不需要动Agent逻辑，改配置文件就行了。我自己实测下来，在OpenClaw里配DeepSeek和配Ollama本地模型的体验基本一致，只是模型名和BaseURL不一样。
• 行动层：这是Harness的"手"。OpenClaw里Agent能执行的动作被组织成一个个Skill（技能）。技能本质上是一段可复用的能力封装——可以是一条命令、一段脚本、一次API调用，也可以是更复杂的多步骤流程。Harness负责加载技能清单、把模型输出的调用意图路由到对应技能、执行完再把结果回填给模型。
• 记忆层：管上下文和长期记忆。会话窗口满了怎么压缩、重要信息怎么沉淀到持久化存储、下次启动时能不能恢复之前的状态，这些都是记忆层的事。没有这层，Agent每次对话都是"第一次见你"。
• 运行时层：管适配不同平台和场景。Windows上跑桌面模式、手机Termux里跑轻量模式、服务器上跑服务模式，甚至接ROS2控制机器人——同一套Agent内核，不同运行外壳。

一开始我总把"模型接入"误以为是Harness的全部，其实那只是一小块。行动层和记忆层往往才是决定Agent好不好用的关键。技能组织得好，Agent能干的活就多；记忆管得好，聊天的连贯性和实用性就强。

2.3 "All in One Runtimes 2.5.0"到底是种什么体验

"All in One Runtimes 2.5.0"这个版本号让我琢磨了很久。后来我把它理解为：一个发行包，聚合了多种运行模式。OpenClaw不是只有一个CLI界面，它同时提供了好几种运行方式，比如Windows下的桌面伴生程序（Companion）、命令行交互模式、后台服务模式等。所谓"All in One"，就是这些运行形态打包在一起，装一个就能按需选择。

好处很明显：下载一次，所有场景都能覆盖。代价也显而易见：功能太多，配置项自然多，新手第一次打开容易懵。我在4.2节里会专门讲怎么避开配置里的那些坑。

3. Runtimes的三层含义：模型、设备、工具

"Runtimes"这个复数形式很关键。很多人以为它只指"运行环境"，但在OpenClaw的语境里，它其实覆盖了三层东西：模型运行时、设备运行时、工具运行时。理解这三层，你就知道一个Agent到底能活在多少种环境里。

3.1 模型运行时：API接入和本地推理两种姿势

模型运行时解决的是"Agent用哪个大脑"的问题。

• API接入：最常见的做法，配置一个API Key和BaseURL就能用。OpenAI、Anthropic、DeepSeek系模型都可以。这类方式的好处是省心，坏处是每一次对话都有token成本，而且数据要发送到外部服务。适合个人开发、原型验证。
• 本地推理：通过Ollama这类工具在本地跑开源模型。好处是数据不出机器、没有按token计费的压力、断网也能用；坏处是模型能力一般不如顶级商用API，而且需要机器有足够的显存或内存。适合隐私敏感的场景，比如把模型和Agent都部署到内网服务器上。

OpenClaw的设计是让这两者可以并存、随时切换。我在实践中的做法是：日常调试用Ollama跑一个中尺寸模型，零成本随便试；正式干活时切到能力更强的API模型。配置切换是热生效的，不需要重启Agent进程。

3.2 设备运行时：Windows、安卓手机、内网服务器各扮演什么角色

设备运行时解决的是"Agent跑在哪台机器上"的问题。

• Windows桌面：我用来干最多活的场景。Agent可以读写本地文件、执行命令行工具、管理日程和邮件，相当于给电脑装了个能说话的"自动化总管"。
• 安卓手机（Termux）：这让Agent真正做到了随身携带。在Termux里部署OpenClaw，等于把Agent放进了口袋。你在外面的时候，可以用手机上的Agent查资料、记笔记、控制家里的设备。手机端最大的限制是性能和续航，适合跑轻量任务。
• 内网服务器：这是我最看重的场景。很多数据不能出内网，模型和Agent都得部署在内部。OpenClaw的Rust单二进制特性在这里优势巨大——拷一个可执行文件进去就能跑，不用在里面折腾依赖环境。

3.3 工具运行时：当Agent要控制ROS2机器人的时候

这是我认为最有想象力的部分。搜索热词里出现了"rosclaw openclaw ros2 humble gazebo"——社区里已经有人在把OpenClaw接进机器人操作系统ROS2，配合Gazebo仿真环境使用。

理解这件事的价值，要先跳出"Agent = 聊天机器人"的思维定势。如果Agent的"手"不止能调用软件工具，还能调用物理世界的接口——比如通过ROS2话题（Topic）发布机器人的运动指令、读取传感器数据——那Agent就从一个软件助手升级成了"机器人指挥官"。

Gazebo是ROS2生态里的仿真环境，用来在虚拟世界里跑机器人。把OpenClaw接进Gazebo的好处是，你可以在完全不接触真机的情况下，反复试验Agent对机器人的控制逻辑。等仿真里验证得够多了，再把它对应到真机上。这个思路和自动驾驶先在模拟器里训练是一回事。

当然，这部分目前更多是社区试验性质，距离开箱即用还有距离。但方向已经很明确了：Harness的"工具"不只是函数，还可以是传感器、执行器、一切能连上网络的物理设备。

4. 复现笔记：我在三种环境里搭建OpenClaw的经验和踩坑

4.1 Windows环境：开发调试的主力场景

Windows上搭建OpenClaw，我走的路径是：先安装Rust工具链，再克隆项目仓库编译，最后准备模型服务配置。如果你的机器没装过Rust，先去rustup.rs下载安装，然后用命令行验证一下rustc和cargo是否可用。

一个容易被忽略的点是：编译之前先把依赖装完整。OpenClaw涉及网络、文件、系统交互等多个Rust crate，编译时间在中等配置的机器上可能要几分钟到十几分钟，期间如果网络不稳定或者依赖缓存冲突，很可能会中断。建议在稳定网络环境下把依赖都拉到位再开始。

我第一次编译时踩了个大坑：默认构建配置没有调优，编译时间巨长，机器风扇狂转，还一度因为内存不够编译失败。后来把构建profile切到release模式，并且关了多余的特性开关，才顺利出包。我的建议是：不要一上来就加一堆自定义feature，先保持默认配置编译通过，再逐步开启你确实需要的功能。

Windows下我推荐配合官方文档里提到的Companion组件使用。Companion相当于给Agent配了个桌面伴生界面，调试时可以实时看到Agent在调哪个工具、上下文状态怎么样，比纯命令行直观太多。

4.2 安卓手机部署：用Termux把Agent装进口袋

手机上装OpenClaw，主流的做法是通过Termux。Termux是安卓上的终端模拟器，能在不root手机的情况下提供一个Linux环境。

步骤大致是：装好Termux后，更新包管理器，安装Rust相关的编译工具链，然后克隆OpenClaw项目在Termux里编译。注意，手机编译和电脑编译完全是两种体验。手机的内存和散热都很有限，大项目编译经常会遇到OOM或者超时。我的经验是：尽量在电脑上交叉编译出ARM64架构的二进制，再传到手机上，比在手机里现编要省事得多。如果非要现场编，务必在Termux里开swap，不然遇到中等规模依赖就可能编译失败。

手机端跑起来之后，我还发现一个问题：后台容易被系统杀进程。Termux有自己的wakelock机制，可以保持后台运行，但耗电会变快。我把Agent当"随用随启"的工具，而不是24小时常驻服务，这样平衡了实用性和续航。

4.3 内网服务器部署：模型和Skill一起离线分发

内网部署是我在工作里遇到很多次的场景。很多企业对数据出境卡得很严，内部系统要求所有服务都跑在隔离网络里。OpenClaw在这种场景下的部署我总结成四个字：提前打包。

流程是这样的：在一台能联网的机器上，把OpenClaw编译成目标架构的二进制，同时下载好Agent运行需要的模型文件（比如通过Ollama）和所有技能依赖。然后把这几个文件一起拷到内网机器。进入内网后，只需要解压文件、启动二进制、配置指向本地模型的路径，Agent就能跑起来。没有需要联网安装的依赖，因为Rust编译产物本身就是静态链接为主的。

这里有一个容易踩的坑：模型文件不能想当然地拷贝。Ollama的模型有时候会按不同架构打包，从x86机器拷到ARM机器可能会无法加载。稳妥的做法是在打包阶段就明确目标机器的CPU架构，下载对应版本的模型文件。

如果内网服务器上还带了OpenClaw附带的Skill，部署时要注意skill目录的权限。Agent需要读写这些目录，但有些内部机器的默认安全策略会把新目录设成只读，运行时直接报权限错误。我一般会在部署脚本里显式设置好目录属主和权限，避免这种低级但烦人的问题。

5. Agent安全：Harness边界就是你的安全边界

5.1 不做防护时，Agent能捅出什么篓子

"Agent安全"是搜索热词里的高频话题，我强烈建议每一个打算长期使用Agent的人都重视起来。没有安全边界的Agent，问题不只是烧token，还可能是：

• 无休止循环：Agent反复调用同一个工具，参数越变越离谱，直到浪费完所有预算。
• 越权操作：模型被诱导去删文件、执行危险命令，或者访问本不该访问的目录。
• 提示注入：外部输入（比如网页内容、文档内容）里被嵌入恶意指令，Agent读取后可能被"洗脑"，转而执行攻击者预设的操作。
• 数据泄露：Agent把不该外传的文件内容拼进上下文，随着API请求一起送出内网。

这些不是危言耸听，每一类都在真实事故里出现过。Harness存在的意义之一，就是把这些风险关进笼子里。

5.2 在OpenClaw里配置安全边界的实操细节

在OpenClaw里，安全能力体现在几个层面，配置方式并不复杂，但一定要配：

• 目录白名单：明确告诉Agent哪些路径可以读、哪些可以写。凡是名单外的路径，工具执行层直接拒绝。日常工作里，我会专门开一个workspace目录给Agent读写，系统目录和我的私人目录一律不在名单内。
• 高危操作二次确认：删除文件、执行系统命令、发送外部请求这类敏感动作，设置成必须经过人工确认。我在跑批量脚本时一度觉得"每次都要确认太烦"，但后来有一次Agent试图执行一个我从没见过、来源可疑的命令，幸好二次确认拦住了，才知道这条配置多重要。
• 日志审计：开启完整的操作日志。Agent每一步调用了什么工具、传了什么参数、耗了多少token，都应该能回溯。出了问题，第一件事永远是翻日志。

安全边界这件事，我的体会是：它不只是防守，更是给Agent的"行为底座"。边界划清楚了，Agent做事反而更收敛，不容易跑偏。

6. 上篇的落脚点：从Runtime到Skills，Harness系列还会讲什么

这篇是"理解Harness系列"的第一篇，标题里特意写了"（上）"，所以我把重点放在了"Runtimes"——也就是Agent在各种平台上跑起来这件事上：Harness的基本概念、OpenClaw的架构、三种运行时形态、搭建复现笔记、安全边界。

到了"（下）"，我准备专门聊Skills的工程组织：技能怎么设计、依赖怎么管理、一个完整的实操案例是怎么拆出来的、以及如何把多个技能编排成一套自动化工作流。Skills是OpenClaw里最值得玩的模块，也是把它从"能跑"推向"好用"的关键。

如果你读到这里，我的建议是：不要光看，先去把你手边最简单的一个Agent搭起来。就用OpenClaw默认配置，接一个本地Ollama模型，放在一个白名单目录里让Agent自由活动。跑起来之后，你再回头看这篇讲的Harness概念，会发现自己已经理解了"为什么要有这一层"——这比记住任何架构图都管用。