夜雨聆风本文适合：刚接触 OpenClaw 的新手，想系统了解架构设计前置知识：Python 基础、命令行使用经验阅读时间：约 20 分钟
目录
1. 什么是 OpenClaw？ 2. 核心架构图解 3. 关键组件详解 4. 消息流转流程 5. 实战：第一个 Agent 交互 6. 常见问题 FAQ
1. 什么是 OpenClaw？
1.1 定义
OpenClaw 是一个开源的 AI Agent 运行时框架，让大模型能够：
• 📁 读写本地文件 • 🖥️ 执行系统命令 • 🌐 访问互联网 • 💬 连接多个通讯平台（微信、Telegram、飞书等） • 🧠 拥有长期记忆
本质：在大模型和你的电脑/手机之间架一座桥。
1.2 与同类工具对比
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 | codingfull / 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.md2. 执行命令前必须告知用户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 APIcurl "https://api.search.brave.com/..."工具返回：
{"results":[{"title":"北京天气预报","snippet":"晴，15-25°C..."}]}Agent 最终回复：
今天北京天气：晴，气温 15-25°C，适合户外活动。
5. 实战：第一个 Agent 交互
5.1 环境准备
# 1. 安装 OpenClawnpm install -g openclaw# 2. 启动 Gatewayopenclaw gateway start# 3. 检查状态openclaw gateway status5.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 wechat2. 扫码登录 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. 重置 Gatewayopenclaw gateway restartQ2: 工具调用被拒绝？
原因：
• 文件路径超出 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 pruneQ5: 如何备份记忆数据？
# 备份整个 workspacecp -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
