OpenClaw 目录结构详细介绍

- [🚀 快速概览](#🚀 快速概览)
- [📦 安装目录详解](#📦 安装目录详解)
- - 整体结构
  - 各目录详细说明
  - - [1. `openclaw.mjs` --- CLI 入口文件](#1. openclaw.mjs — CLI 入口文件)
    - [2. `package.json` --- npm 包配置](#2. package.json — npm 包配置)
    - [3. `dist/` --- 编译后的核心代码](#3. dist/ — 编译后的核心代码)
    - [4. `docs/` --- 官方文档](#4. docs/ — 官方文档)
    - [5. `skills/` --- AgentSkills 技能库](#5. skills/ — AgentSkills 技能库)
    - [6. `extensions/` --- 插件扩展](#6. extensions/ — 插件扩展)
    - [7. `node_modules/` --- npm 依赖包](#7. node_modules/ — npm 依赖包)
    - [8. `assets/` --- 静态资源](#8. assets/ — 静态资源)
    - [9. `README.md` & `CHANGELOG.md`](#9. README.md & CHANGELOG.md)
- [📁 数据目录详解](#📁 数据目录详解)
- - 整体结构
  - 各目录详细说明
  - - [1. `openclaw.json` --- 主配置文件](#1. openclaw.json — 主配置文件)
    - [2. `agents/` --- 多 Agent 工作区](#2. agents/ — 多 Agent 工作区)
    - [3. `workspace/` --- 工作区目录](#3. workspace/ — 工作区目录)
    - [4. `logs/` --- 网关日志](#4. logs/ — 网关日志)
    - [5. `devices/` --- 配对设备](#5. devices/ — 配对设备)
    - [6. `cron/` --- 定时任务](#6. cron/ — 定时任务)
- [🔬 核心文件深度解析](#🔬 核心文件深度解析)
- - [1. 会话存储原理](#1. 会话存储原理)
  - [2. 记忆系统原理](#2. 记忆系统原理)
  - [3. 插件系统原理](#3. 插件系统原理)
  - [4. Gateway 工作原理](#4. Gateway 工作原理)
- [🏗️ 目录结构原理](#🏗️ 目录结构原理)
- - 设计原则
  - 目录命名规范
- [📝 常用命令速查](#📝 常用命令速查)
- [📊 目录大小对比](#📊 目录大小对比)
- [🎯 总结](#🎯 总结)
- - [1. 清晰的职责分离](#1. 清晰的职责分离)
  - [2. 高度模块化](#2. 高度模块化)
  - [3. 文件化存储](#3. 文件化存储)
  - [4. 多 Agent 架构](#4. 多 Agent 架构)
  - [5. 完善的文档](#5. 完善的文档)
- [🔗 参考链接](#🔗 参考链接)

🚀 快速概览

OpenClaw 的目录分为两大类：

类型	路径	用途	是否可修改
安装目录	`/home/ubuntu/.npm-global/lib/node_modules/openclaw/`	程序代码、文档、技能、插件	❌ 不建议修改
数据目录	`/home/ubuntu/.openclaw/`	配置、会话、记忆、日志	✅ 用户数据

核心命令查看位置：

bash 复制代码

# 查看 CLI 安装位置
which openclaw
# 输出：/home/ubuntu/.npm-global/bin/openclaw

# 查看模块安装位置
npm list -g openclaw
# 输出：openclaw@2026.3.13

📦 安装目录详解

路径： /home/ubuntu/.npm-global/lib/node_modules/openclaw/

这是 OpenClaw 的程序本体，通过 npm 全局安装。

整体结构

复制代码

openclaw/
├── openclaw.mjs              # CLI 入口文件
├── package.json              # npm 包配置
├── LICENSE                   # 开源许可证
├── README.md                 # 项目说明 (124KB)
├── CHANGELOG.md              # 更新日志 (728KB)
│
├── dist/                     # 编译后的核心代码 (69MB)
├── docs/                     # 官方文档 (16MB)
├── skills/                   # AgentSkills 技能库 (728KB)
├── extensions/               # 插件扩展 (18MB)
├── node_modules/             # npm 依赖 (485MB)
└── assets/                   # 静态资源 (1.3MB)

各目录详细说明

1. `openclaw.mjs` --- CLI 入口文件

位置： /home/ubuntu/.npm-global/lib/node_modules/openclaw/openclaw.mjs

作用： OpenClaw 命令行工具的启动脚本

核心功能：

javascript 复制代码

#!/usr/bin/env node

// 1. 检查 Node.js 版本（要求 v22.12+）
const MIN_NODE_MAJOR = 22;
const MIN_NODE_MINOR = 12;

// 2. 启用模块编译缓存（性能优化）
module.enableCompileCache();

// 3. 安装进程警告过滤器
// 4. 加载主程序

工作原理：

验证 Node.js 版本是否符合要求
启用编译缓存加速后续启动
过滤掉不必要的警告信息
加载 dist/ 目录中的主程序

2. `package.json` --- npm 包配置

位置： /home/ubuntu/.npm-global/lib/node_modules/openclaw/package.json

大小： 24KB

核心内容：

json 复制代码

{
  "name": "openclaw",
  "version": "2026.3.13",
  "bin": {
    "openclaw": "./openclaw.mjs"
  },
  "dependencies": {
    "@anthropic-ai/sdk": "...",
    "ws": "...",
    "express": "...",
    // 362 个依赖包
  },
  "scripts": {
    "build": "...",
    "test": "..."
  }
}

作用：

定义包名、版本、入口文件
声明所有运行时依赖
定义构建和测试脚本
配置 npm 安装后的行为

3. `dist/` --- 编译后的核心代码

位置： /home/ubuntu/.npm-global/lib/node_modules/openclaw/dist/

大小： 69MB

目录内容：

复制代码

dist/
├── agent-*.js                # Agent 核心逻辑
├── gateway-*.js              # WebSocket 网关服务
├── channels-*.js             # 渠道集成（WhatsApp/Telegram 等）
├── tools-*.js                # 工具实现（浏览器/文件/搜索等）
├── cli-*.js                  # CLI 命令实现
├── memory-*.js               # 记忆系统
├── cron-*.js                 # 定时任务调度
├── models-*.js               # AI 模型管理
└── ... (数百个编译模块)

特点：

所有 TypeScript/源码编译后的 JavaScript
使用 Rollup/Vite 等工具打包
文件名带哈希值（如 agent-BeieZAG2.js）用于缓存失效
不要手动修改，重新编译会被覆盖

工作原理：

复制代码

源代码 (TypeScript) → 打包工具 → dist/*.js → Node.js 执行

4. `docs/` --- 官方文档

位置： /home/ubuntu/.npm-global/lib/node_modules/openclaw/docs/

大小： 16MB

目录结构：

复制代码

docs/
├── index.md                   # 文档首页
├── docs.json                  # 文档索引 (58KB)
├── style.css                  # 文档样式
│
├── cli/                       # CLI 命令参考 (30+ 文档)
│   ├── index.md              # CLI 总览
│   ├── gateway.md            # gateway 命令
│   ├── sessions.md           # sessions 命令
│   ├── memory.md             # memory 命令
│   ├── agents.md             # agents 命令
│   ├── cron.md               # cron 命令
│   ├── browser.md            # browser 命令
│   └── ...
│
├── concepts/                  # 核心概念
│   ├── memory.md             # 记忆系统
│   ├── models.md             # 模型配置
│   ├── oauth.md              # OAuth 认证
│   └── ...
│
├── gateway/                   # 网关文档
│   ├── configuration.md      # 配置参考
│   └── discovery.md          # 服务发现
│
├── tools/                     # 工具文档
│   ├── browser.md            # 浏览器工具
│   ├── plugin.md             # 插件系统
│   └── ...
│
├── channels/                  # 渠道集成文档
│   ├── whatsapp.md
│   ├── telegram.md
│   └── ...
│
├── automation/                # 自动化文档
│   ├── cron-jobs.md
│   └── gmail-pubsub.md
│
├── security/                  # 安全文档
├── providers/                 # AI 提供商文档
├── platforms/                 # 平台文档
├── nodes/                     # 节点文档
├── plugins/                   # 插件文档
│
├── zh-CN/                     # 中文文档
├── ja-JP/                     # 日文文档
└── assets/                    # 文档资源
    └── images/

访问方式：

bash 复制代码

# 本地搜索文档
openclaw docs <关键词>

# 在线文档
https://docs.openclaw.ai

5. `skills/` --- AgentSkills 技能库

位置： /home/ubuntu/.npm-global/lib/node_modules/openclaw/skills/

大小： 728KB

技能数量： 55+ 个内置技能

目录结构：

复制代码

skills/
├── weather/                   # 天气技能
│   ├── SKILL.md              # 技能描述（必须）
│   └── ...                   # 技能实现
├── healthcheck/               # 健康检查技能
├── node-connect/              # 节点连接技能
├── skill-creator/             # 技能创建技能
├── tmux/                      # tmux 控制技能
├── coding-agent/              # 编码代理
├── github/                    # GitHub 集成
├── gifgrep/                   # GIF 搜索
├── blucli/                    # 蓝牙工具
├── camsnap/                   # 相机快照
├── canvas/                    # 画布工具
├── clawhub/                   # ClawHub 集成
└── ... (50+ 技能)

技能文件格式（SKILL.md）：

markdown 复制代码

---
name: weather
description: 获取天气信息
---

# Weather Skill

## 触发条件
- 用户询问天气
- 用户提到温度、预报等关键词

## 使用方法
调用 weather 工具获取 wttr.in 或 Open-Meteo 数据

管理命令：

bash 复制代码

# 查看所有技能
openclaw skills list

# 查看技能详情
openclaw skills info <技能名>

# 检查技能就绪状态
openclaw skills check

工作原理：

Agent 启动时扫描 skills/ 目录
读取每个技能的 SKILL.md 描述文件
根据描述中的触发条件匹配用户请求
加载对应的技能实现代码
执行技能并返回结果

6. `extensions/` --- 插件扩展

位置： /home/ubuntu/.npm-global/lib/node_modules/openclaw/extensions/

大小： 18MB

插件数量： 45+ 个内置扩展

目录结构：

复制代码

extensions/
├── whatsapp/                  # WhatsApp 集成
├── telegram/                  # Telegram 集成
├── discord/                   # Discord 集成
├── slack/                     # Slack 集成
├── signal/                    # Signal 集成
├── imessage/                  # iMessage 集成
├── msteams/                   # Microsoft Teams
├── matrix/                    # Matrix 协议
├── googlechat/                # Google Chat
├── mattermost/                # Mattermost
│
├── memory-core/               # 核心记忆插件
├── memory-lancedb/            # LanceDB 记忆后端
│
├── qwen-portal-auth/          # Qwen 认证插件 ✅
├── ollama/                    # Ollama 本地模型
├── vllm/                      # vLLM 推理
├── minimax-portal-auth/       # MiniMax 认证
│
├── device-pair/               # 设备配对
├── acpx/                      # ACP 扩展
├── copilot-proxy/             # Copilot 代理
├── voice-call/                # 语音通话
│
├── bluebubbles/               # BlueBubbles
├── feishu/                    # 飞书
├── irc/                       # IRC
├── line/                      # LINE
├── llm-task/                  # LLM 任务
├── lobster/                   # Lobster 主题
├── nextcloud-talk/            # Nextcloud Talk
├── nostr/                     # Nostr 协议
├── open-prose/                # OpenProse
├── phone-control/             # 手机控制
├── sglang/                    # SGLang
├── synology-chat/             # Synology Chat
├── talk-voice/                # 语音通话
├── thread-ownership/          # 线程所有权
├── tlón/                      # Urbit Tlon
├── twitch/                    # Twitch
├── zalo/                      # Zalo
└── zalouser/                  # Zalo 用户

插件类型：

类型	插件示例	作用
渠道插件	whatsapp, telegram, discord	连接聊天平台
认证插件	qwen-portal-auth, ollama	AI 模型认证
记忆插件	memory-core, memory-lancedb	向量记忆存储
功能插件	device-pair, voice-call	扩展功能

管理命令：

bash 复制代码

# 查看已安装插件
openclaw plugins list

# 查看插件详情
openclaw plugins info <插件 ID>

# 启用/禁用插件
openclaw plugins enable <插件 ID>
openclaw plugins disable <插件 ID>

# 安装新插件
openclaw plugins install <路径|.tgz|npm-spec>

配置位置（openclaw.json）：

json 复制代码

{
  "plugins": {
    "entries": {
      "qwen-portal-auth": {
        "enabled": true
      }
    }
  }
}

工作原理：

Gateway 启动时加载 extensions/ 目录
读取 openclaw.json 中的 plugins.entries 配置
加载启用的插件模块
插件注册到 Gateway 的事件系统
插件可以添加新的命令、工具、渠道等

7. `node_modules/` --- npm 依赖包

位置： /home/ubuntu/.npm-global/lib/node_modules/openclaw/node_modules/

大小： 485MB

包数量： 362 个依赖包

核心依赖：

复制代码

node_modules/
├── @anthropic-ai/            # Anthropic Claude SDK
├── @agentclientprotocol/     # ACP 协议实现
├── ajv/                      # JSON Schema 验证
├── ajv-formats/              # JSON 格式验证
├── ws/                       # WebSocket 库
├── express/                  # Web 框架
├── @aws/                     # AWS SDK
├── axios/                    # HTTP 客户端
├── chalk/                    # 终端颜色
├── commander/                # CLI 框架
├── dotenv/                   # 环境变量
├── lodash/                   # 工具函数
├── uuid/                     # UUID 生成
└── ... (350+ 依赖)

注意： 不要手动修改此目录，使用 npm 管理依赖。

8. `assets/` --- 静态资源

位置： /home/ubuntu/.npm-global/lib/node_modules/openclaw/assets/

大小： 1.3MB

内容：

复制代码

assets/
├── avatar-placeholder.svg     # 头像占位图
├── dmg-background.png         # macOS DMG 安装背景 (1MB)
├── dmg-background-small.png   # 小尺寸背景 (224KB)
└── chrome-extension/          # Chrome 扩展资源

9. `README.md` & `CHANGELOG.md`

README.md (124KB)

项目介绍和快速开始
功能特性说明
安装和配置指南
使用示例

CHANGELOG.md (728KB)

详细的版本更新历史
每个版本的变更内容
Bug 修复和新功能
破坏性变更说明

📁 数据目录详解

路径： /home/ubuntu/.openclaw/

这是用户数据目录，存储配置、会话、记忆等所有个人数据。

整体结构

复制代码

.openclaw/
├── openclaw.json              # 主配置文件
├── openclaw.json.bak          # 配置备份
├── openclaw.json.bak.1        # 配置备份
├── update-check.json          # 更新检查状态
│
├── agents/                    # 多 Agent 工作区
│   └── main/                  # 默认 Agent
│       ├── sessions/          # 会话存储
│       │   ├── sessions.json              # 会话索引
│       │   └── <session-id>.jsonl         # 会话消息日志
│       └── memory/            # 向量记忆库
│
├── workspace/                 # 工作区目录
│   ├── SOUL.md               # AI 人格定义
│   ├── USER.md               # 用户信息
│   ├── IDENTITY.md           # AI 身份定义
│   ├── AGENTS.md             # 工作区指南
│   ├── TOOLS.md              # 本地工具配置
│   ├── HEARTBEAT.md          # 心跳任务
│   ├── MEMORY.md             # 长期记忆
│   └── memory/               # 每日记忆日志
│       └── YYYY-MM-DD.md
│
├── logs/                      # 网关日志
├── devices/                   # 配对设备信息
├── cron/                      # 定时任务数据
├── canvas/                    # 浏览器自动化缓存
├── completions/               # 代码补全缓存
├── identity/                  # 身份信息
└── update-check.json          # 更新检查

各目录详细说明

1. `openclaw.json` --- 主配置文件

位置： /home/ubuntu/.openclaw/openclaw.json

大小： 2.7KB

核心配置：

json 复制代码

{
  "meta": {
    "lastTouchedVersion": "2026.3.13",
    "lastTouchedAt": "2026-03-17T14:41:03.374Z"
  },
  
  "auth": {
    "profiles": {
      "qwen-portal:default": {
        "provider": "qwen-portal",
        "mode": "oauth"
      }
    }
  },
  
  "models": {
    "providers": {
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "qwen-oauth",
        "api": "openai-completions",
        "models": [
          {
            "id": "coder-model",
            "name": "Qwen Coder",
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  
  "agents": {
    "defaults": {
      "model": {
        "primary": "qwen-portal/coder-model"
      },
      "workspace": "/home/ubuntu/.openclaw/workspace"
    }
  },
  
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "e01dddef..."
    },
    "tailscale": {
      "mode": "off"
    }
  },
  
  "plugins": {
    "entries": {
      "qwen-portal-auth": {
        "enabled": true
      }
    }
  }
}

配置项说明：

配置项	作用	示例值
`auth.profiles`	AI 提供商认证配置	qwen-portal, openai, anthropic
`models.providers`	模型提供商配置	baseUrl, apiKey, models
`agents.defaults`	Agent 默认配置	model, workspace
`gateway`	网关服务配置	port, bind, auth
`plugins.entries`	插件启用状态	enabled: true/false

管理命令：

bash 复制代码

# 查看配置文件路径
openclaw config file

# 获取配置值
openclaw config get gateway.port

# 设置配置值
openclaw config set gateway.port 18790

# 验证配置
openclaw config validate

2. `agents/` --- 多 Agent 工作区

位置： /home/ubuntu/.openclaw/agents/

作用： 支持多个独立的 Agent 实例，每个 Agent 有独立的会话和记忆

目录结构：

复制代码

agents/
└── main/                      # 默认 Agent
    ├── sessions/              # 会话存储
    │   ├── sessions.json      # 会话索引
    │   └── ca29fbbb-*.jsonl   # 会话消息日志
    └── memory/                # 向量记忆库
        ├── index/             # 向量索引
        └── store/             # 记忆存储

sessions.json 格式：

json 复制代码

{
  "sessions": [
    {
      "key": "agent:main:webchat:direct",
      "createdAt": "2026-03-17T14:50:00.000Z",
      "lastActiveAt": "2026-03-17T15:00:00.000Z",
      "model": "qwen-portal/coder-model",
      "messageCount": 50
    }
  ]
}

.jsonl 格式：

jsonl 复制代码

{"type": "user", "text": "你好", "timestamp": "2026-03-17T14:50:00.000Z"}
{"type": "assistant", "text": "你好！我是阿程", "timestamp": "2026-03-17T14:50:01.000Z"}
{"type": "tool", "name": "web_search", "args": {...}, "timestamp": "..."}

管理命令：

bash 复制代码

# 查看所有会话
openclaw sessions

# 查看活跃会话
openclaw sessions --active 120

# JSON 格式输出
openclaw sessions --json

# 清理旧会话
openclaw sessions cleanup --dry-run

3. `workspace/` --- 工作区目录

位置： /home/ubuntu/.openclaw/workspace/

作用： Agent 的工作空间，包含人格定义、用户信息、记忆等

核心文件：

文件	作用	说明
`SOUL.md`	AI 人格定义	行为准则、语气风格、边界
`USER.md`	用户信息	姓名、时区、偏好、项目
`IDENTITY.md`	AI 身份	名字、角色、emoji
`AGENTS.md`	工作区指南	启动流程、记忆规则、红线
`TOOLS.md`	本地配置	设备名、SSH、相机、TTS
`HEARTBEAT.md`	心跳任务	定期检查的任务列表
`MEMORY.md`	长期记忆	curated 重要事件和决策
`memory/YYYY-MM-DD.md`	每日记忆	原始日志

SOUL.md 示例：

markdown 复制代码

# SOUL.md - Who You Are

## Core Truths
- Be genuinely helpful, not performatively helpful
- Have opinions
- Be resourceful before asking
- Earn trust through competence

## Boundaries
- Private things stay private
- Ask before acting externally
- Never send half-baked replies

## Vibe
Be the assistant you'd actually want to talk to.

记忆系统工作原理：

复制代码

用户对话 → 提取重要信息 → memory/YYYY-MM-DD.md (原始日志)
                              ↓
                      定期整理/提炼
                              ↓
                        MEMORY.md (长期记忆)
                              ↓
                    向量索引 (agents/memory/)
                              ↓
                    语义搜索 (memory_search 工具)

4. `logs/` --- 网关日志

位置： /home/ubuntu/.openclaw/logs/

作用： 存储 Gateway 运行日志

查看命令：

bash 复制代码

# 实时查看日志
openclaw logs --follow

# 查看最近 200 行
openclaw logs --limit 200

# JSON 格式输出
openclaw logs --json

# 纯文本输出
openclaw logs --plain

5. `devices/` --- 配对设备

位置： /home/ubuntu/.openclaw/devices/

作用： 存储配对的设备信息（手机、平板等）

管理命令：

bash 复制代码

# 查看已配对设备
openclaw devices list

# 批准配对请求
openclaw devices approve --latest

# 移除设备
openclaw devices remove <deviceId>

# 撤销设备令牌
openclaw devices revoke --device <id> --role <role>

6. `cron/` --- 定时任务

位置： /home/ubuntu/.openclaw/cron/

作用： 存储定时任务数据和执行历史

管理命令：

bash 复制代码

# 查看定时任务
openclaw cron list

# 添加定时任务
openclaw cron add --name "每日备份" --cron "0 2 * * *" --message "备份数据"

# 查看执行历史
openclaw cron runs --id <jobId>

# 立即执行任务
openclaw cron run <jobId>

🔬 核心文件深度解析

1. 会话存储原理

文件： agents/main/sessions/<session-id>.jsonl

格式： JSONL（JSON Lines）--- 每行一个 JSON 对象

示例内容：

jsonl 复制代码

{"id":"msg-001","type":"user","text":"你好","timestamp":"2026-03-17T14:50:00.000Z","channel":"webchat"}
{"id":"msg-002","type":"assistant","text":"你好！我是阿程","timestamp":"2026-03-17T14:50:01.000Z","model":"qwen-portal/coder-model"}
{"id":"msg-003","type":"tool","name":"memory_search","args":{"query":"用户信息"},"result":"...","timestamp":"..."}

为什么用 JSONL 而不是 JSON？

✅ 追加写入无需读取整个文件
✅ 流式处理，内存占用低
✅ 单行损坏不影响其他行
✅ 易于日志轮转和分割

会话加载流程：

复制代码

1. 读取 sessions.json 获取会话列表
2. 根据会话 key 找到对应的 .jsonl 文件
3. 流式读取 JSONL 文件
4. 解析每行 JSON 构建消息数组
5. 传递给 AI 模型作为上下文

2. 记忆系统原理

核心组件：

复制代码

记忆系统
├── 文件存储层
│   ├── MEMORY.md              # 长期记忆（Markdown）
│   └── memory/*.md            # 每日记忆（Markdown）
│
├── 向量索引层
│   ├── memory-core            # 核心插件
│   └── memory-lancedb         # LanceDB 后端
│
└── 搜索 API 层
    └── memory_search 工具

向量搜索流程：

复制代码

用户查询："我之前说过什么关于 Python 的事？"
         ↓
memory_search 工具触发
         ↓
查询文本 → 嵌入模型 → 向量表示
         ↓
在向量数据库中搜索相似向量
         ↓
返回 Top-N 匹配片段（带路径和行号）
         ↓
AI 根据检索结果生成回答

记忆检索示例：

json 复制代码

{
  "results": [
    {
      "path": "memory/2026-03-17.md",
      "lines": "15-20",
      "score": 0.89,
      "text": "竹之却提到正在学习 Python，想用 AI 辅助编程"
    },
    {
      "path": "MEMORY.md",
      "lines": "42-45",
      "score": 0.76,
      "text": "用户偏好：Python > JavaScript，喜欢简洁的代码风格"
    }
  ]
}

3. 插件系统原理

插件加载流程：

复制代码

Gateway 启动
    ↓
扫描 extensions/ 目录
    ↓
读取 openclaw.json 中的 plugins.entries
    ↓
加载启用的插件模块
    ↓
插件注册到事件系统
    ↓
插件可以：
  - 添加新的渠道（WhatsApp/Telegram）
  - 添加新的工具（browser/web_search）
  - 添加新的命令（cron/memory）
  - 修改 AI 行为（hooks）

插件结构示例（qwen-portal-auth）：

复制代码

extensions/qwen-portal-auth/
├── index.js                   # 插件入口
├── provider.js                # 提供商实现
├── oauth.js                   # OAuth 流程
└── package.json               # 插件配置

插件注册代码示例：

javascript 复制代码

export default {
  name: 'qwen-portal-auth',
  activate(ctx) {
    // 注册认证提供商
    ctx.models.registerProvider('qwen-portal', {
      baseUrl: 'https://portal.qwen.ai/v1',
      auth: 'oauth'
    });
    
    // 注册 OAuth 回调
    ctx.auth.registerOAuthHandler('qwen-portal', handleOAuth);
  }
};

4. Gateway 工作原理

Gateway 是 OpenClaw 的核心服务

启动流程：

复制代码

openclaw gateway start
    ↓
1. 读取 openclaw.json 配置
2. 绑定到指定端口（默认 18789）
3. 启动 WebSocket 服务器
4. 加载插件系统
5. 初始化 Agent 实例
6. 连接配置的渠道（WhatsApp/Telegram 等）
7. 启动 Cron 调度器
8. 启动记忆索引服务
    ↓
Gateway 运行中...

消息处理流程：

复制代码

用户发送消息（WhatsApp/Telegram/Web）
    ↓
渠道插件接收消息
    ↓
转换为统一消息格式
    ↓
发送到 Gateway WebSocket
    ↓
Gateway 路由到对应 Agent
    ↓
Agent 加载会话历史
    ↓
调用 memory_search 检索记忆
    ↓
调用工具（web_search/browser 等）
    ↓
AI 模型生成回复
    ↓
通过渠道插件发送回用户

🏗️ 目录结构原理

设计原则

安装与数据分离
- 安装目录：程序代码，升级可覆盖
- 数据目录：用户数据，永久保存
模块化设计
- 每个技能、插件独立目录
- 易于扩展和维护
多 Agent 支持
- agents/<agent-id>/ 隔离不同 Agent
- 每个 Agent 独立会话和记忆
文件化存储
- 会话用 JSONL 文件
- 记忆用 Markdown 文件
- 易于备份和版本控制

目录命名规范

目录名	复数形式	说明
`agent`	`agents/`	多个 Agent 实例
`session`	`sessions/`	多个会话
`skill`	`skills/`	多个技能
`extension`	`extensions/`	多个插件
`memory`	`memory/`	记忆（不可数）
`log`	`logs/`	多个日志文件

📝 常用命令速查

位置查询

bash 复制代码

# 查看 CLI 安装位置
which openclaw

# 查看模块安装位置
npm list -g openclaw

# 查看配置文件路径
openclaw config file

# 查看数据目录
echo $HOME/.openclaw

配置管理

bash 复制代码

# 获取配置
openclaw config get <路径>

# 设置配置
openclaw config set <路径> <值>

# 验证配置
openclaw config validate

会话管理

bash 复制代码

# 查看会话
openclaw sessions [--active <分钟>] [--json]

# 清理会话
openclaw sessions cleanup --dry-run

技能管理

bash 复制代码

# 查看技能
openclaw skills list

# 技能详情
openclaw skills info <技能名>

# 检查技能
openclaw skills check

插件管理

bash 复制代码

# 查看插件
openclaw plugins list

# 插件详情
openclaw plugins info <插件 ID>

# 启用/禁用
openclaw plugins enable <插件 ID>
openclaw plugins disable <插件 ID>

日志查看

bash 复制代码

# 实时日志
openclaw logs --follow

# 最近 N 行
openclaw logs --limit <N>

# JSON 格式
openclaw logs --json

文档搜索

bash 复制代码

# 搜索文档
openclaw docs <关键词>

📊 目录大小对比

目录	大小	占比	说明
`node_modules/`	485MB	83%	npm 依赖包
`dist/`	69MB	12%	编译代码
`extensions/`	18MB	3%	插件扩展
`docs/`	16MB	2.7%	文档
`assets/`	1.3MB	0.2%	静态资源
`skills/`	728KB	0.1%	技能库
`CHANGELOG.md`	728KB	0.1%	更新日志
`README.md`	124KB	0.02%	项目说明
`package.json`	24KB	-	包配置
`openclaw.mjs`	4KB	-	入口文件

总计： 约 590MB

🎯 总结

OpenClaw 的目录设计体现了以下理念：

1. 清晰的职责分离

2. 高度模块化

每个技能、插件独立
易于扩展和定制

3. 文件化存储

会话、记忆都用文件存储
易于备份、版本控制、迁移

4. 多 Agent 架构

支持多个独立 Agent 实例
每个 Agent 有自己的会话和记忆

5. 完善的文档

16MB 的本地文档
支持多语言
可通过 CLI 搜索

🔗 参考链接

官方文档： https://docs.openclaw.ai
GitHub： https://github.com/openclaw/openclaw
ClawHub（技能市场）： https://clawhub.com
社区 Discord： https://discord.com/invite/clawd

End

你好，少年，未来可期~

本文由作者最佳伙伴------阿程，赞助推出！！

OpenClaw 目录结构详细介绍

OpenClaw 目录结构详细介绍

🚀 快速概览

📦 安装目录详解

整体结构

各目录详细说明

1. openclaw.mjs --- CLI 入口文件

2. package.json --- npm 包配置

3. dist/ --- 编译后的核心代码

4. docs/ --- 官方文档

5. skills/ --- AgentSkills 技能库

6. extensions/ --- 插件扩展

7. node_modules/ --- npm 依赖包

8. assets/ --- 静态资源

9. README.md & CHANGELOG.md

📁 数据目录详解

整体结构

各目录详细说明

1. openclaw.json --- 主配置文件

2. agents/ --- 多 Agent 工作区

3. workspace/ --- 工作区目录

4. logs/ --- 网关日志

5. devices/ --- 配对设备

6. cron/ --- 定时任务

🔬 核心文件深度解析

1. 会话存储原理

2. 记忆系统原理

3. 插件系统原理

4. Gateway 工作原理

🏗️ 目录结构原理

设计原则

目录命名规范

📝 常用命令速查

位置查询

配置管理

会话管理

技能管理

插件管理

日志查看

文档搜索

📊 目录大小对比

🎯 总结

1. 清晰的职责分离

2. 高度模块化

3. 文件化存储

4. 多 Agent 架构

5. 完善的文档

🔗 参考链接

1. `openclaw.mjs` --- CLI 入口文件

2. `package.json` --- npm 包配置

3. `dist/` --- 编译后的核心代码

4. `docs/` --- 官方文档

5. `skills/` --- AgentSkills 技能库

6. `extensions/` --- 插件扩展

7. `node_modules/` --- npm 依赖包

8. `assets/` --- 静态资源

9. `README.md` & `CHANGELOG.md`

1. `openclaw.json` --- 主配置文件

2. `agents/` --- 多 Agent 工作区

3. `workspace/` --- 工作区目录

4. `logs/` --- 网关日志

5. `devices/` --- 配对设备

6. `cron/` --- 定时任务