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 什么时候能用）、执行体（代码或脚本）、校验规则（入参出参的格式约束）。

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 调用，而是“多次调用组成的一个循环”。这个循环是运行时里最重要的子系统，我习惯叫它执行循环。每轮会话，运行时会经历这样一组状态：

1. 初始启动：读取系统提示词，注入全局状态，建立会话 ID。
2. 模型调用：把当前消息列表发给模型，附上当前可用的技能列表。
3. 输出解析：拿回模型输出，区分它到底是普通文本回复，还是工具调用指令。
4. 工具执行：如果是指令，按声明的 Skill 去执行，取回结果。
5. 观察注入：把执行结果作为新的消息放回消息列表。
6. 回到第二步，或者由 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/v1；
• API Key，云端必须有，本地可以不填或填占位符；
• 上下文窗口上限，要匹配模型实际能力。

这里有个很容易忽略的细节：模型名称必须和推理服务完全对齐。同样是 DeepSeek，官方 API 的模型名和本地量化包的模型名不一样，填错的话，Harness 能启动，但一调用就报错。

5.3 写第一个 Skill：让 Agent 学会一个查时间动作

理论讲再多，不如写一个真实技能。下面以极简的“查询当前时间”为例，展示一个可用的技能长什么样。

先创建目录：

skills/ └── get_current_time/ ├── SKILL.md └── main.py

SKILL.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 后，不要急着上复杂功能。按下面三条检查：

1. 输入一句“现在几点了”，看模型是否决定调用技能，而不是凭空乱答。
2. 打开运行日志，确认出现过技能注册成功的记录。
3. 手动停掉进程，重新启动，确认会话状态能恢复。

这三个检查点同时验证了模型接入、技能调用、运行时状态管理这三条基础链路。三条都过，说明你的最小系统已经站稳了。

我第一次启动时，就挂在第一关。模型没有调用技能，而是凭训练记忆给了个大致时间，看起来像模像样，实际上完全不能用。原因就是技能描述写得太泛，模型压根没意识到该调用工具。改完描述，立刻正常。

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 设计里，处处都是工程经验的沉淀。