本文适合：刚接触 OpenClaw 的新手，想系统了解架构设计
前置知识：Python 基础、命令行使用经验

---

目录

1. 什么是 OpenClaw？
2. 核心架构图解
3. 关键组件详解
4. 消息流转流程
5. 实战：第一个 Agent 交互
6. 常见问题 FAQ

---

1. 什么是 OpenClaw？

1.1 定义

OpenClaw 是一个开源的 AI Agent 运行时框架，让大模型能够：

• 读写本地文件
• 执行系统命令
• 访问互联网
• 连接多个通讯平台（微信、Telegram、飞书等）
• 拥有长期记忆

本质：在大模型和你的电脑/手机之间架一座桥。

1.2 与同类工具对比

特性	OpenClaw	Claude Desktop	Dify
本地文件访问	✅ 完整	⚠️ 受限	❌
命令执行	✅ 可配置	❌	⚠️
多平台连接	✅ 10+	⚠️ 有限	❌
开源程度	✅ 完全开源	❌ 闭源	✅
自定义技能	✅ 简单	❌	⚠️

---

2. 核心架构图解

2.1 整体架构

┌─────────────────────────────────────────────────────────┐
│                    用户设备                              │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐           │
│  │  微信     │  │ Telegram  │  │  飞书     │  ...      │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘           │
│        │              │              │                   │
│        └──────────────┼──────────────┘                   │
│                       │                                   │
│              ┌────────▼────────┐                         │
│              │   Gateway       │ ← 消息路由中心          │
│              │  (127.0.0.1)    │                         │
│              └────────┬────────┘                         │
└───────────────────────┼─────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
┌───────▼───────┐ ┌─────▼─────┐ ┌──────▼──────┐
│   Session     │ │   Tools   │ │   Memory    │
│   (会话管理)   │ │  (工具集)  │ │  (记忆系统)  │
└───────┬───────┘ └─────┬─────┘ └─────────────┘
        │               │
        │      ┌────────▼────────┐
        │      │   Workspace     │
        │      │  (工作目录)      │
        │      └─────────────────┘
        │
┌───────▼───────────────────────────────┐
│          大模型 API                     │
│  ┌─────────┐  ┌─────────┐  ┌────────┐ │
│  │ Qwen    │  │ Claude  │  │ GPT    │ │
│  └─────────┘  └─────────┘  └────────┘ │
└───────────────────────────────────────┘

2.2 进程模型

openclaw gateway start
       │
       ▼
┌─────────────────────┐
│  Gateway 进程        │
│  - HTTP Server      │ 监听 127.0.0.1:18789
│  - Session Manager  │ 管理多个会话
│  - Tool Executor    │ 执行工具调用
│  - Memory Store     │ 存储记忆数据
└─────────────────────┘
       │
       ▼
┌─────────────────────┐
│  Agent 会话进程      │ ← 每个会话独立
│  - 模型对话         │
│  - 工具调用         │
│  - 状态维护         │
└─────────────────────┘

---

3. 关键组件详解

3.1 Gateway（网关）

职责：消息路由、会话管理、工具调度

配置文件：~/.openclaw/openclaw.json

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "workspace": "~/.openclaw/workspace"
  },
  "tools": {
    "profile": "coding",
    "fs": {
      "workspaceOnly": true
    },
    "denyCommands": [
      "shutdown", "taskkill", "format", "del"
    ]
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "mode": "allowlist",
      "allowlist": ["chat_xxxxx"]
    }
  }
}

关键配置说明：

配置项	含义	推荐值
tools.profile	工具权限级别	coding / full / minimal
fs.workspaceOnly	限制文件访问范围	true（安全）
denyCommands	禁止执行的命令	高危命令列表

3.2 Session（会话）

定义：一次完整的对话上下文，包含历史消息、状态、工具使用记录。

会话类型：

• main：主会话（直接对话）
• subagent：子代理（后台任务）
• isolated：隔离会话（独立上下文）

查看会话：

openclaw sessions list

会话数据结构：

{
  "sessionKey": "abc123",
  "channel": "webchat",
  "messages": [
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好！有什么可以帮你？"}
  ],
  "tools": {
    "used": ["read", "write", "exec"],
    "cost": 0.002
  }
}

3.3 Tools（工具集）

内置工具：

工具	功能	示例
read	读取文件	read(path="config.json")
write	写入文件	write(path="test.txt", content="hello")
edit	编辑文件	edit(path="main.py", oldText="x", newText="y")
exec	执行命令	exec(command="python test.py")
web_search	搜索网络	web_search(query="AI news")
web_fetch	抓取网页	web_fetch(url="https://example.com")
sessions_spawn	创建子代理	sessions_spawn(task="分析数据")

工具调用格式（Agent 内部）：

{
  "tool": "read",
  "parameters": {
    "path": "~/.openclaw/workspace/MEMORY.md"
  }
}

3.4 Memory（记忆系统）

三层记忆结构：

