小学子讲技术 - OpenClaw 嵌入式Agent运行机制
深入理解 OpenClaw 嵌入式 Agent 运行机制
小学子讲技术，带你探索 AI Agent 的内部世界
一、什么是嵌入式 Agent？
大家好，我是小学子！今天要和大家聊一个很有意思的话题——OpenClaw 嵌入式 Agent。
在说嵌入式 Agent 之前，我们先来想想一个问题：当你和 AI 对话时，这个"对话"到底是怎么实现的？
传统的 AI 对话系统就像是一个问答机器：你问一句，它答一句，聊完就结束，没有任何"记忆"。但 OpenClaw 想要做的，是一个真正的 AI 助手——它不仅能对话，还能帮你完成各种任务，比如操作浏览器、读写文件、执行命令、管理日程等等。
而 嵌入式 Agent（Embedded Agent），就是 OpenClaw 用来实现这个目标的核心机制。
架构概览
┌─────────────────────────────────────────────────────────────────┐
│ OpenClaw Gateway │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Embedded Agent │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │
│ │ │ AgentSession│ │ Workspace │ │ Tool System │ │ │
│ │ │ Manager │ │ (文件) │ │ (七层管道) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ LLM API │ │ Tools │ │ Events │ │
│ │ Provider │ │ Executor │ │ Handler │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────┘简单来说，嵌入式 Agent 就是一个运行在 OpenClaw Gateway 内部的 AI 代理。它有自己的：
-
会话管理器（AgentSession）：管理和 LLM 的对话
-
工作空间（Workspace）：包含配置文件和上下文
-
工具系统：可以执行各种实际操作
二、核心架构：AgentSession
AgentSession 是 OpenClaw 嵌入式 Agent 的心脏。它负责创建和管理与 LLM 的对话会话。
创建 AgentSession
你可以通过 createAgentSession() 方法来创建一个新的 Agent 会话：
const session = await createAgentSession({
// 会话唯一标识
sessionKey: "my-agent-session",
// Agent 配置
agent: {
id: "assistant",
description: "我的 AI 助手",
},
// 工作空间目录
workspace: "./workspace",
// 系统提示词
systemPrompt: "你是一个乐于助人的 AI 助手。",
// LLM 配置
model: "claude-sonnet-4-20250514",
thinking: { type: "low" },
// 回调函数
onBlockReply: (block) => {
// 处理流式输出
},
onToolCall: (toolCall) => {
// 处理工具调用
},
});核心参数详解
|
参数 |
说明 |
示例 |
|
|
会话唯一标识符 |
|
|
|
Agent 配置对象 |
|
|
|
工作空间路径 |
|
|
|
系统提示词 |
自定义指令 |
|
|
使用的 LLM 模型 |
|
|
|
思考级别配置 |
|
|
|
沙箱模式配置 |
|
会话流程
User Message → AgentSession → LLM Provider
│
┌─────────────┴─────────────┐
▼ ▼
Text Response Tool Calls
│ │
▼ ▼
Display to User Execute Tools
│
▼
Tool Results
│
▼
→ LLM Provider (继续对话)三、实战：如何创建 OpenClaw Agent
方式一：对话式创建（推荐新手）
使用 OpenClaw CLI 可以快速创建一个 Agent：
# 交互式创建 Agent
openclaw agents create
# 或者一步到位
openclaw agents create --id my-agent --description "我的代码助手" --profile coding这会引导你完成配置过程，自动生成必要的文件。
方式二：手动配置文件
更高级的用法是直接编辑 openclaw.json：
{
// 全局工具配置
tools: {
// 工具配置文件：coding | messaging | minimal | full
profile: "coding",
// 允许的工具列表
allow: ["browser", "canvas"],
// 禁止的工具列表（优先于 allow）
deny: ["exec"],
// 循环检测配置
loopDetection: {
enabled: true,
warningThreshold: 10,
criticalThreshold: 20,
},
// Web 工具配置
web: {
search: { enabled: true },
fetch: { enabled: true, maxCharsCap: 50000 },
},
// 浏览器配置
browser: { enabled: true },
},
// Agent 列表
agents: {
list: [
{
id: "coder",
description: "专业的代码助手",
// Agent 专属工具配置
tools: {
profile: "coding",
allow: ["group:fs", "group:runtime", "group:memory"],
deny: ["process"],
},
// 心跳配置
heartbeat: {
enabled: true,
prompt: "检查是否有新任务...",
intervalMs: 30000,
},
// 子 Agent 配置
subagents: {
allowAgents: ["*"],
runTimeoutSeconds: 600,
},
},
],
defaults: {
// 默认模型
model: "claude-sonnet-4-20250514",
// 默认工作空间
workspace: "./workspace",
// 沙箱模式
sandbox: {
mode: "enabled",
},
},
},
}四、Workspace 引导文件系统
每个 OpenClaw Agent 都有一个工作空间（Workspace），这是它的"大脑"和"记忆"。下面是工作空间的目录结构：
workspace/
├── .openclaw/ # OpenClaw 系统目录（自动生成）
│ ├── agents/ # Agent 配置
│ │ └── <agentId>/
│ │ ├── sessions/ # 会话历史
│ │ │ └── <sessionId>.jsonl
│ │ └── state.json # Agent 状态
│ └── attachments/ # 文件附件
├── SOUL.md # 🌟 Agent 灵魂定义
├── USER.md # 用户信息
├── AGENTS.md # 工作规范
├── TOOLS.md # 工具配置
└── MEMORY.md # 长期记忆关键文件详解
1. SOUL.md — Agent 的灵魂
这是最重要的文件，定义了 Agent 的人格和价值观：
# SOUL.md - Who You Are
**核心信念：**
- 永远说真话
- 不做假设，先求证
- 尊重用户隐私
**沟通风格：**
- 简洁明了，不说废话
- 适当使用 emoji 增添活力
- 遇到问题敢于说"我不懂"2. USER.md — 用户画像
记录用户的相关信息，让 Agent 更好地理解和服务用户：
# USER.md - About Your Human
- **Name:** 张三
- **Timezone:** Asia/Shanghai
- **Preferences:**
- 喜欢简洁的技术文档
- 常用 VS Code + Python3. AGENTS.md — 工作规范
定义 Agent 的工作流程和行为准则：
# AGENTS.md - Your Workspace
## 每次会话开始时
1. 读取 SOUL.md — 理解自己是谁
2. 读取 USER.md — 了解服务对象
3. 读取 memory/YYYY-MM-DD.md — 回顾最近发生了什么
## 行为准则
- 不要，未经允许不要执行任何外部操作
- 重要决策要主动询问用户
- 定期保存会话到 memory/4. TOOLS.md — 工具配置
记录工具的具体配置和本地参数：
# TOOLS.md - Local Notes
## 摄像头
- living-room → 客厅，180° 广角
- front-door → 门口，移动侦测
## SSH 配置
- home-server → 192.168.1.100, user: admin
## TTS 语音
- 推荐音色：Nova（温暖、英式）五、工具系统架构（七层管道 + 适配器模式）
OpenClaw 的工具系统是一个非常精妙的设计。让我来为你拆解！
七层管道架构
User/Agent
│
▼
┌────────────────────────────────────────┐
│ Layer 1: Tool Definition │ ← 工具定义（名称、参数）
│ (名称、描述、参数 Schema) │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ Layer 2: Tool Adapter │ ← 适配器转换
│ (pi-tool-definition-adapter) │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ Layer 3: Provider Normalization │ ← provider 适配
│ (Google/OpenAI/Anthropic 特殊处理) │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ Layer 4: Policy Enforcement │ ← 策略执行
│ (allow/deny/profiles) │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ Layer 5: Execution Sandbox │ ← 沙箱执行
│ (安全隔离) │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ Layer 6: Tool Executor │ ← 实际执行
│ (read/write/exec/browser...) │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ Layer 7: Result Normalization │ ← 结果标准化
│ (统一返回格式) │
└────────────────────────────────────────┘工具分类与工具组
OpenClaw 提供了丰富的内置工具，按功能分组：
|
工具组 |
包含工具 |
说明 |
|
|
read, write, edit, apply_patch |
文件系统操作 |
|
|
exec, bash, process |
命令执行 |
|
|
sessions_list, sessions_history, sessions_send, sessions_spawn |
会话管理 |
|
|
memory_search, memory_get |
记忆系统 |
|
|
web_search, web_fetch |
网络工具 |
|
|
browser, canvas |
UI 自动化 |
|
|
message |
消息发送 |
工具配置示例
{
tools: {
// 基础配置：只允许文件操作 + 浏览器
allow: ["group:fs", "browser"],
// 禁止执行危险命令
deny: ["exec"],
// 针对特定 provider 的限制
byProvider: {
"google-antigravity": {
profile: "minimal" // Google 模型只用最小工具集
}
}
}
}六、运行流程和事件处理
完整运行流程
// 1. 初始化 AgentSession
const session = await createAgentSession({
sessionKey: "my-session",
agent: { id: "assistant" },
});
// 2. 发送消息
await session.send({
message: "帮我查一下今天的天气",
});
// 3. 事件回调处理
session.onBlockReply((block) => {
if (block.type === "text") {
console.log("AI 回复:", block.text);
}
});
session.onToolCall(async (toolCall) => {
console.log("工具调用:", toolCall.name, toolCall.params);
// 执行工具并返回结果
const result = await executeTool(toolCall);
return result;
});事件类型
|
事件 |
触发时机 |
用途 |
|
|
流式输出时 |
处理 AI 的文本回复 |
|
|
调用工具时 |
处理工具执行请求 |
|
|
会话结束时 |
清理和保存状态 |
|
|
发生错误时 |
错误处理和恢复 |
七、错误处理和沙箱模式
错误分类
OpenClaw 内置了完善的错误处理机制：
// 错误识别函数
isContextOverflowError(errorText) // 上下文溢出
isCompactionFailureError(errorText) // 压缩失败
isAuthAssistantError(lastAssistant) // 认证失败
isRateLimitAssistantError(...) // 速率限制
isFailoverAssistantError(...) // 需要故障转移
// 错误分类
classifyFailoverReason(errorText)
// 返回: "auth" | "rate_limit" | "quota" | "timeout" | ...思考级别回退
如果当前模型不支持指定的思考级别，会自动回退：
const fallbackThinking = pickFallbackThinkingLevel({
message: errorText,
attempted: attemptedThinking,
});
if (fallbackThinking) {
thinkLevel = fallbackThinking; // 降级到支持的级别
continue; // 重试请求
}沙箱模式
OpenClaw 支持沙箱模式（Sandbox Mode），提供安全隔离的执行环境：
const session = await createAgentSession({
sessionKey: "sandboxed-session",
sandbox: {
mode: "enabled",
// 限制可用的工具
tools: {
allow: ["read", "write", "group:fs"],
deny: ["exec", "process"],
},
// 限制文件访问
paths: {
allowed: [".workspace/**"],
denied: [".workspace/secrets/**"],
},
},
});沙箱模式下：
-
文件访问：只能访问工作空间内的文件
-
工具执行：只能使用白名单中的工具
-
网络请求：通过安全代理进行
-
命令执行：在隔离容器中运行
八、会话管理和持久化
会话存储结构
~/.openclaw/agents/<agentId>/sessions/
├── session-2026-03-10-001.jsonl
├── session-2026-03-10-002.jsonl
└── ...每个会话存储为 JSONL 格式（JSON Lines），每行是一个消息：
{"role": "user", "content": "你好！", "timestamp": 1708400000000}
{"role": "assistant", "content": "你好！有什么可以帮你的？", "timestamp": 1708400001000}
{"role": "tool", "tool": "read", "result": "file content...", "timestamp": 1708400002000}会话管理工具
|
工具 |
功能 |
|
|
列出所有会话 |
|
|
查看会话历史 |
|
|
向指定会话发送消息 |
|
|
创建子 Agent 会话 |
会话配置
{
// 全局会话配置
sessions: {
// 可见性：self | tree | all
visibility: "tree",
// 消息保留天数
retentionDays: 30,
// 每次获取的最大消息数
messageLimit: 50,
}
}九、总结
今天我们深入探讨了 OpenClaw 嵌入式 Agent 的运行机制。让我来回顾一下重点：
核心要点
-
嵌入式 Agent = 会话管理 + 工作空间 + 工具系统
-
AgentSession 负责 LLM 对话
-
Workspace 存储配置和记忆
-
工具系统执行实际操作
-
-
七层管道架构
-
从工具定义到结果标准化
-
每层都有特定的职责
-
适配器模式处理 provider 差异
-
-
Workspace 文件系统
-
SOUL.md：Agent 的人格定义
-
USER.md：用户信息
-
AGENTS.md：工作规范
-
TOOLS.md：工具配置
-
MEMORY.md：长期记忆
-
-
安全机制
-
工具 allow/deny 策略
-
沙箱模式隔离执行
-
错误分类和自动恢复
-
-
会话持久化
-
JSONL 格式存储
-
支持会话历史查看
-
子 Agent 会话管理
-
好了，今天的分享就到这里！我是小学子，带你探索 AI 技术的方方面面。
如果你对 OpenClaw 感兴趣，不妨自己动手试试创建一个嵌入式 Agent，体验一下它的强大功能！
下期预告：我们将深入探讨 OpenClaw 的工具系统，看看它是如何实现浏览器自动化、文件操作等强大功能的。
敬请期待！🚀
参考来源
-
版本信息截至 2026 年 3 月
「AI团队养成记」系列记录了我用AI Agent打造游戏开发团队的真实过程。目前已更新至第3篇，欢迎小红书搜索关注阅读完整图文版~
🔗 最新篇：AI团队养成记 · 三 · AI是怎么写代码的
智能硬件社区聚焦AI智能硬件技术生态，汇聚嵌入式AI、物联网硬件开发者，打造交流分享平台，同步全国赛事资讯、开展 OPC 核心人才招募，助力技术落地与开发者成长。
更多推荐
18
0- 0
已为社区贡献1条内容
所有评论(0)