OpenClaw 部署

ubuntu

Posted by LXG on March 20, 2026

openclaw

openclaw中文文档

概念

适用于任何操作系统的 AI 智能体 Gateway 网关,支持 WhatsApp、Telegram、Discord、iMessage 等。 发送消息,随时随地获取智能体响应。通过插件可添加 Mattermost 等更多渠道。

源码目录


openclaw/
├── AGENTS.md              # 🤖 AI代理/系统说明(类似设计文档)
├── CLAUDE.md -> AGENTS.md # 👉 软链接(给 Claude/AI 用的说明)
├── VISION.md              # 🧭 项目愿景(了解架构思想用)
├── CHANGELOG.md           # 📜 更新记录
├── CONTRIBUTING.md        # 👨‍💻 贡献指南
├── LICENSE                # 📄 开源协议
├── SECURITY.md            # 🔐 安全策略

├── README.md              # 📘 入口文档(建议精读)
├── docs/                  # 📚 详细文档
├── docs.acp.md            # 🧠 ACP(Agent Control Protocol?)说明

├── apps/                  # 🚀 【核心】应用层(入口!!!)
│                          # 👉 前端 / 后端 / 网关 都在这里
│                          # 👉 等你 ls apps 后重点分析

├── packages/              # 📦 公共库(类似 framework 层)
│                          # 👉 各个 app 共享代码
│                          # 👉 比如 API 封装 / utils

├── ui/                    # 🎨 UI组件库(React组件)
│                          # 👉 Button / Chat UI / Layout
│                          # 👉 Panel 的“外观”

├── src/                   # 🧠 核心逻辑(可能是服务端 or SDK)
│                          # 👉 有时是核心 runtime / agent逻辑

├── extensions/            # 🔌 插件系统(扩展能力)
│                          # 👉 类似 ChatGPT plugin

├── skills/                # 🧠 AI技能(Agent能力定义)
│                          # 👉 很关键(AI行为逻辑)

├── vendor/                # 📦 第三方代码(内置依赖)

├── assets/                # 🖼️ 静态资源(图片 / 图标)

├── test/                  # 🧪 测试代码
├── test-fixtures/         # 🧪 测试数据

├── scripts/               # ⚙️ 脚本(构建/部署辅助)

├── git-hooks/             # 🔧 git hook(代码提交检查)

├── patches/               # 🩹 依赖补丁(patch-package)

├── Swabble/               # ❓(可能是内部模块/实验功能)

├── openclaw.mjs           # 🚀 启动入口(Node 脚本,很重要)
                          # 👉 可能是 CLI / 主程序入口

├── package.json           # 📦 Node 主配置
├── pnpm-lock.yaml         # 🔒 依赖锁
├── pnpm-workspace.yaml    # 🧠 workspace定义(关键!)
                          # 👉 决定 apps/packages 关系

├── tsconfig.json          # 🟦 TypeScript配置
├── tsconfig.plugin-sdk.dts.json # 插件SDK类型定义

├── tsdown.config.ts       # ⚙️ 构建配置(可能是打包工具)

├── knip.config.ts         # 🧹 检查未使用依赖

├── vitest*.ts             # 🧪 单元测试配置(很多)
                          # 👉 说明项目很工程化

├── docker-compose.yml     # 🐳 一键部署(包含多个服务)
├── Dockerfile             # 🐳 主镜像
├── Dockerfile.sandbox*    # 🧪 沙箱环境(执行代码用)
├── docker-setup.sh        # ⚙️ Docker初始化脚本

├── setup-podman.sh        # 🐳 Podman支持(替代docker)
├── openclaw.podman.env    # 环境变量(podman)

├── fly.toml               # ☁️ Fly.io部署配置
├── fly.private.toml       # ☁️ 私有部署配置
├── render.yaml            # ☁️ Render部署配置

├── pyproject.toml         # 🐍 Python环境(很重要!)
                          # 👉 说明有 Python AI 后端

├── zizmor.yml             # 🔍 CI / 安全扫描

架构


        ┌───────────────┐
        │     apps      │  ← 🚀 应用入口(前端/后端)
        └──────┬────────┘
               │
        ┌──────▼────────┐
        │   packages    │  ← 📦 公共逻辑(类似framework)
        └──────┬────────┘
               │
   ┌───────────▼───────────┐
   │   skills / extensions │  ← 🧠 AI能力层
   └───────────┬───────────┘
               │
        ┌──────▼──────┐
        │   模型/API   │  ← 🔌 推理层(外部 or 内置)
        └─────────────┘

package.json

package.json-github


                ┌──────────────┐
                │   CLI / UI   │
                └──────┬───────┘
                       │
                ┌──────▼───────┐
                │   Gateway    │  ← 核心
                └──────┬───────┘
                       │
        ┌──────────────▼──────────────┐
        │        Plugin SDK           │
        │ (agent / provider / tools)  │
        └──────────────┬──────────────┘
                       │
        ┌──────────────▼──────────────┐
        │   多渠道 (Telegram/Slack…)   │
        └──────────────┬──────────────┘
                       │
                ┌──────▼──────┐
                │   LLM层      │
                └─────────────┘

