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. 完善的文档 参考链接 快速概览OpenClaw 的目录分为两大类类型路径用途是否可修改安装目录/home/ubuntu/.npm-global/lib/node_modules/openclaw/程序代码、文档、技能、插件❌ 不建议修改数据目录/home/ubuntu/.openclaw/配置、会话、记忆、日志✅ 用户数据核心命令查看位置# 查看 CLI 安装位置whichopenclaw# 输出/home/ubuntu/.npm-global/bin/openclaw# 查看模块安装位置npmlist-gopenclaw# 输出openclaw2026.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 命令行工具的启动脚本核心功能#!/usr/bin/env node// 1. 检查 Node.js 版本要求 v22.12constMIN_NODE_MAJOR22;constMIN_NODE_MINOR12;// 2. 启用模块编译缓存性能优化module.enableCompileCache();// 3. 安装进程警告过滤器// 4. 加载主程序工作原理验证 Node.js 版本是否符合要求启用编译缓存加速后续启动过滤掉不必要的警告信息加载dist/目录中的主程序2.package.json— npm 包配置位置/home/ubuntu/.npm-global/lib/node_modules/openclaw/package.json大小24KB核心内容{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/访问方式# 本地搜索文档openclaw docs关键词# 在线文档https://docs.openclaw.ai5.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--- name: weather description: 获取天气信息 --- # Weather Skill ## 触发条件 - 用户询问天气 - 用户提到温度、预报等关键词 ## 使用方法 调用 weather 工具获取 wttr.in 或 Open-Meteo 数据管理命令# 查看所有技能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, ollamaAI 模型认证记忆插件memory-core, memory-lancedb向量记忆存储功能插件device-pair, voice-call扩展功能管理命令# 查看已安装插件openclaw plugins list# 查看插件详情openclaw plugins info插件 ID# 启用/禁用插件openclaw pluginsenable插件 IDopenclaw plugins disable插件 ID# 安装新插件openclaw pluginsinstall路径|.tgz|npm-spec配置位置openclaw.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.mdCHANGELOG.mdREADME.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核心配置{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.profilesAI 提供商认证配置qwen-portal, openai, anthropicmodels.providers模型提供商配置baseUrl, apiKey, modelsagents.defaultsAgent 默认配置model, workspacegateway网关服务配置port, bind, authplugins.entries插件启用状态enabled: true/false管理命令# 查看配置文件路径openclaw configfile# 获取配置值openclaw config get gateway.port# 设置配置值openclaw configsetgateway.port18790# 验证配置openclaw config validate2.agents/— 多 Agent 工作区位置/home/ubuntu/.openclaw/agents/作用支持多个独立的 Agent 实例每个 Agent 有独立的会话和记忆目录结构agents/ └── main/ # 默认 Agent ├── sessions/ # 会话存储 │ ├── sessions.json # 会话索引 │ └── ca29fbbb-*.jsonl # 会话消息日志 └── memory/ # 向量记忆库 ├── index/ # 向量索引 └── store/ # 记忆存储sessions.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 格式{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: ...}管理命令# 查看所有会话openclaw sessions# 查看活跃会话openclaw sessions--active120# JSON 格式输出openclaw sessions--json# 清理旧会话openclaw sessions cleanup --dry-run3.workspace/— 工作区目录位置/home/ubuntu/.openclaw/workspace/作用Agent 的工作空间包含人格定义、用户信息、记忆等核心文件文件作用说明SOUL.mdAI 人格定义行为准则、语气风格、边界USER.md用户信息姓名、时区、偏好、项目IDENTITY.mdAI 身份名字、角色、emojiAGENTS.md工作区指南启动流程、记忆规则、红线TOOLS.md本地配置设备名、SSH、相机、TTSHEARTBEAT.md心跳任务定期检查的任务列表MEMORY.md长期记忆curated 重要事件和决策memory/YYYY-MM-DD.md每日记忆原始日志SOUL.md 示例# 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 youd actually want to talk to.记忆系统工作原理用户对话 → 提取重要信息 → memory/YYYY-MM-DD.md (原始日志) ↓ 定期整理/提炼 ↓ MEMORY.md (长期记忆) ↓ 向量索引 (agents/memory/) ↓ 语义搜索 (memory_search 工具)4.logs/— 网关日志位置/home/ubuntu/.openclaw/logs/作用存储 Gateway 运行日志查看命令# 实时查看日志openclaw logs--follow# 查看最近 200 行openclaw logs--limit200# JSON 格式输出openclaw logs--json# 纯文本输出openclaw logs--plain5.devices/— 配对设备位置/home/ubuntu/.openclaw/devices/作用存储配对的设备信息手机、平板等管理命令# 查看已配对设备openclaw devices list# 批准配对请求openclaw devices approve--latest# 移除设备openclaw devices removedeviceId# 撤销设备令牌openclaw devices revoke--deviceid--rolerole6.cron/— 定时任务位置/home/ubuntu/.openclaw/cron/作用存储定时任务数据和执行历史管理命令# 查看定时任务openclawcronlist# 添加定时任务openclawcronadd--name每日备份--cron0 2 * * *--message备份数据# 查看执行历史openclawcronruns--idjobId# 立即执行任务openclawcronrunjobId 核心文件深度解析1. 会话存储原理文件agents/main/sessions/session-id.jsonl格式JSONLJSON Lines— 每行一个 JSON 对象示例内容{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 根据检索结果生成回答记忆检索示例{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-authextensions/qwen-portal-auth/ ├── index.js # 插件入口 ├── provider.js # 提供商实现 ├── oauth.js # OAuth 流程 └── package.json # 插件配置插件注册代码示例exportdefault{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 文件易于备份和版本控制目录命名规范目录名复数形式说明agentagents/多个 Agent 实例sessionsessions/多个会话skillskills/多个技能extensionextensions/多个插件memorymemory/记忆不可数loglogs/多个日志文件 常用命令速查位置查询# 查看 CLI 安装位置whichopenclaw# 查看模块安装位置npmlist-gopenclaw# 查看配置文件路径openclaw configfile# 查看数据目录echo$HOME/.openclaw配置管理# 获取配置openclaw config get路径# 设置配置openclaw configset路径值# 验证配置openclaw config validate会话管理# 查看会话openclaw sessions[--active分钟][--json]# 清理会话openclaw sessions cleanup --dry-run技能管理# 查看技能openclaw skills list# 技能详情openclaw skills info技能名# 检查技能openclaw skills check插件管理# 查看插件openclaw plugins list# 插件详情openclaw plugins info插件 ID# 启用/禁用openclaw pluginsenable插件 IDopenclaw plugins disable插件 ID日志查看# 实时日志openclaw logs--follow# 最近 N 行openclaw logs--limitN# JSON 格式openclaw logs--json文档搜索# 搜索文档openclaw docs关键词 目录大小对比目录大小占比说明node_modules/485MB83%npm 依赖包dist/69MB12%编译代码extensions/18MB3%插件扩展docs/16MB2.7%文档assets/1.3MB0.2%静态资源skills/728KB0.1%技能库CHANGELOG.md728KB0.1%更新日志README.md124KB0.02%项目说明package.json24KB-包配置openclaw.mjs4KB-入口文件总计约 590MB 总结OpenClaw 的目录设计体现了以下理念1. 清晰的职责分离安装目录 程序本身只读数据目录 用户数据可写2. 高度模块化每个技能、插件独立易于扩展和定制3. 文件化存储会话、记忆都用文件存储易于备份、版本控制、迁移4. 多 Agent 架构支持多个独立 Agent 实例每个 Agent 有自己的会话和记忆5. 完善的文档16MB 的本地文档支持多语言可通过 CLI 搜索 参考链接官方文档https://docs.openclaw.aiGitHubhttps://github.com/openclaw/openclawClawHub技能市场https://clawhub.com社区 Discordhttps://discord.com/invite/clawdEnd你好少年未来可期~本文由作者最佳伙伴——阿程赞助推出
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. 完善的文档 参考链接 快速概览OpenClaw 的目录分为两大类类型路径用途是否可修改安装目录/home/ubuntu/.npm-global/lib/node_modules/openclaw/程序代码、文档、技能、插件❌ 不建议修改数据目录/home/ubuntu/.openclaw/配置、会话、记忆、日志✅ 用户数据核心命令查看位置# 查看 CLI 安装位置whichopenclaw# 输出/home/ubuntu/.npm-global/bin/openclaw# 查看模块安装位置npmlist-gopenclaw# 输出openclaw2026.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 命令行工具的启动脚本核心功能#!/usr/bin/env node// 1. 检查 Node.js 版本要求 v22.12constMIN_NODE_MAJOR22;constMIN_NODE_MINOR12;// 2. 启用模块编译缓存性能优化module.enableCompileCache();// 3. 安装进程警告过滤器// 4. 加载主程序工作原理验证 Node.js 版本是否符合要求启用编译缓存加速后续启动过滤掉不必要的警告信息加载dist/目录中的主程序2.package.json— npm 包配置位置/home/ubuntu/.npm-global/lib/node_modules/openclaw/package.json大小24KB核心内容{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/访问方式# 本地搜索文档openclaw docs关键词# 在线文档https://docs.openclaw.ai5.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--- name: weather description: 获取天气信息 --- # Weather Skill ## 触发条件 - 用户询问天气 - 用户提到温度、预报等关键词 ## 使用方法 调用 weather 工具获取 wttr.in 或 Open-Meteo 数据管理命令# 查看所有技能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, ollamaAI 模型认证记忆插件memory-core, memory-lancedb向量记忆存储功能插件device-pair, voice-call扩展功能管理命令# 查看已安装插件openclaw plugins list# 查看插件详情openclaw plugins info插件 ID# 启用/禁用插件openclaw pluginsenable插件 IDopenclaw plugins disable插件 ID# 安装新插件openclaw pluginsinstall路径|.tgz|npm-spec配置位置openclaw.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.mdCHANGELOG.mdREADME.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核心配置{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.profilesAI 提供商认证配置qwen-portal, openai, anthropicmodels.providers模型提供商配置baseUrl, apiKey, modelsagents.defaultsAgent 默认配置model, workspacegateway网关服务配置port, bind, authplugins.entries插件启用状态enabled: true/false管理命令# 查看配置文件路径openclaw configfile# 获取配置值openclaw config get gateway.port# 设置配置值openclaw configsetgateway.port18790# 验证配置openclaw config validate2.agents/— 多 Agent 工作区位置/home/ubuntu/.openclaw/agents/作用支持多个独立的 Agent 实例每个 Agent 有独立的会话和记忆目录结构agents/ └── main/ # 默认 Agent ├── sessions/ # 会话存储 │ ├── sessions.json # 会话索引 │ └── ca29fbbb-*.jsonl # 会话消息日志 └── memory/ # 向量记忆库 ├── index/ # 向量索引 └── store/ # 记忆存储sessions.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 格式{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: ...}管理命令# 查看所有会话openclaw sessions# 查看活跃会话openclaw sessions--active120# JSON 格式输出openclaw sessions--json# 清理旧会话openclaw sessions cleanup --dry-run3.workspace/— 工作区目录位置/home/ubuntu/.openclaw/workspace/作用Agent 的工作空间包含人格定义、用户信息、记忆等核心文件文件作用说明SOUL.mdAI 人格定义行为准则、语气风格、边界USER.md用户信息姓名、时区、偏好、项目IDENTITY.mdAI 身份名字、角色、emojiAGENTS.md工作区指南启动流程、记忆规则、红线TOOLS.md本地配置设备名、SSH、相机、TTSHEARTBEAT.md心跳任务定期检查的任务列表MEMORY.md长期记忆curated 重要事件和决策memory/YYYY-MM-DD.md每日记忆原始日志SOUL.md 示例# 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 youd actually want to talk to.记忆系统工作原理用户对话 → 提取重要信息 → memory/YYYY-MM-DD.md (原始日志) ↓ 定期整理/提炼 ↓ MEMORY.md (长期记忆) ↓ 向量索引 (agents/memory/) ↓ 语义搜索 (memory_search 工具)4.logs/— 网关日志位置/home/ubuntu/.openclaw/logs/作用存储 Gateway 运行日志查看命令# 实时查看日志openclaw logs--follow# 查看最近 200 行openclaw logs--limit200# JSON 格式输出openclaw logs--json# 纯文本输出openclaw logs--plain5.devices/— 配对设备位置/home/ubuntu/.openclaw/devices/作用存储配对的设备信息手机、平板等管理命令# 查看已配对设备openclaw devices list# 批准配对请求openclaw devices approve--latest# 移除设备openclaw devices removedeviceId# 撤销设备令牌openclaw devices revoke--deviceid--rolerole6.cron/— 定时任务位置/home/ubuntu/.openclaw/cron/作用存储定时任务数据和执行历史管理命令# 查看定时任务openclawcronlist# 添加定时任务openclawcronadd--name每日备份--cron0 2 * * *--message备份数据# 查看执行历史openclawcronruns--idjobId# 立即执行任务openclawcronrunjobId 核心文件深度解析1. 会话存储原理文件agents/main/sessions/session-id.jsonl格式JSONLJSON Lines— 每行一个 JSON 对象示例内容{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 根据检索结果生成回答记忆检索示例{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-authextensions/qwen-portal-auth/ ├── index.js # 插件入口 ├── provider.js # 提供商实现 ├── oauth.js # OAuth 流程 └── package.json # 插件配置插件注册代码示例exportdefault{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 文件易于备份和版本控制目录命名规范目录名复数形式说明agentagents/多个 Agent 实例sessionsessions/多个会话skillskills/多个技能extensionextensions/多个插件memorymemory/记忆不可数loglogs/多个日志文件 常用命令速查位置查询# 查看 CLI 安装位置whichopenclaw# 查看模块安装位置npmlist-gopenclaw# 查看配置文件路径openclaw configfile# 查看数据目录echo$HOME/.openclaw配置管理# 获取配置openclaw config get路径# 设置配置openclaw configset路径值# 验证配置openclaw config validate会话管理# 查看会话openclaw sessions[--active分钟][--json]# 清理会话openclaw sessions cleanup --dry-run技能管理# 查看技能openclaw skills list# 技能详情openclaw skills info技能名# 检查技能openclaw skills check插件管理# 查看插件openclaw plugins list# 插件详情openclaw plugins info插件 ID# 启用/禁用openclaw pluginsenable插件 IDopenclaw plugins disable插件 ID日志查看# 实时日志openclaw logs--follow# 最近 N 行openclaw logs--limitN# JSON 格式openclaw logs--json文档搜索# 搜索文档openclaw docs关键词 目录大小对比目录大小占比说明node_modules/485MB83%npm 依赖包dist/69MB12%编译代码extensions/18MB3%插件扩展docs/16MB2.7%文档assets/1.3MB0.2%静态资源skills/728KB0.1%技能库CHANGELOG.md728KB0.1%更新日志README.md124KB0.02%项目说明package.json24KB-包配置openclaw.mjs4KB-入口文件总计约 590MB 总结OpenClaw 的目录设计体现了以下理念1. 清晰的职责分离安装目录 程序本身只读数据目录 用户数据可写2. 高度模块化每个技能、插件独立易于扩展和定制3. 文件化存储会话、记忆都用文件存储易于备份、版本控制、迁移4. 多 Agent 架构支持多个独立 Agent 实例每个 Agent 有自己的会话和记忆5. 完善的文档16MB 的本地文档支持多语言可通过 CLI 搜索 参考链接官方文档https://docs.openclaw.aiGitHubhttps://github.com/openclaw/openclawClawHub技能市场https://clawhub.com社区 Discordhttps://discord.com/invite/clawdEnd你好少年未来可期~本文由作者最佳伙伴——阿程赞助推出
