第12章 OpenClaw / Harness 与 Agent 生产基础设施

12.1 Gateway 中心化架构 ------ Agent 生产化设计模式

本节我们设计一个「假设的」生产级 Agent 架构，命名为 OpenClaw。

它不是一个真实存在的开源项目，而是一个用于教学的参考设计。

核心设计理念：「不是一个 Agent 框架，而是 Agent 本身」

------ 这条定位把它和 LangChain/crewAI 等框架区隔开来。

设计目标：

一个中心化的 Gateway（Node.js 控制平面），

统一管理多条消息渠道 + 多个 LLM Provider + 持久化记忆。

OpenClaw 的 Gateway 中心化架构：

复制代码

│ │ │

┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐

│ Channel 1 │ │ Channel 2 │ │ Channel 3 │

│ WhatsApp │ │ Telegram │ │ Discord │

└─────────────┘ └─────────────┘ └─────────────┘

📊 架构示意

复制代码

  ┌─────────────────────────────────────────────────────────┐
  │                    The Gateway                           │
  │                  (Node.js 控制平面)                       │
  │                                                          │
  │  ┌──────────┐  ┌──────────────┐  ┌──────────────────┐  │
  │  │ 消息路由   │  │ 状态管理中心  │  │ 安全策略执行      │  │
  │  │          │  │              │  │                  │  │
  │  └──────────┘  └──────────────┘  └──────────────────┘  │
  │                                                          │
  │  ┌──────────────────────────────────────────────────┐  │
  │  │             LLM Provider Abstraction             │  │
  │  │   Claude | GPT | Gemini | Ollama | 任意兼容API    │  │
  │  └──────────────────────────────────────────────────┘  │
  │                                                          │
  │  ┌──────────────────────────────────────────────────┐  │
  │  │            Persistent Memory Store               │  │
  │  │         长期记忆 + 用户偏好 + 对话历史             │  │
  │  └──────────────────────────────────────────────────┘  │
  └─────────────────────────────────────────────────────────┘

Gateway 的职责：

消息路由：从不同 Channel 接收消息，路由到正确的 LLM Provider
状态管理：维护每个用户的对话状态和 Agent 运行状态
安全策略：权限控制、速率限制、内容过滤
Provider 抽象：统一接口，可热切换底层 LLM

Channel Integrations（消息渠道）：

OpenClaw 不是只能通过 CLI 交互，它可以接入：

WhatsApp
Telegram
Discord
Slack
iMessage
Web Chat

Agent 在这些渠道上表现得像一个「真人」。

12.2 OpenClaw 的 AgentSkills 和 ClawHub

这是 OpenClaw 最具特色的设计。

AgentSkills：

类似 Node.js 的 npm 包
社区可以开发、发布、安装 Agent 的「技能」
每个 Skill 是一个独立的模块（含工具定义 + 实现）

示例 Skill：

skill/weather → 天气查询

skill/calendar → 日历管理

skill/email → 邮件发送

skill/translation → 翻译服务

skill/code-review → 代码审查

ClawHub：

AgentSkills 的注册中心
类似 npm registry 或 Docker Hub
社区贡献和共享 Skill

与 MCP 的关系：

MCP 定义了「协议」------ 如何连接和通信
AgentSkill 定义了「能力」------ 具体做什么
一个 AgentSkill 可以通过 MCP 协议暴露给 LLM
两者是协议层和功能层的关系

12.2.1 Gateway 模式为什么适合 Agent？------ 工程取舍分析

面试官问：「Agent 为什么用 Gateway 模式，不用微服务+API Gateway？」

▍ Gateway vs 微服务的核心差异

传统微服务 → 每个服务独立部署、独立数据库、独立运维

Agent 的 Gateway → 集中式控制平面 + 可插拔的 Channel/Provider/AgentSkill

为什么 Agent 架构不适合微服务模式？

成本共享问题 ------ Agent 的「状态」不是无状态的

