AI Agent开发框架-OpenClaw

前言

在传统智能体开发中，开发者需要关注

接入例如微信、飞书、钉钉、Web、移动端等多渠道如何统一对接
消息如何路由、协议如何适配
Agent的执行逻辑

而OpenClaw的颠覆在于

接入层解耦（无头架构）：任意前端（微信、飞书、Slack 等）只作为输入输出管道，AI Agent不再绑定任何界面，实现多渠道接入。

网关集中调度：Gateway作为唯一控制中心，统一处理协议转换、任务分发和状态管理，让多模态消息与多后端实例有序协同。

执行层无状态弹性：Claw Pods跑在K8s上，完全无状态，可按业务负载无限创建，实现真正的弹性扩容与高可用部署。

智能体开发者只需专注于Skill开发，和Token消耗。

使用openclaw开发智能体

有了OpenClaw AI Agent开发框架之后，智能体开发变得简单很多，写python脚本+markdown文件+修改配置就行+启动网关即可。

智能体灵魂配置文件

SKILL.md是Skill的灵魂，而SOULL.md预设Agent的灵魂。

可以预设Agent的人格、人设、行为规则、系统提示词。

/root/.openclaw/workspace

#你是智能运维组手-小根
##必须严格遵守以下规则：
1. 用户请求如果匹配已有Skill能力，禁止闲聊。

SOUL.md

OpenClaw网关

/root/.openclaw

{
  "gateway": {
    "bind": "lan",
    "port": 18789,
    "mode": "local",
    "controlUi": {
      "enabled": true,
      "allowInsecureAuth": true,
      "allowedOrigins": [
        "*"
      ],
      "dangerouslyAllowHostHeaderOriginFallback": true,
      "dangerouslyDisableDeviceAuth": true
    },
    "auth": {
      "mode": "token",
      "token": "00aa281f2b12a273ccdd22a8e33a5c4121bb61774582542b"
    }
  },
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai-proxy.org/v1",
        "auth": "api-key",
        "apiKey": "",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4.1",
            "name": "gpt-4.1",
            "reasoning": false
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-4.1"
      }
    },
    "list": [
      {
        "id": "zhanggen",
        "default": true
      }
    ]
  },
  "plugins": {
    "entries": {
      "openai": {
        "enabled": true
      }
    }
  },
  "meta": {
    "lastTouchedVersion": "2026.4.9",
    "lastTouchedAt": "2026-04-29T12:18:22.607Z"
  },
  "skills": {
    "entries": {
      "tmux": {
        "enabled": false
      },
      "node-connect": {
        "enabled": false
      },
      "1password": {
        "enabled": false
      },
      "bear-notes": {
        "enabled": false
      },
      "apple-notes": {
        "enabled": false
      },
      "apple-reminders": {
        "enabled": false
      },
      "bluebubbles": {
        "enabled": false
      },
      "coding-agent": {
        "enabled": false
      },
      "blucli": {
        "enabled": false
      },
      "skill-creator": {
        "enabled": false
      },
      "weather": {
        "enabled": false
      },
      "healthcheck": {
        "enabled": false
      },
      "blogwatcher": {
        "enabled": false
      },
      "camsnap": {
        "enabled": false
      },
      "discord": {
        "enabled": false
      },
      "gh-issues": {
        "enabled": false
      },
      "gifgrep": {
        "enabled": false
      },
      "eightctl": {
        "enabled": false
      },
      "summarize": {
        "enabled": false
      },
      "himalaya": {
        "enabled": false
      }
    }
  }
}

openclaw.json

OpenClaw Skill

之前Agent直接调用零散的工具，Agent需要关注

执行逻辑
用哪个工具
参数怎么拼
顺序怎么排
错误怎么处理

容易导致LLM对工具调用识别不准确，导致智能体系统不稳定、不可控。

Skill模式：业务化、可直接调用的复合能力（原子能力的组合 + 流程）

Skill 把执行逻辑 + 工具链 + 错误处理全部封装成一个可直接调用的业务能力。

Agent只需调用Skill，无需关注底层实现，让LLM 更稳定、更可控。