CLI 入口

openclaw.mjs = 整个系统的“启动入口”


"bin": {
  "openclaw": "openclaw.mjs"
}

openclaw.mjs 是一个 JavaScript 脚本文件,采用了 ES Modules (ESM) 标准

模块导出(🔥 架构核心)


  "main": "dist/index.js",
  "exports": {
    ".": "./dist/index.js",
    "./plugin-sdk": {
      "types": "./dist/plugin-sdk/index.d.ts",
      "default": "./dist/plugin-sdk/index.js"
    },
    "./plugin-sdk/telegram": {
      "types": "./dist/plugin-sdk/telegram.d.ts",
      "default": "./dist/plugin-sdk/telegram.js"
    },
    "./plugin-sdk/telegram-core": {
      "types": "./dist/plugin-sdk/telegram-core.d.ts",
      "default": "./dist/plugin-sdk/telegram-core.js"
    },
    "./cli-entry": "./openclaw.mjs"
  },

在 package.json 里,所有 plugin-sdk 的路径都指向了 dist/plugin-sdk/。

  • dist/ 是编译后的产物:这意味着 plugin-sdk 的原始 TypeScript 代码分散在 src/ 目录下的各个核心模块中。
  • 真正的源码目录通常是: src/plugin-sdk/ 或者分布在 src/core/、src/runtime/ 之中。
  • 构建逻辑:当你运行 pnpm build 或 pnpm build:plugin-sdk:dts 时,构建脚本会提取 src 中的接口定义,并按照 package.json 里的映射关系,把它们重组到 dist/plugin-sdk/ 目录下。

plugin-sdk = OpenClaw 的“操作系统 API”

OpenClaw 的核心设计

它不是一个应用, 而是一个“平台 + SDK”

plugin-sdk 是什么?

plugin-sdk = 插件开发框架

在 OpenClaw 的工程结构中,找不到 plugin-sdk 目录是非常正常的,因为 plugin-sdk 不是一个源码目录,而是一个“发布别名(Alias)”或“虚拟映射”。

AI 核心运行时


"./plugin-sdk/agent-runtime"
"./plugin-sdk/llm-task"
"./plugin-sdk/text-runtime"
"./plugin-sdk/conversation-runtime"

多渠道支持


"./plugin-sdk/telegram"
"./plugin-sdk/discord"
"./plugin-sdk/slack"
"./plugin-sdk/whatsapp"
"./plugin-sdk/matrix"
"./plugin-sdk/msteams"

Provider(模型层)


"./plugin-sdk/provider-models"
"./plugin-sdk/provider-stream"
"./plugin-sdk/provider-auth"
"./plugin-sdk/provider-web-search"

Memory(记忆系统)


"./plugin-sdk/memory-lancedb"

支持向量数据库(AI 记忆)

安全


"./plugin-sdk/security-runtime"

网关


"./plugin-sdk/gateway-runtime"

scripts(🔥 启动方式)


"dev": "node scripts/run-node.mjs",
"start": "node scripts/run-node.mjs"

真正入口不是 openclaw.mjs 而是 scripts/run-node.mjs

网关启动(重点)


"gateway:dev": "node scripts/run-node.mjs --dev gateway"

gateway 是核心服务, gateway = AI 请求入口(类似 API Server)

dependencies(看架构)

Web 框架

既支持传统 API(express),也支持轻量网关(hono)


"express": "^5.2.1",
"hono": "4.12.8"

网络通信

WebSocket(实时通信)


"ws": "^8.19.0"

AI 相关

MCP / ACP(AI协议)


"@modelcontextprotocol/sdk"
"@agentclientprotocol/sdk"

AI agent 系列(重点)

OpenClaw 直接基于“现成 Agent 框架”


"@mariozechner/pi-agent-core"
"@mariozechner/pi-ai"
"@mariozechner/pi-coding-agent"

向量数据库

本地 embedding + memory


"sqlite-vec"

多媒体能力

❗支持多模态 AI


"sharp"           // 图像处理
"pdfjs-dist"      // PDF解析
"node-edge-tts"   // 语音

peerDependencies

本地模型支持


"node-llama-cpp": "3.16.2"

OpenClaw 如何启动“整个 AI 系统”


node openclaw.mjs
 → 初始化 runtime
 → 启动 gateway(核心调度)
 → 加载 skills(AI能力)
 → 启动 sandbox(执行环境)
 → 对外提供 API/UI

指令执行流程


用户输入
   ↓
Gateway
   ↓
任务拆解(可能用 LLM)
   ↓
选择 Skill
   ↓
执行(sandbox)
   ↓
返回结果

openclaw.mjs