┌─────────────────────────────────────┐
│  短期记忆 (Session Context)          │
│  - 当前对话历史                      │
│  - 工具调用记录                      │
│  - 会话结束后清除                    │
└─────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│  中期记忆 (memory/YYYY-MM-DD.md)    │
│  - 每日日志                          │
│  - 临时笔记                          │
│  - 按日期自动归档                    │
└─────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│  长期记忆 (MEMORY.md)               │
│  - 重要决策                          │
│  - 用户偏好                          │
│  - 经验教训                          │
│  - 手动 curated                      │
└─────────────────────────────────────┘

记忆文件示例：

# MEMORY.md - 长期记忆

## 关于用户
- 名字：老大
- 时区：Asia/Shanghai
- 偏好：不喜欢废话，直接给结果

## 项目进度
-  股票指标工具开发完成
-  回测系统开发中
-  每日涨幅榜分析待实现

## 经验教训
1. 完成任务后立即更新 MEMORY.md
2. 执行命令前必须告知用户
3. 批量修改文件前先备份

---

4. 消息流转流程

4.1 用户消息 → Agent 回复

1. 用户发送消息
   │
   ▼
2. Channel 接收（微信/Telegram/飞书）
   │
   ▼
3. Gateway 路由到对应 Session
   │
   ▼
4. Session 将消息 + 历史上下文打包
   │
   ▼
5. 发送到大模型 API
   │
   ▼
6. 大模型返回回复 + 工具调用请求
   │
   ▼
7. Gateway 执行工具（读文件/运行命令等）
   │
   ▼
8. 工具执行结果返回给大模型
   │
   ▼
9. 大模型生成最终回复
   │
   ▼
10. Gateway 通过 Channel 发送给用户

4.2 工具调用示例

用户：帮我查一下今天的天气

Agent 思考：

{
  "thought": "用户想查天气，我需要用 web_search 工具搜索",
  "tool": "web_search",
  "parameters": {
    "query": "北京天气 2026-03-16"
  }
}

Gateway 执行：

# 内部调用 Brave Search API
curl "https://api.search.brave.com/..."

工具返回：

{
  "results": [
    {"title": "北京天气预报", "snippet": "晴，15-25°C..."}
  ]
}

Agent 最终回复：

今天北京天气：晴，气温 15-25°C，适合户外活动。

---

5. 实战：第一个 Agent 交互

5.1 环境准备

# 1. 安装 OpenClaw
npm install -g openclaw

# 2. 启动 Gateway
openclaw gateway start

# 3. 检查状态
openclaw gateway status

5.2 配置模型

编辑 ~/.openclaw/openclaw.json：

{
  "models": {
    "default": "qwen3.5-plus",
    "providers": {
      "bailian": {
        "apiKey": "sk-xxxxx",
        "models": ["qwen3.5-plus", "qwen3.5-turbo"]
      }
    }
  }
}

5.3 开始对话

Web 界面：访问 http://127.0.0.1:18789

命令行：

openclaw chat "你好，介绍一下你自己"

集成到微信：

1. 运行 openclaw channel wechat
2. 扫码登录
3. 在微信中直接对话

5.4 第一个任务：读取文件

用户：帮我看看 MEMORY.md 里记了什么

Agent 工具调用：

read(path="~/.openclaw/workspace/MEMORY.md")

执行流程：

1. Gateway 解析工具调用
2. 检查文件路径是否在 workspace 内（安全校验）
3. 读取文件内容
4. 返回给 Agent
5. Agent 总结后回复用户

---

6. 常见问题 FAQ

Q1: Gateway 启动失败怎么办？

检查步骤：

# 1. 查看端口是否被占用
netstat -ano | findstr :18789

# 2. 查看日志
openclaw gateway logs

# 3. 重置 Gateway
openclaw gateway restart

Q2: 工具调用被拒绝？

原因：

• 文件路径超出 workspace 范围
• 命令在 denyCommands 黑名单中
• tools.profile 权限不足

解决：

// openclaw.json
{
  "tools": {
    "profile": "coding",  // 改为 full（谨慎）
    "fs": {
      "workspaceOnly": false  // 允许访问 workspace 外（危险）
    }
  }
}

Q3: 如何添加自定义工具？

步骤：

1. 创建 Skill 目录：~/.openclaw/workspace/skills/my-skill/
2. 编写 SKILL.md 和工具脚本
3. 在 openclaw.json 中注册
4. 重启 Gateway

示例：

# SKILL.md
## 功能
发送飞书消息

## 工具
- feishu_send_message(to, content)

Q4: 会话太多怎么管理？

# 列出所有会话
openclaw sessions list

# 查看会话详情
openclaw sessions show <sessionKey>

# 删除旧会话
openclaw sessions delete <sessionKey>

# 清理所有过期会话
openclaw sessions prune

Q5: 如何备份记忆数据？

# 备份整个 workspace
cp -r ~/.openclaw/workspace ~/.openclaw/workspace.bak

# 只备份记忆文件
cp ~/.openclaw/workspace/MEMORY.md ~/backup/
cp -r ~/.openclaw/workspace/memory ~/backup/

---

总结

OpenClaw 的核心价值：

1. 开放：完全开源，可审计，可定制
2. 连接：打通大模型与本地资源
3. 安全：多层防护，权限可控
4. 扩展：Skill 系统，无限可能

---

作者：阿财 | 更新时间：2026-03-16