Harness Engineering：从 OpenClaw 看 AI 助理的基础设施建设

当 AI 从"玩具"变成"工具"，Harness Engineering 成为关键竞争力。

2026 年 3 月，AI 工程化正在经历一场静默的革命。

人们谈论模型、谈论 Agent、谈论应用场景，但很少人谈论Harness Engineering------那个让 AI 从 demo 变成产品的"脏活累活"。

本文从 OpenClaw 的架构出发，聊聊 Harness Engineering 到底是什么，以及为什么它可能是 AI 工程化的下一站。

---

01 / 什么是 Harness Engineering？

Harness，字面意思是"马具"、"控制装置"。

在软件工程里，Harness Engineering 指的是：为 AI 系统搭建运行、管理、监控所需的基础设施。

它不是模型训练，不是 Prompt 工程，而是让模型能在生产环境稳定运行的那层"中间件"。

OpenClaw 的 Harness 架构

OpenClaw 是一个典型的 Harness Engineering 案例。它的核心不是模型（用的是第三方 API），而是如何把模型变成可用的个人助理。

flowchart TB subgraph UserLayer["用户交互层"] direction TB WA[WhatsApp] TG[Telegram] DC[Discord] SL[Slack] WC[WebChat] end subgraph HarnessLayer["Harness 层（OpenClaw Gateway）"] direction TB SM[Session 管理] CR[Channel 路由] TO[Tool 编排] EV[Cron/Event 调度] end subgraph ModelLayer["模型层"] direction TB GPT[OpenAI] CL[Anthropic] GL[Google] BL[Bailian] LC[本地模型] end UserLayer --> HarnessLayer HarnessLayer --> ModelLayer style UserLayer fill:#f0f4ff,stroke:#667eea,stroke-width:2px style HarnessLayer fill:#fff7ed,stroke:#f97316,stroke-width:2px style ModelLayer fill:#f3f4f6,stroke:#6b7280,stroke-width:2px

Harness 层做的事：

• Session 管理：多用户隔离、上下文维护、状态持久化
• Channel 路由：消息从微信/Telegram/Discord 进来，统一处理后再发回去
• Tool 编排：浏览器、文件系统、定时任务、子 Agent 的调用和结果聚合
• Event 调度：定时任务、webhook、设备事件的处理

这些都不是"AI 能力"，但缺了任何一块，AI 都无法真正用起来。

---

02 / Harness Engineering 的核心挑战

挑战 1：多通道消息的"归一化"

OpenClaw 支持 20+ 消息渠道：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、微信、飞书......

每个渠道的消息格式都不一样：

• Discord：有 thread、emoji reaction、embed、component
• Telegram：有 inline keyboard、reply、forward、media group
• 微信：有公众号文章、小程序卡片、语音消息
• Signal：只有纯文本和基础图片

Harness 层的任务：

0. 把所有渠道的消息"翻译"成统一的内部格式
1. 处理完后，再"翻译"回对应渠道的格式

// 伪代码示例
interface UnifiedMessage {
  id: string;
  channelId: string;
  senderId: string;
  content: string;
  attachments?: Attachment[];
  replyTo?: string;
  metadata: Record<string, any>;
}
​
// Discord 适配器
function discordToUnified(discordMsg: DiscordMessage): UnifiedMessage {
  return {
    id: discordMsg.id,
    channelId: `discord:${discordMsg.channelId}`,
    senderId: `discord:${discordMsg.author.id}`,
    content: discordMsg.content,
    attachments: discordMsg.attachments.map(a => ({
      type: a.type === 'image' ? 'image' : 'file',
      url: a.url,
      filename: a.filename
    })),
    replyTo: discordMsg.reference?.messageId,
    metadata: {
      discord: {
        guildId: discordMsg.guildId,
        reactions: discordMsg.reactions,
        components: discordMsg.components
      }
    }
  };
}
​
// 微信适配器
function wechatToUnified(wechatMsg: WechatMessage): UnifiedMessage {
  return {
    id: wechatMsg.MsgId,
    channelId: `wechat:${wechatMsg.FromUserName}`,
    senderId: `wechat:${wechatMsg.FromUserName}`,
    content: wechatMsg.Content,
    attachments: wechatMsg.Attachments?.map(a => ({
      type: a.type,
      url: a.url
    })),
    metadata: {
      wechat: {
        msgType: wechatMsg.MsgType,
        event: wechatMsg.Event
      }
    }
  };
}

难点：

• 每个渠道的 API 都在变（Discord 的 component、微信的卡片消息）
• 有些功能无法对齐（比如 Discord 的 thread 在微信没有对应概念）
• 需要维护 20+ 个适配器，每个都要处理边界情况

挑战 2：Session 状态管理

AI 助理是有状态的。

用户说"把刚才那个链接发我"，AI 需要知道：

• "刚才"是哪条消息？
• "那个链接"是哪个链接？
• "发我"是发到哪个渠道？

OpenClaw 的 Session 管理包含：

• Session 隔离：不同用户、不同群组的对话上下文不能混
• 状态持久化：Gateway 重启后，Session 不能丢
• 跨渠道关联：同一个用户在微信和 Discord 的对话要能关联