微服务推崇 stateless → 但 Agent 的对话上下文必须共享→ 每个请求都重建上下文 = 前 20 条消息重新计费 = 成本爆炸

→ Gateway 模式下对话历史存在控制平面，无需跨服务传递

LLM Provider 的切换频率 ------ 应该是运行时切换，不是部署时

微服务要换模型 → 改代码 → 重新部署 → 全量回归测试

Gateway 换模型 → /model gpt-4o → 即刻生效，零部署

AgentSkill 的安装卸载 ------ 需要运行时热插拔

微服务下装新 Skill → 部署新服务 → 配 Service Discovery

Gateway 下装新 Skill → install agent-skill/weather → 即刻生效

▍ Gateway 模式的设计取舍（面试可以主动分析）

优点：集中式状态管理、运行时热切换 Provider/模型、单点安全审计

代价：Gateway 成为单点瓶颈（需要水平扩展 + 队列）

解决：Gateway 本身可以是多实例 + 共享存储的

类比：Gateway 模式像「OS 内核」------ 管理所有资源，

但允许动态加载驱动（AgentSkill）和切换硬件（LLM Provider）

12.3 Harness (OpenHarness) ------ 开源编码 Agent 黑马

Harness 是一个假设的编码 Agent 参考设计。

核心亮点：

CLI + SDK 双模式（既可以命令行用，也可以嵌入代码）
支持任意 LLM（Claude、GPT、Gemini、Ollama 等）
内置评测框架（持续集成友好的工具调用验证）
多提供商兼容（一个命令切换模型）

Harness 的 REPL 命令体系：

📊 架构示意

复制代码

  ┌────────────────┬──────────────────────────────────────┐
  │     命令        │               功能                    │
  ├────────────────┼──────────────────────────────────────┤
  │ /help          │ 帮助和提示                            │
  │ /connect       │ 配置 API Key                         │
  │ /model         │ 切换模型（/model gpt-5.2）            │
  │ /plan          │ 用只读 Agent 规划实现方案              │
  │ /review        │ 审查代码变更                          │
  │ /team          │ 分解任务并并行执行多个 Agent           │
  │ /status        │ 显示提供商、模型、会话、成本           │
  │ /cost          │ 显示 Token 使用量和费用               │
  └────────────────┴──────────────────────────────────────┘

Harness 的权限模式：

默认模式：每个工具调用需要用户确认
Bypass 模式：完全自动批准（适合 CI/CD 脚本）

应用场景：

harness "Fix the authentication bug in auth.py"

harness --permission bypass "Run all tests and fix failures"

harness -p ollama -m llama3.3 "Write unit tests for utils.py"

与 Claude Code 的对比：

📊 架构示意

复制代码

  ┌──────────────┬────────────────────┬───────────────────┐
  │     维度      │      Harness        │    Claude Code     │
  ├──────────────┼────────────────────┼───────────────────┤
  │ 源           │ 开源                │ 闭源（但可逆向）    │
  │ 模型绑定      │ 任何模型            │ Claude 系列        │
  │ 本地模型      │ 支持 (Ollama)       │ 不支持             │
  │ 多Agent      │ /team 命令          │ Task 工具          │
  │ 成熟度        │ Alpha 阶段          │ 生产级别            │
  │ 社区          │ 快速发展中          │ 官方支持            │
  └──────────────┴────────────────────┴───────────────────┘

12.4 Agent 评测基础设施 ------ MultiAgentEval

MultiAgentEval 是一个企业级的 Agent 评测框架。

核心概念：

Scenario（评测场景）

定义要评测什么：场景描述 + 任务列表 + 成功标准

Task（评测任务）

每个 Scenario 包含多个 Task：

