从OpenClaw源码分析小龙虾是如何工作的?——概览与调试环境搭建

“

近期将连续发布《从OpenClaw源码分析小龙虾是如何工作的？》，本系列一共十篇文章。主题为：概览与调试环境搭建->Gateway源码分析->Session管理分析->提示词上下文分析->ReAct 原理与 pi-mono 源码分析->定时任务与心跳机制->记忆系统分析->Skill 体系分析->Channel 系统分析->自我进化机制。

第1篇：概览与调试环境搭建

一、OpenClaw 是什么？

OpenClaw 是一个 AI Agent 运行时框架，简单来说，它是一个私人 AI 助理。它位于 AI 模型与外部世界之间，将自然语言指令转换为真实的系统操作。

“

开源地址：https://github.com/openclaw/openclaw

用一句话概括：OpenClaw = Gateway + Agent Runtime + Skills + Memory + Channel

二、整体架构

三、核心目录结构

📦 根目录├── 📁 src                          # 核心运行时逻辑│   ├── 📁 cli                      # CLI 命令行界面相关代码│   ├── 📁 commands                 # 具体 CLI 命令实现│   ├── 📁 gateway                  # 处理 HTTP/WebSocket 请求│   ├── 📁 channels                 # 通用通道│   ├── 📁 routing                  # 消息路由逻辑│   ├── 📁 providers                # 模型提供器│   ├── 📁 media                    # 媒体处理管道│   ├── 📁 infra                    # 基础设施代码│   ├── 📁 agents                   # 智能体核心逻辑│   ├── 📁 plugins                  # 插件系统框架│   └── 📁 utils                    # 通用工具函数├── 📁 apps                         # 本地客户端实现├── 📁 extensions                   # 集成插件├── 📁 docs                         # 使用与开发文档├── 📁 scripts                      # 构建/发布脚本├── 📁 ui                           # 前端界面├── 📄 package.json                 # Node 依赖和脚本├── 📄 openclaw.mjs                 # 主入口运行 CLI├── 📄 tsconfig.json                # TypeScript 配置└── 📄 .env                         # 环境变量配置

四、核心配置文件说明

OpenClaw 使用一组 Markdown 文件来定义 Agent 的行为和身份：

文件	作用
AGENTS.md	操作指令、工作规范、犯过的错误、学到的教训
SOUL.md	人格、边界、语气 — 定义“我是谁”
IDENTITY.md	名字、形象、emoji 签名
USER.md	用户档案（主人信息、偏好、禁区等画像）
TOOLS.md	工具使用笔记（SSH 等本地配置）
HEARTBEAT.md	定期检查清单（heartbeat 时使用）
BOOTSTRAP.md	一次性首次运行引导

这些文件会在每次对话时被注入到系统提示词中，让 Agent 拥有持久化的身份和行为记忆。

五、调试环境搭建

步骤一：克隆源码

git clone https://github.com/openclaw/openclaw

步骤二：用 VSCode 导入项目

步骤三：配置 LLM API

在 openclaw.json 文件中配置 LLM API 密钥和端点。

步骤四：启动调试模式

点击 VSCode 的 “Run and Debug” 模式
打开 JavaScript Debug Terminal 命令窗
执行以下命令启动 Gateway 服务：

node --enable-source-maps scripts/run-node.mjs --dev gateway --port 18789 --allow_unconfigured --token 123456

步骤五：配置 Source Map（断点调试必备）

TypeScript 打断点需要先编译 sourcemap 文件，否则 TS 的行数对应不到编译后的 JS 上：

pnpm tsdown --sourcemap

步骤六：连接 Web 界面

浏览器打开 http://127.0.0.1:18789/，配置 Gateway 的访问 token（示例中为 123456），否则无法连接。

步骤七：开始对话

在浏览器打开的 Chat 窗口中开始与 Agent 对话。

下篇预告

下一篇我们将深入分析 Gateway（网关） 的源码，了解它是如何作为中央控制器协调所有组件之间的交互的。