Skill（一个能力）
├── 元数据：trigger、prompt、说明（对外：我能干啥）
├── 执行逻辑（主流程）
│   ├── 参数校验
│   ├── 分支判断/循环
│   ├── 结果组装/格式化
│   └── 错误处理
└── 内部调用：多个 Tool
    ├── Tool1：HTTP API（如天气接口）
    ├── Tool2：Shell 命令（如 curl/python）
    ├── Tool3：数据库/缓存
    └── Tool4：其他 SDK/服务

SKILL.md是当前skill的灵魂，本质是输入给LLM的结构化提示词，定义当前skill执行逻辑。

/root/.openclaw/skills/ops/

---
name: SRE工程师帮助用户排查故障
description:该技能用于故障定位，全部使用scripts/python脚本完成。
version: 1.0.0
triggers:
  - "查询Pod信息"
---

# SRE角色
你是1个SRE工程师，收到问题需求，按以下流程完成任务，禁止使用kubectl

## 1.执行以下脚本返回脚本执行结果给用户

### 1.1.参数说明
 --username:从用户输入中提前当前会话用户
 --level :引导用户输入故障等级

## 1.2.带参执行脚本执行示例
```bash
   python3 /root/.openclaw/skills/ops/scripts/get_pods.py --username zhangsan --level 1
```

##1.3.参数收集完毕带参真正执行脚本
```bash
python3 /root/.openclaw/skills/ops/scripts/get_pods.py --username <故障发起人即当前用户>  --level <故障等级>
```

SKILL.md

/root/.openclaw/skills/ops/scripts/

import argparse
import sys


def get_pods(user_input):
    # 接收参数
    parser = argparse.ArgumentParser()
    parser.add_argument("--username", required=True, help="故障发起人")
    parser.add_argument("--level", required=True, help="故障等级")

    # 解析参数
    args = parser.parse_args()
    username = args.username
    level = args.level

    pods = ["pod1", "pod2", "pod3", "pod4"]
    with open(file="/pod.txt", mode="w", encoding="utf-8") as f:
        f.write("\n".join(pods))
        f.write(f"故障提出人{username}故障等级{level}\n")

    data = {
        "username": username,
        "level": level,
        "pods": pods,
    }
    return data


if __name__ == "__main__":
    if len(sys.argv) > 1:
        user_input = sys.argv[1]
    else:
        user_input = None
    pod_list = get_pods(user_input)

get_pods.py

重启OpenClaw网关

OpenClaw原生网关主要用WebSocket协议做通信；

插件的职责是把各平台的协议和消息格式，转换成网关统一的内部消息模型

openclaw gateway --allow-unconfigured

control-ui与网关建立新对话

使用openClaw内置的openclaw-control-ui与openClaw内置网关建立websocket连接。

1.采集用户需求和脚本执行参数

2.收集完整参数信息执行skill

查看本次对话skill执行的工具以及工具执行结果

插件钩子

插件钩子是OpenClaw插件的进程内扩展点。

当插件需要检查或更改智能体运行、工具调用、消息流、会话生命周期、子智能体路由、安装或Gateway网关启动时，使用插件钩子。

如果想在/new、/reset、/stop、agent:bootstrap或gateway:startup等命令和Gateway网关内部事件发生时，执行小型脚本，请改用内部钩子。

插件钩子也可以在工具调用前后、会话启停等节点拦截事件、读写请求参数、注入会话信息（sessionId）、动态修改系统/用户提示词。

实现权限校验、操作审计、参数预处理、提示词定制、跨语言集成（Python/Go）等功能扩展，让框架高度灵活可定制。

开发1个插件钩子功能如下：在skill被LLM选中后，当前skill中定义的python脚本执行前，通过before_tool_call钩子自动注入1个执行上下文参数。

有了sessionId参数，Python脚本就可以识别当前会话信息。

