1. 从一个失控的 agent 开始为什么我们需要一套“代理运行时”早些年做自动化项目的时候我吃过不少亏最典型的就是“裸调 API 写 agent”。那个时期的思路很单纯找一个大模型接口塞一段很长的系统提示词说明“你是我的助手”然后把 API 密钥焊死在脚本里再写一个 while 循环把模型的输出原样喂回去。听起来很像 agent 了跑起来却完全失控。模型会坚持调用一个根本不存在的工具会在同一件事上反复重试会把用户随手输的一段话当成新指令执行。最夸张的一次一夜之间烧掉上千次调用额度日志里全是莫名其妙的乱码。也就是从那次起我彻底明白了一件事Agent 要真正干活缺的不是更聪明的模型而是一套能约束、能观测、能恢复它的运行框架。这套框架就是社区里反复提到的 Harness。而 OpenClaw 是我最近半年一直在用的开源项目它的核心价值恰恰就在 Harness 层和运行时runtimes层的工程化上。这篇文章是“理解 Harness 系列”的第一篇先拿 OpenClaw 的 Agent runtime 开刀把“一个 agent 到底是怎么跑起来的”这件事讲透。适合两类人一类是想自己搭 AI 助手、但一直被“框架”两个字劝退的新手另一类是已经裸调模型 API 裸到头秃、想找一个工程化出口的开发者。1.1 裸字符串调用为什么注定失控先还原一下最早期那个失败脚本的结构。整条链路只有三层用户输入、模型 API、输出。模型想调用什么就调用什么想什么时候停就什么时候停没有任何中间层做约束。问题主要出在三个地方。第一没有验证层。模型返回了一个工具调用参数但参数格式根本不对程序直接崩溃而不是触发重试或自我纠正。第二没有护栏层。模型连续对话十几轮之后越聊越“嗨”没有任何机制检查它访问的路径、文件和接口是否越界。第三没有可观测层。它失败之后你只能看到一屏报错根本分不清是模型理解问题、参数问题、还是网络问题。我相信很多人在本地折腾 agent 时都经历过类似场景。这其实不是模型笨是我们缺少一个可编程的“运行环境”。你可以把这个问题想象成一个实习生能力很强但你既没给他工作手册也没给他操作权限还没给他汇报机制。他当然会搞砸因为让他干活的条件本身就不完整。1.2 用操作系统的演化来理解 Agent 运行时这里我想用一个类比。操作系统出现之前开发者直接操作硬件一个程序想用内存就用内存想占 CPU 就占 CPU程序之间互相打架是常态。操作系统出现之后进程、线程、文件系统、权限管理把底层资源的分配规范化了程序才真正变得可管理。Agent 开发也在经历同样的演化。Harness 相当于 Agent 的“操作系统内核”负责调度大模型的思考节奏、决定每一步行动策略而 Agent runtime 相当于“进程运行环境”负责具体执行、资源隔离、状态管理和安全边界。我自己更喜欢把 runtime 比作发动机和底盘把 Harness 比作方向盘和仪表盘。方向盘决定去哪底盘决定车能不能平稳地跑过坑洼路面。OpenClaw 对这两层的边界分得很清楚Harness 决定“为什么做、下一步做什么”runtime 决定“怎么做、在哪跑、跑完怎么记账”。1.3 这篇先解决什么问题因为是系列第一篇标题又写了“上”所以本文不打算覆盖所有花式玩法而是聚焦在理解运行时这件事本身。我会按四步走先把概念层拆解干净再进到运行时内部看核心子系统然后带你看四个典型部署场景最后走一遍完整起步流程。有这些底子你再去翻任何 Harness 项目的文档都不会觉得它是黑盒。更深入的内容比如多机编排、细粒度权限模型、超长上下文下的分层记忆、大规模技能库治理我会在系列后面几篇逐个展开。现在先把最地基的部分打牢。2. 先把概念切碎模型、Harness、运行时、技能谁在干什么很多人拿到 OpenClaw 后的第一反应是“装完了怎么用”然后跟着网上的教程去配各种向量数据库、接各种聊天前端结果翻车翻得莫名其妙。我建议先别急花十分钟把下面四个概念分清后面所有配置都会变得顺理成章。2.1 四个概念的边界模型层Model最里层的大脑比如 DeepSeek、Qwen 这类推理引擎。模型只做一件事根据输入预测下一个 token。它不知道什么是文件系统也不知道什么是浏览器更不知道你的电脑上跑着什么服务。推理服务层API / Inference Server把模型包装成可以被外部调用的服务。云端有各家官方 API本地可以用 Ollama、vLLM 这类推理服务。对 OpenClaw 来说它接触的其实是这一层而不是赤裸裸的模型权重。Harness 层Agent 的控制编排层。它持有整个 agent 的“基调”系统提示词、任务规划器、工具选择策略、多轮循环的节奏。Harness 不负责具体执行也不关心你部署在什么设备上它只负责“下一步做什么”的决策。运行时层Runtimes这是整篇文章的核心。runtime 负责把 Harness 的决策变成真实动作。它管理进程生命周期、执行工具的沙箱、保存对话状态、读写日志、和操作系统交互。同一个 Harness 配置可以被不同的运行时承载Windows 上的本地进程、安卓 Termux 里的进程、机器人上的 ROS2 节点、内网服务器上的服务进程。技能层Skill可复用的动作包。比如“查天气”“读数据库”“浏览网页”。一个 Skill 通常由三部分组成声明文件元数据告诉 Harness 什么时候能用、执行体代码或脚本、校验规则入参出参的格式约束。层级职责常见实现模型层语言理解和生成DeepSeek、Qwen 等推理服务层把模型包装成 APIOpenAI API、Ollama、vLLMHarness 层决策循环与任务编排OpenClaw 控制核心Runtime 层执行、状态、权限、日志桌面进程、安卓进程、ROS2 节点、服务器服务Skill 层具体动作与工具封装声明文件 Python/Shell 实现2.2 把“部署平面”和“运行平面”分开想我在交流群里经常看到有人问“OpenClaw 是不是只能通过 API 方式用算力” 这个问题背后其实就是没把模型平面和运行平面分开。模型平面只关心“智商”由谁来提供。你完全可以本地跑一个 Ollama加载量化后的 DeepSeek 模型再把 OpenClaw 的模型地址指向 localhost:11434。这样算力在本地OpenClaw 照常工作只是推理速度取决于你的显卡。运行平面关心的是 agent 的“身体”在哪儿。也许在 Windows 电脑上也许在安卓手机里也许在机器人的控制器上也许在纯内网服务器上。模型平面和运行平面相互独立你完全可以让模型跑在云端、agent 身体跑在离线环境里只要中间有一条可控的通道。把这两个平面分开想之后很多部署问题都变得简单。比如公司数据不能出内网那就把推理服务建在内网运行平面同样是服务器上的进程数据全程不出域。这也是“harness 工程”这个词被频繁提起的原因工程化的本质不是炫技而是把边界划干净让每一层各司其职。2.3 社区里的“all-in-one runtimes”是什么意思搜索热词里有个词叫“all in one runtimes 2.5.0”这其实代表了运行时层的一个发展趋势尽量把多种执行环境统一到一个引擎下管理。以前你装一个 agent 框架桌面一套、手机一套、机器人一套各自为政技能包还得分别适配。而现代设计比如 OpenClaw 这类项目倾向于让同一套技能包、同一个 Harness 逻辑能横跨不同运行时发射。这个思路的价值在于今天你在笔记本上写的“定时提醒”技能明天同步到手机的 Termux 里后天放到机器人的 ROS2 节点里逻辑本体不变变的只是运行时的环境适配层。这是“agent anywhere”思想在工程上的落点。3. OpenClaw 运行时架构里最值得先啃下的四个子系统跑 OpenClaw 这一路下来我的感受是这个项目的运行时不是一个大杂烩而是由几个相互独立、又能精密咬合的子系统组成。你不需要一上来全弄明白但下面这四个是理解一切后续特性的地基。3.1 会话执行循环运行时的心脏前面说过agent 不是一次 API 调用而是“多次调用组成的一个循环”。这个循环是运行时里最重要的子系统我习惯叫它执行循环。每轮会话运行时会经历这样一组状态初始启动读取系统提示词注入全局状态建立会话 ID。模型调用把当前消息列表发给模型附上当前可用的技能列表。输出解析拿回模型输出区分它到底是普通文本回复还是工具调用指令。工具执行如果是指令按声明的 Skill 去执行取回结果。观察注入把执行结果作为新的消息放回消息列表。回到第二步或者由 Harness 判定任务完成而退出。这套机制说起来简单工程难点在于它是个状态机。你不能用线性脚本表达这个循环因为随时要处理中断、超时、拒绝执行、模型返回格式异常。OpenClaw 的运行时把每种状态都做成可观测的你在日志里能看到每一轮是模型返回了文本还是请求了一个工具还是被权限策略拦下来了。给新手的建议很直接先学会看日志再去猜配置。日志里每一行的状态字段就是这个循环的实时心电图。哪个环节卡住了一眼就能定位。3.2 技能执行沙箱把“能力”变成可校验的代码前面分概念时说过“技能层”但技能真正落地的位置在运行时。OpenClaw 对 Skill 的加载有一套固定规范一个 Skill 一般是一个目录里面有声明文件与实现代码。声明文件里写明名称、描述、参数格式实现代码则用 Python 或 Shell 写。当模型在对话中提出“我要调用 xxx 工具”时运行时不会盲目执行而是走一套校验流程先检查工具名是否在已注册列表里再校验参数是否通过格式检查通过后才进入执行环境执行返回结果会被截断到合理长度避免把上下文撑爆。我见过不少人把 Skill 理解成“一段 prompt”这是很常见的误区。Skill 不是一段文字而是“一段可执行程序 一段模型可读的说明书”。说明书给模型的推理用程序给运行时的动作用两者缺一不可。声明文件写得含糊模型就不知道该在什么时机调用执行体写得不稳运行时再聪明也没用。3.3 会话状态与记忆管理token 预算的守门员回到执行循环的第五步执行结果放回消息列表但消息列表不能无限长。任何模型的上下文窗口都有 token 上限这是硬约束。很多新手会问“ai agent token 是什么意思”。简单说token 是模型处理文本的最小单位中文大致一个字占 1 到 2 个 token。一次会话读入的所有提示词、历史消息、工具说明书、中间执行结果都要占用 token 预算。预算耗尽模型就会“失忆”——越早的对话越容易被丢弃。运行时在这里必须做取舍全量保留历史吧很快撞顶只留最近几轮吧又会丢关键信息。OpenClaw 的做法是把状态分成短期、中期、长期。短期记忆放当前对话轮次长期记忆放更早时需要持久化的摘要或向量索引工作记忆放本次任务产生的中间变量。你应该把 token 预算想象成一个钱包每一轮对话都在花钱。运行时要做的是让每分钱都花在刀刃上老对话压缩成摘要工具说明书按需加载用不到的历史直接归档。理解了这一点你就明白为什么“上下文窗口越大越好”不完全对——窗口再大也架不住漫无边际地全塞进去。3.4 权限与安全栅栏agent 不只是一个聊天机器人如果我们允许 agent 访问真实文件系统、执行真实命令那么权限问题就不是可选配置而是生死线。“agent 安全”是所有 Harness 工程绕不开的课题。OpenClaw 运行时里有一层策略控制常见做法是给工具和路径打标allow明确允许执行deny明确拒绝ask执行前询问用户确认。我在实际使用中会默认把“修改系统文件、执行高危命令、访问私密路径”这三类设为 ask 或 deny等 agent 稳定运行一段时间后再逐步放宽。很多安全事故其实不是模型太聪明而是运行时权限太松。一个好的 runtime 应该做到“能力越大权限越紧”模型再强也只能在授权范围内动作。顺便说一句这也是 Harness 和 agent 区别最直观的体现一个裸 agent 是“有一个模型在说话”而一个 Harness 工程是“模型在声音外面套了一层规则、状态和安全边界”。有没有这层边界决定了你敢不敢让它碰真实资源。3.5 可观测性查一次异常胜过读十篇文档最后一个子系统是日志与回放。OpenClaw 会把每一条会话、每一次工具调用、每一个关键计费点都记录下来。我排查问题的套路固定三步先看最后几条日志确认是不是权限拒绝再看工具调用返回确认参数对不对最后才怀疑模型理解能力。有人觉得日志多看了心烦恰恰相反日志就是 agent 的黑匣子。只要黑匣子在就没有真正玄学的 bug。很多看起来“模型突然犯傻”的现象翻日志你会发现是某个技能返回了超大错误信息把上下文污染了。4. 部署场景会把运行时逼疯桌面、手机、机器人、内网服务器四个现场标题这么写是因为同一个 OpenClaw在不同环境下运行时脾气完全不同。很多部署教程只告诉你“怎么装”不告诉你“为什么这个环境要这样配”。下面把四个常见现场过一遍。4.1 桌面与 Windows Companion让 agent 长在 Windows 进程上把 OpenClaw 装在 Windows 上是最快的体验方式但如果你要让它操作本地应用而不是只回答文字问题就要理解 Companion 这个组件。你可以把它看作一个常驻操作系统上的进程负责唤起软件、读写剪贴板、操作窗口、在授权范围内执行命令。主 Harness 进程通过本地端口和它通信。最容易踩的坑是工具开了一大堆却忘了给窗口操作类动作配权限。结果 agent 说要打开浏览器实际上被策略挡住你就以为它“不聪明”。其实它很听话只是你不让它动手。桌面部署我建议先从两三个高频技能开始跑稳了再逐步加。另一个细节是 Windows 环境下的路径分隔符、命令执行方式跟 Linux 有差异写技能时不要硬编码路径风格。凡是需要访问文件系统的技能尽量用运行时提供的路径抽象接口而不是自己在代码里拼字符串。4.2 安卓 Termux移动运行时的真相是权限受限而非性能差手机上装 OpenClaw 是最近讨论度非常高的话题搜索热词里“如何用 termux 安装 openclaw 手机版下载步骤”被反复问到。Termux 是安卓上的终端模拟器本质上是一个运行在普通用户空间的 Linux 环境你可以装 Python、Node、Git然后把 OpenClaw 跑起来。很多人以为手机跑不动 agent其实性能不是最大瓶颈真正的瓶颈有三个没有 systemd进程需要靠 tmux 或 nohup 保住息屏或切网络都可能杀进程没有 root很多系统级权限拿不到运行时只能操作普通用户路径网络环境不稳定长会话需要断线重连机制。我的手机端实操流程大致是装 Termux配置基础包和 Git拉取 OpenClaw 代码建虚拟环境装依赖写配置最后丢进 tmux 会话里跑。手机端的 token 消耗和电脑端没有区别但屏幕操作和文件目录都是专用环境所以技能设计要更朴素。真正适合手机端做的任务是提醒、记录、定时检查而不是批量跑数据分析。关于“OpenClaw 只能用 API 方式用算力吗”这个问题在手机端尤其明显手机几乎不可能本地推理大模型更适合走云端 API。手机只是充当“移动控制台”和“常驻执行器”算力仍然在模型侧。4.3 ROS2 与 Gazebo 机器人agent 有了身体搜索热词里还有个组合很有意思rosclaw、OpenClaw、ROS2 humble、Gazebo。这代表的是把 agent 接到机器人系统上的玩法。到了机器人场景runtime 的含义就明显“硬核”了agent 不再只是在文本流里打转而是要读传感器数据、发控制指令、观察执行器反馈。ROS2 是机器人领域常用的中间件Gazebo 是经典物理仿真器。先接仿真器再接真机是绝大多数项目的稳妥路径。在 ROS2 Humble 环境下OpenClaw 的运行时通常会作为一个节点存在通过话题的发布和订阅去感知和操作机器人。这个部署形态对 Harness 的挑战很大机器人任务时间敏感度高你不能让模型每一小步都思考几秒。我的做法是给高频率动作开“直连通道”模型只做高层决策产出少量高层指令再由 ROS2 节点翻译成控制频率更高的底层动作。说白了模型做战略运行时做战术。层分清楚了机器人才不会看起来又蠢又慢。真机和仿真的另一个区别是安全等级。仿真里可以随意试错真机上一些小错误可能直接损坏设备。所以我强烈建议在运行时层面做一层“动作白名单”仿真环境放开真机环境收紧。这个策略同样来自 agent 安全的通用原则运行时是最后一道闸门。4.4 内网服务器与私有化部署模型和数据都不出门最后是内网服务器场景。很多团队希望在内部网络部署 OpenClaw连私有化模型。这里经常和 DeepSeek 关联在一起因为 DeepSeek 既能通过公共 API 使用也能借助本地推理服务做私有化部署。在 OpenClaw 里切换只需要改模型服务地址和模型名称。内网部署的好处很直接数据不出域、推理可控。代价是自己要维护推理服务的可用性、显存调度和升级节奏。运行时层面服务器部署相对简单有 systemd 或容器编排工具进程不会因为终端关闭而消失。我强烈建议内网环境用容器方式跑 OpenClaw 本体把数据目录挂载出来日志统一采集。这样升级、回滚都方便也回应了“deepseek harness 附带 skill 怎么部署到内网服务器”这类问题技能包是文件目录同步过去再在配置里启用即可跟模型走 API 还是本地没有强绑定关系。5. 一次完整的 OpenClaw 起步安装、接模型、写第一个 Skill概念聊完部署现场也过了一遍。现在走一遍我最常用的起步流程不贴全部截图但会把关键步骤和检查点写清楚。5.1 最小环境准备我建议最少准备三样东西一台能联网的电脑内存建议 8GB 以上16GB 更舒服一个 Git 客户端一个模型 API 的 Key或者一台已经跑好 Ollama 的机器。如果想用本地模型还要一块装得下目标模型的显卡。以 7B 量化模型为例通常 6GB 以上显存是底线。安装核心步骤大概是这样# 拉取代码具体仓库地址以官方文档为准这里是工程结构示意 git clone openclaw-repo cd openclaw # 创建虚拟环境避免污染系统 Python python -m venv .venv source .venv/bin/activate # 安装依赖 pip install -r requirements.txt # 生成默认配置 cp .env.example .env多花三十秒建虚拟环境是非常值得的。很多“依赖冲突”“版本不兼容”问题都是因为直接往系统 Python 里塞包导致的。5.2 接模型云端 API 和本地 Ollama 的区别OpenClaw 连接的是“OpenAI 兼容接口”。这意味着无论你用的是 DeepSeek 官方 API还是 Ollama 本地服务只要接口兼容都能无缝接入。关键配置项通常包括四个模型名称例如 deepseek-chat或本地量化包自定义名称模型服务地址云端是官方地址本地是 http://localhost:11434/v1API Key云端必须有本地可以不填或填占位符上下文窗口上限要匹配模型实际能力。配置项云端 API本地 Ollama服务地址官方地址http://localhost:11434/v1API Key需要可以不需要算力来源服务商机房自己机器数据出域会出本地完全本地适合阶段快速体验隐私敏感项目这里有个很容易忽略的细节模型名称必须和推理服务完全对齐。同样是 DeepSeek官方 API 的模型名和本地量化包的模型名不一样填错的话Harness 能启动但一调用就报错。5.3 写第一个 Skill让 Agent 学会一个查时间动作理论讲再多不如写一个真实技能。下面以极简的“查询当前时间”为例展示一个可用的技能长什么样。先创建目录skills/ └── get_current_time/ ├── SKILL.md └── main.pySKILL.md 写声明--- name: get_current_time description: 获取当前系统时间当用户询问当前日期时间时调用 args: format: type: string description: 时间格式默认 %Y-%m-%d %H:%M:%S required: false ---main.py 写执行体import sys import datetime fmt %Y-%m-%d %H:%M:%S if len(sys.argv) 1 and sys.argv[1]: fmt sys.argv[1] now datetime.datetime.now() print(now.strftime(fmt))看起来很简单但里面包含了技能层和运行时协作的关键逻辑声明文件描述“模型什么时候能调用、传什么参数”执行脚本负责“真正干活”。运行时会在模型要求调用时先读声明注册再校验入参最后放进沙箱执行。这里补一个很重要的经验description字段一定要写得具体。模型是靠描述来判断是否调用这个技能的。泛泛写“获取时间信息”不如写“当用户询问当前日期、当前时间、或希望生成时间戳时调用”。你已经让模型变聪明了哪怕模型不够聪明一个好的技能描述也能替你弥补很多解释成本。5.4 第一次运行的三个检查点配好模型、写完第一个技能启动 OpenClaw 后不要急着上复杂功能。按下面三条检查输入一句“现在几点了”看模型是否决定调用技能而不是凭空乱答。打开运行日志确认出现过技能注册成功的记录。手动停掉进程重新启动确认会话状态能恢复。这三个检查点同时验证了模型接入、技能调用、运行时状态管理这三条基础链路。三条都过说明你的最小系统已经站稳了。我第一次启动时就挂在第一关。模型没有调用技能而是凭训练记忆给了个大致时间看起来像模像样实际上完全不能用。原因就是技能描述写得太泛模型压根没意识到该调用工具。改完描述立刻正常。6. 起步阶段最容易在“运行时”上摔的四个坑最后分享四个我见过最多、也亲身踩过的坑。它们都不深但每一个都能让你白折腾好几个小时。6.1 把 token 预算当成聊天记录条数很多人的第一反应是把上下文窗口想象成“聊天记录条数”这很危险。token 不是按条数算而是按文本长度算。一段 2000 字的日志、一份 50 行的工具说明书分分钟吃掉几千 token。运行时一般会对工具返回结果做截断但如果你写技能时完全不管输出量谁也救不了你。我的习惯是每个技能的输出尽量控制在几百 token 以内必要时自己先做摘要再返回。这既省预算也减少模型被无关信息干扰的概率。6.2 只接模型不配权限agent 上来就想动文件这是“agent 安全”里最基础的教训。默认配置通常偏宽松agent 能访问用户目录、能执行命令。你装好后如果没动权限很可能在某一轮对话里收到“需要删除文件 X”的请求而 agent 已经开始准备照做了。别把希望寄托在模型的自我判断上。模型的判断受提示词影响很大一套 prompt 就能让它改变行为。权限策略是运行时层面的硬约束必须写在配置里不能在对话里靠商量。记住一句话模型是可能性权限是确定性。6.3 终端窗口一关运行时跟着灰飞烟灭本地测试时很多人直接在终端前台运行 OpenClaw然后跑去干别的回来发现窗口被系统关了agent 也下线了。如果你的场景需要长时间运行请务必让进程脱离终端常见方式就是 systemd 服务、容器或者 tmux 和 nohup。手机端尤其要注意Termux 里不用 tmux 的话息屏、切网络、切后台都可能让进程静默消失。这个坑很小但几乎每个人都踩过。踩过一次之后你就懂了进程管理是运行时的一部分不是你临时想起来才做的事。6.4 Skill 能加载但执行报错schema 与命名空间对不上最隐蔽的一个坑声明文件写对了、目录也放对了但一执行就报参数校验失败。十有八九是字段名和运行时预期不一致。比如运行时统一用下划线风格命名参数你的声明文件里却用了连字符或者你的格式版本写得太老运行时解析不了。排查方法很简单看日志里“参数解析失败”的具体报错字段名用报错信息反查声明文件。报错信息其实已经把答案告诉你一半了剩下的就是对照字段命名风格改一遍。最后再分享一个调试习惯每次给 agent 加新技能我都会在日志里单独查一次“技能名称 参数解析”的关键字确认注册和校验都通过再关掉日志窗口。这个动作只需要十几秒却能提前排掉大部分“技能装好了但用不了”的隐患。运行时这东西看着复杂但抽丝剥茧之后核心无非是循环、执行、记忆、权限、日志这五件事。把这篇里的概念消化掉下一期我们就能进入更深的玩法如何设计多机协作的运行时拓扑、如何做细粒度的权限模型、以及在高压力场景下怎么压榨 token 预算。到那时你会发现 OpenClaw 的 Harness 设计里处处都是工程经验的沉淀。