task_id：任务ID
description：Agent 收到的提示词
success_criteria：评测指标 + 阈值
required_tools：Agent 应该调用的工具
expected_state_changes：期望的状态变化
Tool Sandbox（工具沙箱）
模拟工具调用（不调用真实 API）
工具行为由 Scenario 定义控制
支持策略检查（Policy Check）
Metrics（评测指标）
policy_compliance：策略合规性
path_parsimony：执行效率（步骤越少越好）
state_verification：状态验证
calculation_accuracy：计算准确性
planning_quality：规划质量
root_cause_analysis_correctness：诊断准确性
consistency_score：多次运行一致性
luna_judge_score：LLM-as-Judge 语义评测

评测流程：

│

▼

复制代码

┌───────────────┐

│ Tool Sandbox │ ← 模拟工具调用

│ Policy Engine │ ← 检查合规性

└───────────────┘

📊 架构示意

复制代码

  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
  │ 加载场景  │───→│ 执行任务  │───→│ 收集指标  │───→│ 生成报告  │
  └──────────┘    └──────────┘    └──────────┘    └──────────┘

12.5 Agent 生产基础设施全景图

一个生产级 Agent 系统需要以下基础设施：

📊 架构示意

复制代码

┌─────────────────────────────────────────────────────────────┐
│                      生产基础设施全景                          │
├─────────────────┬─────────────────┬─────────────────────────┤
│   可观测性       │      评测        │        安全              │
│  ─────────────  │  ─────────────  │  ─────────────────────  │
│  • LangSmith     │  • MultiAgentEval│  • Prompt Injection防护 │
│  • LangFuse      │  • RAGAS        │  • 权限最小化            │
│  • OpenTelemetry │  • AgentBench   │  • 审计日志              │
│  • 自定义 Tracing│  • SWE-bench    │  • 数据脱敏              │
│  • 日志聚合      │  • 自定义评测集   │  • Rate Limiting       │
├─────────────────┼─────────────────┼─────────────────────────┤
│   成本控制       │      部署        │        可靠性            │
│  ─────────────  │  ─────────────  │  ─────────────────────  │
│  • 模型分层      │  • Docker/K8s    │  • 重试机制              │
│  • 语义缓存      │  • Serverless    │  • 超时控制              │
│  • Token 预算    │  • 负载均衡      │  • 熔断器                │
│  • 批处理        │  • 蓝绿部署      │  • 降级策略              │
│  • 使用配额      │  • Feature Flag  │  • 健康检查              │
└─────────────────┴─────────────────┴─────────────────────────┘

可观测性（最重要！）：

每次 LLM 调用：model + input_tokens + output_tokens + latency
每次 Tool Call：tool_name + args + result + latency
每个 Agent 步骤：step_number + action + observation
指标看板：成功率、平均延迟、Token 消耗趋势、错误分布

LangSmith / LangFuse 的使用：

复制代码

┌──────────┐ ┌──────────────┐ ┌──────────┐

│ Agent │────→│ LangSmith │────→│ 可视化 │

│ 执行过程 │ │ (Tracing) │ │ Dashboard │

└──────────┘ └──────────────┘ └──────────┘

│

▼

┌──────────┐

│ 告警系统 │ ← PagerDuty / Slack

└──────────┘

📝 对应的代码实现

checkprint_checklistAgentProductionChecklist

复制代码