/root/.openclaw/extensions/my-before-tool-plugin/

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-before-tool-plugin",
  name: "My Before Tool Plugin",

  register(api) {
    api.on("before_tool_call", async (event,ctx) => {
      if (event.toolName === "exec") {
          const extendedCtx = { ...event, ...ctx };
          const originCommand = event.params.command;
          const ctxJson = JSON.stringify(extendedCtx);
          event.params.command = `${originCommand} --ctx '${ctxJson}'`;
          console.log("[插件] 新命令 =", event.params.command);
      }
      return { params: event.params };
    });
  },
});

index.ts

/root/.openclaw/extensions/my-before-tool-plugin/

{
"id": "my-before-tool-plugin",
"configSchema": {
  "type": "object",
  "additionalProperties": false
}
}

openclaw.plugin.json

/root/.openclaw/extensions/my-before-tool-plugin/

{
  "name": "my-before-tool-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"]
  }
}

package.json

/root/.openclaw/skills/ops/scripts/

import argparse
import sys
import json
def get_pods(user_input):
    # 接收参数
    parser = argparse.ArgumentParser()
    parser.add_argument('--ctx', required=True, help='openclaw插件自动注入执行上下文')


    # 解析参数
    args = parser.parse_args()
    ctx = json.loads(args.ctx)
    
    pods = ['pod1', 'pod2', 'pod3', 'pod4']
    data = {
        'context': ctx,
        'pods': pods,
    }
    return data


if __name__ == '__main__':
    if len(sys.argv) > 1:
        user_input = sys.argv[1]
    else:
        user_input = None
    pod_data = get_pods(user_input)
    print(pod_data)

get_pods.py

脚本执行后输出

{'context': {'toolName': 'exec', 'params': {'command': 'python3 /root/.openclaw/skills/ops/scripts/get_pods.py'}, 'runId': '37e07dc0-85a7-44b2-b3d9-c26f62c19e88', 'toolCallId': 'call_aPB7DTMiQDvfcAOxIdCCxqOw', 'agentId': 'zhanggen', 'sessionKey': 'agent:zhanggen:main', 'sessionId': '92beeb8b-3bcb-42ad-b2e0-177962a7e71c'}, 'pods': ['pod1', 'pod2', 'pod3', 'pod4']}

output

OpenClaw

OpenClaw原生架构

ClawPod是运行于操作系统之上的AI任务执行运行时（Runtime），其实例的创建、销毁及全生命周期由外部Gateway统一调度管理。

OpenClaw网关负责接收外部Gateway下发的任务并完成内部调度与执行，通过调用Python Skill实现智能体的具体业务逻辑。

Claw运行时通常以ClawPod形式部署于Kubernetes集群中，组成ClawPod集群，也就是周鸿祎在抖音上常说的龙虾集群。

ClawPod核心职责：

启动后主动连接网关实现注册发现

接收上层Gateway转发的自然语言输入

负责任务调度、并发控制、生命周期管理；

作为执行引擎，统一调度并调用由Python开发的 Skills 插件；

4完成智能体业务逻辑执行，并返回结果。

该运行时通常以ClawPod的形式部署在Kubernetes中。

结合之前学的云原生知识，参考OpenClaw网关的架构设计和工作流程，实现企业级AI Agent落地

OpenClaw架构

OpenClaw的Gateway和微服务中网关有很大不同。

OpenClaw Gateway 是三位一体网关：IM 协议网关 + AI 模型调度网关 + ClawPod 生命周期与任务管控网关。

而传统微服务网关只做认证+鉴权+流量转发，不涉AI、不控Pod、不管IM长连接。

Gateway

统一接入50+种类型IM通信协议（微信 / 飞书 / 钉钉 / 企微 / QQ 等），同时承担ClawPod的调度、管理与生命周期控制，并负责任务分配与执行编排

Gateway：监听 WS（被动）关系连接和消息关系

ClawPod：主动连接（客户端）注册发现

任务下发：网关通过WS推送任务到ClawPod

执行结果：ClawPod通过和网关建立的唯一WS回传

AgentCore

调用 LLM、解析意图、分发任务、状态管理、异步处理

Claw Pod

弹性技能执行层，执行 Skill 或任务

MCP Server

（可选）统一管理 Pod 内的任务接口、鉴权和异步执行

LLM

处理自然语言、生成意图、提供推理能力