interface Session {
  sessionKey: string;
  channelId: string;
  userId: string;
  model: string;
  thinking: 'low' | 'medium' | 'high';
  messages: Message[];
  context: Record<string, any>;
  createdAt: number;
  lastActiveAt: number;
}
​
// Session 路由示例
function routeMessage(msg: UnifiedMessage): Session {
  // DM 消息：每个用户一个 Session
  if (msg.channelType === 'dm') {
    return getOrCreateSession({
      sessionKey: `dm:${msg.senderId}`,
      channelId: msg.channelId,
      userId: msg.senderId
    });
  }
  
  // 群组消息：每个群组一个 Session（或每个用户 + 群组组合）
  if (msg.channelType === 'group') {
    return getOrCreateSession({
      sessionKey: `group:${msg.channelId}:${msg.senderId}`,
      channelId: msg.channelId,
      userId: msg.senderId,
      context: { groupId: msg.channelId }
    });
  }
}

难点：

• Session 太多会爆内存（需要 LRU 淘汰）
• Session 持久化要考虑并发写入
• 跨渠道关联需要用户身份映射（同一个人在微信和 Discord 的 ID 不同）

挑战 3：Tool 编排与错误处理

AI 助理的价值在于能做事，不只是聊天。

OpenClaw 的 Tool 包括：

• browser：浏览器控制（打开网页、截图、点击、输入）
• canvas：Canvas 渲染（在 macOS 上显示 UI）
• nodes：设备控制（拍照、录屏、通知）
• cron：定时任务
• sessions：子 Agent 管理
• filesystem：文件读写

Tool 编排的复杂性：

// 用户说："帮我监控竞品价格，每天下午 5 点发我"
// AI 需要：
// 1. 创建一个 cron 任务
// 2. 任务内容是打开竞品网页、抓取价格、生成对比图
// 3. 把结果发到用户的指定渠道
​
async function setupPriceMonitor(userRequest: UserRequest) {
  // 1. 解析需求
  const { competitorUrls, targetTime, notifyChannel } = parseRequest(userRequest);
  
  // 2. 创建 cron 任务
  const cronJob = await cron.add({
    schedule: {
      kind: 'cron',
      expr: `0 ${targetTime} * * *`,  // 每天指定时间
      tz: 'Asia/Shanghai'
    },
    payload: {
      kind: 'agentTurn',
      message: `检查以下竞品价格：${competitorUrls.join(', ')}`
    },
    sessionTarget: 'isolated'  // 在独立 Session 运行
  });
  
  // 3. 创建子 Agent 处理抓取任务
  const scraperAgent = await sessions.spawn({
    task: '抓取竞品价格并生成对比报告',
    runtime: 'subagent',
    mode: 'run',
    attachments: competitorUrls.map(url => ({
      name: 'url.txt',
      content: url
    }))
  });
  
  // 4. 设置通知回调
  scraperAgent.onComplete((result) => {
    message.send({
      to: notifyChannel,
      message: `今日竞品价格报告：\n${result.summary}`
    });
  });
}

难点：

• Tool 调用可能失败（网页打不开、API 超时、权限不足）
• 需要重试机制和降级策略
• 子 Agent 可能跑飞（需要超时和 kill 机制）
• Tool 调用链太长会导致延迟（用户等不及）

挑战 4：安全与权限控制

AI 助理能访问用户的消息、文件、设备，安全是生命线。

OpenClaw 的安全设计：

• DM Pairing：陌生用户发消息先配对，防止骚扰
• Tool 权限：敏感操作（删除文件、发消息）需要确认
• 消息隔离：群组消息不能泄露到其他渠道
• 本地优先：数据存在本地，不上传第三方

// DM Pairing 逻辑
async function handleInboundDM(msg: UnifiedMessage) {
  const sender = msg.senderId;
  const channel = msg.channelId;
  
  // 检查是否在白名单
  const isAllowed = await allowlist.check(sender, channel);
  
  if (!isAllowed) {
    // 生成配对码
    const pairingCode = generatePairingCode();
    await pairingStore.set(channel, pairingCode, sender);
    
    // 发送配对提示
    await message.send({
      to: channel,
      message: `收到来自 ${sender} 的消息。\n\n请在终端运行以下命令完成配对：\n```\nopenclaw pairing approve ${channel} ${pairingCode}````
    });
    
    // 丢弃原始消息
    return;
  }
  
  // 白名单用户，正常处理
  await processMessage(msg);
}

难点：

• 安全性 vs 便利性的平衡（配对太麻烦用户会跑）
• 权限模型要细粒度（能读文件不代表能删文件）
• 审计日志要完整（谁在什么时候做了什么）

---

03 / Harness Engineering 的技术栈

基于 OpenClaw 的实践，Harness Engineering 的技术栈可以总结为：

1. 消息总线（Event Bus）

所有消息、事件、命令都通过统一的事件总线流转。