class AgentProductionChecklist:
    """Agent 生产化就绪度检查清单。"""

    CHECKLIST = [
        # 可观测性
        ("可观测性", "每次 LLM 调用记录 input/output tokens + latency"),
        ("可观测性", "每次 Tool Call 记录工具名 + 参数 + 结果 + 耗时"),
        ("可观测性", "核心指标看板：成功率 / P50/P99延迟 / Token消耗趋势"),
        ("可观测性", "告警规则：成功率 < 95% → 通知"),
        # 评测
        ("评测", "离线评测集覆盖典型场景 + 边界条件 + Bad Case"),
        ("评测", "上线前回归评测（确保新版本不退化）"),
        ("评测", "A/B 测试框架（对比新老版本效果）"),
        # 安全
        ("安全", "Prompt Injection 检测与过滤"),
        ("安全", "工具调用分级：读自动 / 写确认 / 危险需二次确认"),
        ("安全", "审计日志：记录所有操作，可追溯"),
        ("安全", "敏感信息脱敏（API Key、用户数据等）"),
        # 成本
        ("成本", "模型分层：简单任务用小模型 (gpt-4o-mini)"),
        ("成本", "语义缓存：避免重复查询消耗 Token"),
        ("成本", "Token 预算告警：单用户/单日/单月上限"),
        # 可靠性
        ("可靠性", "LLM 调用重试 (exponential backoff)"),
        ("可靠性", "超时控制 (30s 超时 + 降级策略)"),
        ("可靠性", "熔断器：连续失败 N 次 → 暂停 → 恢复"),
        ("可靠性", "优雅降级：LLM 不可用时返回兜底回答"),
    ]

    class="d">@classmethod
    def check(cls) -> list[tuple[str, str, bool]]:
        """返回检查清单及每项的完成状态（这里标注为待检查）。

        Returns:
            (类别, 检查项, 是否完成) 的列表。
        """
        return [(cat, item, False) for cat, item in cls.CHECKLIST]

    class="d">@classmethod
    def print_checklist(cls):
        """打印检查清单。"""
        for cat, item in cls.CHECKLIST:
            print(f"  [{cat:8s}] ☐ {item}")

12.6 全课程体系梳理 ------ 回顾与展望

现在你学完了全部 12 章：

Ch0 → 课程概览，理解 Agent 是什么

Ch1-3 → Agent 的基础理论（循环、组件、类型）

Ch4-5 → Agent 的工程实践（框架、Multi-Agent）

Ch6-7 → Agent 的评估与求职（评测、面试）

Ch8 → Claude Code 架构（nO/h2A/Compaction/SubAgent）

Ch9 → RAG 深度（Naive→Advanced→GraphRAG→Agentic RAG）

Ch10 → MCP 协议（JSON-RPC/原语/能力协商/传输层）

Ch11 → Tool Calling 底层（OpenAI vs Anthropic/Streaming/Strict）

Ch12 → 生产基础设施（OpenClaw/Harness/评测/可观测性）← 你在这里

面试时你可以自信地讨论：

✓ Agent 的核心循环和组件

✓ Function Calling 的底层原理

✓ MCP 协议的架构和调用流程

✓ RAG 的技术演进和 GraphRAG

✓ Claude Code 的设计哲学

✓ Multi-Agent 系统的架构模式

✓ Agent 的生产化 Checklist

核心能力矩阵：

📊 架构示意

复制代码

┌──────────────────┬──────────────────────────┬─────────┐
│      能力         │         覆盖章节          │  深度    │
├──────────────────┼──────────────────────────┼─────────┤
│ Agent 基础理论    │ Ch1, Ch2, Ch3            │  ⭐⭐⭐  │
│ 框架上手          │ Ch4, Ch5                 │  ⭐⭐⭐  │
│ RAG 技术栈        │ Ch9                      │  ⭐⭐⭐⭐ │
│ MCP 协议          │ Ch10                     │  ⭐⭐⭐⭐ │
│ Tool Calling     │ Ch11                     │  ⭐⭐⭐⭐⭐│
│ Claude Code 架构  │ Ch8                      │  ⭐⭐⭐⭐⭐│
│ 生产基础设施      │ Ch6, Ch12                │  ⭐⭐⭐  │
│ 面试准备          │ Ch7                      │  ⭐⭐⭐⭐ │
└──────────────────┴──────────────────────────┴─────────┘

12.7 本章总结

核心要点回顾：