OpenClaw Gateway

系统唯一入口，负责请求路由、鉴权、会话管理、结果聚合，是整个架构的控制平面。

负责实例管理 + 身份认证 + Pod 调度 + 双向通信转发

Pi Agent

Pi Agent内嵌在OpenClaw Gateway进程中，是1个极简嵌入式Agent引擎无额外Pod开销，适合本地单实例使用。

AgentCore

调用 LLM、解析意图、分发任务、状态管理、异步处理

Claw Pod (Worker)

企业级部署模式，需要独立Pod/进程，支持水平扩缩容，适合高并发、多租户场景。

外部LLM和工具服务

所有智能来自外部大模型，所有操作通过技能/Skill/MCP 服务执行，OpenClaw本身不内置模型。

外部 LLM / 工具服务：OpenClaw无需内置LLM与工具能力

所有智能决策依赖外部LLM
所有业务操作通过Skill 执行：Skill统一经由内置MCP-Client 与外部 MCP-Server通信
MCP-Server 封装并提供外部系统

结果流转：两种执行模式的结果统一回传给 Gateway，由网关聚合后返回给用户

用户请求
   │
   ▼
+───────────────────────────────────────────────────+
│  OpenClaw Gateway                                  │
│  <-- 管理逻辑、会话生命周期、API Key                │
│  - 保存 OpenClaw Instance                          │
+───────────────────────────────────────────────────+
   │
   ├──────────────────┐
   │                  │
   ▼                  ▼
+───────────────────+  +───────────────────────────────────+
│ Claw Pod (Worker)  │  │ pi AgentSession                  │
│ - 独立 Pod         │  │ - 嵌入 Gateway 进程              │
│ - 调用外部 LLM     │  │ - 调用外部 LLM                    │
│ - 执行技能         │  │ - 管理会话上下文                  │
│ - 并行/重试/状态   │  │ - 工具注入/分支会话               │
+───────────────────+  +───────────────────────────────────+
   │                       │
   ▼                       ▼
外部 LLM / 工具服务      外部 LLM / 工具服务
   │                       │
   ▼                       ▼
结果返回 → OpenClaw Gateway → 用户

OpenClaw网关工作流程

OpenClaw网关本质是一个基于WebSocket协议的Agent生命周期管理系统，和传统的微服务网关有本质差别。

通过K8s动态调度CrawPod，并用user_id + instance_id + api_key建立安全客户端和Agenr之间双向通信通道。

概念	所属层级	本质是什么	是否稳定	是否唯一	生命周期	作用
user_id	用户层 / 身份层	标识区分1个用户身份	是	是	长期	区分用户、隔离数据、权限归属
api_key	接入层/安全层	网关访问凭证（类似 Token）	✅ 稳定	✅ 唯一	长期 / 实例级	鉴权、标识调用方
instance_id	业务层	标识任务/会话	✅ 稳定	✅ 全局唯一	任务级	标识一次 Agent 执行
Node	逻辑层	一个运行中的 Agent 实例	✅ 稳定	✅ 一一对应 instance_id	任务级	承载执行逻辑
ClawPod	运行层	K8s Pod（执行容器）	❌ 会变	❌ 不唯一	容器级	实际执行任务

🚀一、实例创建（Instance Creation）

用户发起请求：

POST /openclaw/instance/create

网关执行：

生成唯一实例标识
- instance_id
- api_key
持久化数据库（关键步骤）

user_id: u_123
instance_id: inst_666
api_key_hash: xxx
status: creating

👉 注意：

api_key 只返回一次，数据库只存 hash
状态进入：creating

☸️ 二、Pod 创建（Kubernetes 调度）

网关调用 Kubernetes API 创建 Claw Pod：

env:
  - name: USER_ID
    value: "u_123"
  - name: INSTANCE_ID
    value: "inst_666"
  - name: API_KEY
    value: "api_888"
  - name: GATEWAY_WS_URL
    value: "ws://gateway/plugin/ws"

👉 本质：
网关把身份凭证 + 连接地址通过环境变量的方式，注入给CrawPod（Agent插件）

状态推进：