// 事件类型
type GatewayEvent =
  | { type: 'message:inbound'; payload: UnifiedMessage }
  | { type: 'message:outbound'; payload: OutboundMessage }
  | { type: 'session:created'; payload: Session }
  | { type: 'tool:call'; payload: ToolCall }
  | { type: 'cron:trigger'; payload: CronJob };
​
// 事件处理器
gateway.on('message:inbound', async (msg) => {
  const session = routeMessage(msg);
  const response = await agent.process(msg, session);
  await sendResponse(response);
});

2. 适配器模式（Adapter Pattern）

每个消息渠道、每个 Tool 都是一个适配器。

interface ChannelAdapter {
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  send(msg: OutboundMessage): Promise<void>;
  onMessage(handler: (msg: any) => void): void;
}
​
class DiscordAdapter implements ChannelAdapter {
  private client: Discord.Client;
  
  async connect() {
    this.client = new Discord.Client({ intents: [...] });
    await this.client.login(token);
  }
  
  onMessage(handler) {
    this.client.on('messageCreate', (msg) => {
      handler(discordToUnified(msg));
    });
  }
}
​
class TelegramAdapter implements ChannelAdapter {
  // ...
}

3. 状态机（State Machine）

Session 状态、Tool 调用、子 Agent 都是状态机。

type SessionState = 'idle' | 'processing' | 'waiting_tool' | 'error';
​
interface SessionMachine {
  state: SessionState;
  transitions: {
    from: SessionState;
    trigger: string;
    to: SessionState;
    action?: () => void;
  }[];
}
​
const sessionMachine: SessionMachine = {
  state: 'idle',
  transitions: [
    { from: 'idle', trigger: 'message:received', to: 'processing' },
    { from: 'processing', trigger: 'tool:call', to: 'waiting_tool' },
    { from: 'waiting_tool', trigger: 'tool:result', to: 'processing' },
    { from: 'processing', trigger: 'response:sent', to: 'idle' },
    { from: '*', trigger: 'error', to: 'error' }
  ]
};

4. 可观测性（Observability）

日志、指标、追踪是 Harness 的"眼睛"。

// 结构化日志
logger.info('message:processed', {
  sessionId: session.sessionKey,
  channelId: msg.channelId,
  model: session.model,
  latency: Date.now() - startTime,
  tokens: { prompt: 1200, completion: 300 }
});
​
// 指标收集
metrics.increment('message.inbound');
metrics.histogram('tool.latency', latency);
metrics.gauge('session.active', activeSessions.length);
​
// 分布式追踪
const span = tracer.startSpan('agent.process');
span.setTag('model', session.model);
span.setTag('thinking', session.thinking);
await agent.process(msg, session);
span.finish();

---

04 / 为什么 Harness Engineering 重要？

1. 模型会贬值，Harness 不会

GPT-5 会出来，Claude-5 会出来，模型能力会越来越强、价格会越来越低。

但你的 Harness------你的消息适配器、你的 Session 管理、你的 Tool 编排------是你独有的，不会贬值。

2. Harness 决定用户体验

用户不在乎你用的是什么模型，只在乎：

• 消息能不能及时回复？
• 说的事情能不能做到？
• 会不会泄露隐私？

这些都是 Harness Engineering 的范畴。

3. Harness 是护城河

模型可以换（OpenClaw 支持 10+ 模型供应商），但 Harness 一旦建成，迁移成本极高。

用户在你的 Harness 里沉淀了：

• 消息渠道配置
• 自动化工具
• 定时任务
• 使用习惯

换模型容易，换 Harness 难。

---

05 / Harness Engineering 的未来

基于 OpenClaw 的实践，预测几个趋势：

1. Harness 即服务（HaaS）

现在每个 AI 项目都要自己写 Harness（消息适配、Session 管理、Tool 编排）。

未来会出现Harness 即服务，像 Vercel 之于 Web 应用。

2. 标准化协议

消息渠道的适配器会标准化，就像 USB-C。

OpenClaw 已经在做这件事：统一的消息格式、统一的 Tool 接口、统一的 Session 管理。

3. 本地优先

隐私意识觉醒，用户不希望所有消息都经过第三方服务器。

OpenClaw 的"本地 Gateway + 本地模型"模式会成为主流。

4. 多 Agent 协作

单个 Agent 能力有限，未来是多 Agent 协作的时代。

Harness 需要管理：

• Agent 之间的任务分配
• 结果聚合
• 冲突解决

OpenClaw 的 sessions_spawn + subagents 已经在往这个方向走。

---

06 / 写在最后

Harness Engineering 不性感。

它没有"AGI 即将到来"那么激动人心，没有"Prompt 工程"那么神秘。

但它是 AI 工程化的必经之路。

当 AI 从"能聊天"变成"能做事"，Harness Engineering 的价值会被重新认识。

模型是引擎，Harness 是底盘。引擎再强，底盘不稳，车也开不快。

---

参考资料：

0. OpenClaw 官方文档：docs.openclaw.ai
1. OpenClaw GitHub：github.com/openclaw/op...
2. Harness Engineering 最佳实践（本文总结）

---

免责声明： 本文基于 OpenClaw 开源项目实践总结，部分观点为作者个人见解。技术细节请以官方文档为准。