Gateway 架构（本章的 OpenClaw 假设设计）
Gateway 中心化架构（Node.js 控制平面）
多 Channel 接入（WhatsApp/Telegram/Discord）
AgentSkills + ClawHub 插件生态
设计定位：「是 Agent，不是框架」
编码 Agent 参考设计（本章的 Harness 假设设计）
CLI + SDK 双模式
支持任意 LLM + 本地模型
/team 命令实现并行 Multi-Agent
Agent 评测基础设施
MultiAgentEval：企业级评测框架
核心概念：Scenario → Task → Sandbox → Metrics
8 种内置评测指标
生产 Checklist（面试最爱问！）
可观测性（Tracing + Dashboard + Alerting）
评测体系（离线评测 + A/B测试 + 回归评测）
安全防护（Prompt Injection + 权限分级 + 审计）
成本控制（模型分层 + 缓存 + 预算）
可靠性（重试 + 超时 + 熔断 + 降级）

面试速记：

"Agent 怎么上生产？"

→ 可观测性 + 评测体系 + 安全防护 + 成本控制 + 可靠性

→ 每个环节都可以展开讲具体方案

→ 关键在于「工程化思维」而非「Demo 思维」

📝 对应的代码实现

复制代码

if __name__ == "__main__":
    print("╔══════════════════════════════════════════════════════╗")
    print("║  第12章：OpenClaw / Harness 与 Agent 生产基础设施      ║")
    print("║  Gateway架构 · AgentSkills · 评测 · 生产Checklist    ║")
    print("╚══════════════════════════════════════════════════════╝")

    print("\n▶ 12.1 OpenClaw 架构概览")
    print("-" * 50)
    oc_features = [
        "Gateway 中心化架构（Node.js 控制平面）",
        "多 Channel 接入：WhatsApp / Telegram / Discord / Slack",
        "LLM Provider 抽象：Claude / GPT / Gemini / Ollama",
        "持久化记忆存储：用户偏好 + 对话历史",
        "AgentSkills + ClawHub：Agent 技能生态（假设设计）",
    ]
    for f in oc_features:
        print(f"  • {f}")

    print("\n▶ 12.2 AgentSkills vs MCP 关系")
    print("-" * 50)
    print("  MCP 定义「协议」------ 如何连接和通信")
    print("  AgentSkill 定义「能力」------ 具体做什么")
    print("  关系：AgentSkill 通过 MCP 协议暴露给 LLM")
    print("  类比：MCP = USB-C标准，AgentSkill = USB设备")

    print("\n▶ 12.3 Harness 亮点")
    print("-" * 50)
    h_features = [
        "CLI + SDK 双模式",
        "支持任意 LLM（Claude/GPT/Gemini/Ollama）",
        "/plan /review /team /status /cost 命令",
        "Bypass 模式（CI/CD 友好）",
    ]
    for f in h_features:
        print(f"  • {f}")

    print("\n▶ 12.5 Agent 生产化 Checklist")
    print("-" * 50)
    AgentProductionChecklist.print_checklist()

    print("\n▶ 12.6 全课程回顾")
    print("-" * 50)
    chapters = [
        "Ch0   → 课程概览",
        "Ch1-3 → Agent 基础理论（循环/组件/类型）",
        "Ch4-5 → 工程实践（框架/Multi-Agent）",
        "Ch6-7 → 评估与求职（评测/面试）",
        "Ch8   → Claude Code 架构深度剖析",
        "Ch9   → RAG 技术全览（Naive→Agentic RAG）",
        "Ch10  → MCP 协议详解",
        "Ch11  → Tool Calling 底层机制",
        "Ch12  → 生产基础设施（OpenClaw/Harness/评测）",
    ]
    for ch in chapters:
        print(f"  {ch}")

    print("\n" + "=" * 60)
    print("  🎓 全课程体系完成！")
    print("  从 Agent 基础到 Claude Code 逆向分析")
    print("  从 RAG 到 MCP 到 Tool Calling 底层原理")
    print("  你现在已经具备了成为顶级 Agent 工程师的所有知识")
    print("=" * 60)