creating → pod_pending → pod_running

🔌 三、插件回连（WebSocket 建连）

Pod 启动后，插件自动执行：

读取环境变量中网关注入的api_key
连接服务端也就是网关WebSocket
发送鉴权信息

{
  "instance_id": "inst_666",
  "api_key": "api_888"
}

网关处理：

校验 instance_id + api_key_hash
建立连接池映射：

connections[instance_id] = websocket_conn

状态推进：

pod_running → connecting → ready

💓 四、心跳与连接管理（Connection Lifecycle）

为保证稳定性，必须实现：

1️⃣ 心跳机制

{ "type": "ping" }

网关：

记录 last_seen
超时剔除连接

2️⃣ 自动重连

插件侧需支持：

断线 → 自动重试（指数退避）

3️⃣ 状态更新

ready → offline / error

🔄 五、消息转发/推送（核心能力）

建立客户端和CrawPod的双向连接后：

前端 → 网关 → Claw Pod
Claw Pod → 网关 → 前端

前端连接：

ws://gateway/chat/ws?user_id=u_123&instance_id=inst_666

👉 网关职责：

根据 instance_id 路由消息
维护双向通信通道

⚠️ 六、异常处理与状态机（关键设计）

完整状态机：

creating
→ pod_pending
→ pod_running
→ connecting
→ ready
→ offline / error
→ deleted

👉 关键点：

Pod 启动失败要进入 error
长时间未连接要判定异常
所有阶段都要可恢复

🧹 七、实例销毁（资源回收）

DELETE /openclaw/instance

网关执行：

删除 Pod
断开 WebSocket
更新 DB 状态：deleted

openClaw skills执行流程

1个AI Agent核心架构必需以下3大组件

skills：Skill是Agent可调用的各类程序开发工具与执行能力。

Agent-runtime：加载本地skills的名称+接收用户提示词输入+对话上下文信息，输入给LLM，并根据LLM响应的推理结果调用不同skill。

LLM：LLM收到Agent-runtime输入的消息进行推理输出结果原路返回给Agent-runtime

OpenClaw的skill执行流程

OpenClaw是一款AI Agent开发框架，开发者只需专注于业务技能开发，无需关注底层通信与网关调度。

1. OpenClaw-runtime启动时扫描/skills目录

2. 解析每1个skills的SKILL.md，转成结构化能力描述

3. 构建skill registry（内存里的技能索引）

4. 用户请求进入runtime（带 session_id）

5. 读取会话上下文（历史对话 / 状态 / memory）

6. 构造 LLM Prompt

= 用户输入
+ 历史上下文
+ 所有skill 的描述（压缩/筛选后）

7. LLM 输出：

- 要调用的 skill

- 或直接回复（不调用 skill）

8. runtime 判断：

- 如果是 skill → 执行 index.js

- 如果是文本 → 直接返回

9. 执行 skill（可能多轮调用）

10. 返回结果给用户

OpenClaw官网

posted on 2026-04-09 17:23 运维体系建设之路阅读(289) 评论(0) 收藏举报

刷新页面返回顶部

AI Agent开发框架-OpenClaw

前言

使用openclaw开发智能体

智能体灵魂配置文件

OpenClaw网关

OpenClaw Skill

重启OpenClaw网关

control-ui与网关建立新对话

查看本次对话skill执行的工具以及工具执行结果

插件钩子

OpenClaw

OpenClaw架构

OpenClaw Gateway

Pi Agent

AgentCore

Claw Pod (Worker)

外部LLM和工具服务

OpenClaw网关工作流程

🚀一、实例创建（Instance Creation）

☸️ 二、Pod 创建（Kubernetes 调度）

🔌 三、插件回连（WebSocket 建连）

💓 四、心跳与连接管理（Connection Lifecycle）

1️⃣ 心跳机制

2️⃣ 自动重连

3️⃣ 状态更新

🔄 五、消息转发/推送（核心能力）

⚠️ 六、异常处理与状态机（关键设计）

🧹 七、实例销毁（资源回收）

openClaw skills执行流程

OpenClaw的skill执行流程

公告