openclaw 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

openclaw 是一个以 TypeScript 编写的个人人工智能助手（Artificial Intelligence Assistant）项目，核心运行形态是连接模型、工具、消息渠道和可选伴侣应用的网关（Gateway）。项目面向单一操作者，助手可以运行在用户自己的设备上，并通过用户已经使用的聊天渠道提供交互。

仓库默认分支为 main，GitHub 页面资料显示 Star 数为 386176、Fork 数为 81170。package.json 当前记录的包版本为 2026.8.1，包许可证字段为 MIT；仓库元信息中的许可证显示为 NOASSERTION，实际许可判断应以仓库中的 LICENSE 文件为准。

“OpenClaw is a personal AI assistant that runs on your devices and meets you in the channels you already use.”

来源：README

定位与目标用户

本项目的定位不是单独的聊天网页，而是一个本地控制平面（Control Plane）。它把模型访问、会话、工具调用、消息渠道连接和设备节点集中到 Gateway 中，再由控制界面、命令行工具（CLI）或终端用户界面（TUI）连接该 Gateway。

目标用户需要管理模型凭据、消息渠道、工作区和本地运行环境。README 明确将项目设计为“单一操作者”使用，因此在把它连接给其他用户之前，应先阅读安全、暴露面和沙箱文档，并自行完成访问控制和数据边界评估。

• 希望在自己的设备上运行个人助手，并从多个聊天渠道访问同一套会话与工具的人。
• 需要把托管模型或本地模型提供商接入统一网关的人。
• 需要通过工具（Tools）、技能（Skills）和插件（Plugins）扩展助手行为的开发者。
• 需要在 macOS、Linux、Windows 或 WSL2 环境中部署服务的使用者。

核心功能

OpenClaw 的核心能力由 Gateway 统一编排，消息渠道负责输入与输出，模型提供商负责生成模型响应，工具和插件负责扩展动作。每项能力都依赖相应的凭据、配置和运行环境，不能仅凭安装命令推断所有渠道或模型已经可用。

统一网关与会话管理

Gateway 是本地控制平面，负责会话（Sessions）、工具（Tools）、事件（Events）以及渠道连接。控制界面、CLI 和 TUI 不直接取代 Gateway，而是作为连接端；用户在 Control UI 中发送消息后，Gateway 才会按已配置的模型、工具和渠道处理请求。

Gateway 的启动方式可以通过 CLI 触发，Docker Compose 中则由容器执行 node dist/index.js gateway。Compose 将容器内 Gateway 端口设置为 18789，并把桥接端口设置为 18790；是否对外暴露以及绑定到何种网络范围，应由部署者根据环境配置。

多渠道消息接入

README 列出的消息渠道包括 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage 和其他消息服务。渠道的作用是把外部消息送入 Gateway，并把助手输出投递回对应服务；渠道令牌、账号授权和具体配置字段不在所给资料中完整列出，不能据此虚构统一配置格式。

具备直接消息能力的渠道默认会对未知发送者执行配对（Pairing）流程。收到配对请求后，操作者需要使用 openclaw pairing approve <channel> <code> 明确批准对应渠道和代码，未知消息不会因为网络连通而自动获得操作权限。

模型提供商与本地模型

项目支持托管模型和本地模型提供商。模型访问由 onboarding 流程验证并写入相关配置；资料中明确提到 Docker 环境下的本地模型提供商可以通过 host.docker.internal 访问宿主机侧的 LM Studio 或 Ollama，但没有提供完整的模型字段、认证接口或提供商清单。

因此，模型接入的最小前置条件是：选择受支持的模型提供商，准备其访问凭据或本地服务，并通过 onboarding 完成验证。具体认证方式、模型名称和环境变量应以官方模型文档为准。

工具、技能、插件与设备节点

工具是助手执行外部动作的能力单元，技能用于组织可复用能力，插件通过插件 SDK（Plugin SDK）扩展系统。README 将新能力推荐放入插件，并通过 ClawHub 分享；这意味着扩展点位于项目的插件体系，而不是要求直接修改核心 Gateway。

伴侣应用和节点（Nodes）可以增加语音、Canvas、相机、屏幕和设备本地动作，但这些能力取决于受支持的平台和已安装的节点组件。资料未给出每个节点的权限模型、设备清单或调用接口签名，实施前应以平台和节点文档核对。

系统架构与关键模块

从 README、Docker Compose 和包描述可以确认，OpenClaw 采用“Gateway 居中、多个客户端和扩展围绕它连接”的架构。该结构将消息接入、模型访问、工具调用与设备能力放到同一控制面中，便于统一管理状态和认证。

• Gateway：本地控制平面，承载会话、工具、事件与渠道连接。
• Control UI：浏览器控制界面，启动后可通过 openclaw dashboard 打开。
• CLI：命令行入口，对应 npm 包在 bin 字段中注册为 openclaw，入口文件为 openclaw.mjs。
• TUI：终端用户界面，用于连接 Gateway 并进行终端交互。
• Channels：消息服务连接器，处理外部渠道的收发。
• Models：托管或本地模型提供商，向助手提供生成能力。
• Tools、Skills、Plugins：扩展助手行为、动作和集成能力。
• Companion Apps and Nodes：向设备侧提供语音、Canvas、相机、屏幕或本地动作。

Docker 部署将 Gateway 与 CLI 分成两个 Compose 服务：openclaw-gateway 负责长期运行并执行健康检查，openclaw-cli 使用 network_mode: "service:openclaw-gateway" 与 Gateway 共享网络命名空间。两者共享配置目录、工作区目录和认证配置目录，但 CLI 依赖 Gateway 服务先启动。

依赖与运行环境

发布包要求 Node.js 版本为 22.22.3+、24.15+ 或 25.9+，这是 README 给出的 npm 安装条件。仓库本身是 pnpm 工作区（pnpm workspace），README 明确指出仓库根目录不支持直接执行 npm install。

Dockerfile 使用 Node.js 24 Bookworm 构建阶段和 Node.js 24 Bookworm Slim 运行阶段，并使用 Bun 1.3.14 镜像中的 Bun 二进制参与构建流程。Dockerfile 还通过 SHA256 摘要固定基础镜像；这属于仓库构建文件中的实现细节，不等同于项目对所有安装方式的统一运行时要求。

快速开始

快速开始的最小闭环是安装 CLI、运行 onboarding、检查 Gateway 状态，再打开控制界面。onboarding 会验证模型访问、创建工作区并配置 Gateway；模型凭据和渠道设置仍需由操作者按实际提供商完成。

安装、运行、验证

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# 完成引导并安装后台守护进程
openclaw onboard --install-daemon

# 验证 Gateway 状态
openclaw gateway status

# 打开 Control UI
openclaw dashboard

上面的安装脚本来自 README，覆盖 macOS、Linux 和 WSL2。Windows PowerShell 使用仓库提供的安装脚本；如果已有符合要求的 Node.js，也可以改用 npm 安装路径。安装脚本本身会在需要时配置受支持的 Node.js 运行时，但资料没有给出脚本的内部步骤。

# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

如果使用已有 Node.js 环境，可以执行以下命令。命令中的 latest 是 README 给出的发布包标签，不代表本文声明了未来版本号；安装后应以实际输出为准。

npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

如果 onboarding 要求模型认证，凭据应填写在受支持的认证流程或配置位置中，不要把真实密钥提交到 Git。所给资料未提供某个具体模型提供商的 API 字段，因此本文不写入虚构的环境变量名称。

从源码构建

源码开发需要先克隆仓库，再使用 pnpm 安装依赖并执行构建。README 明确给出的构建命令还包括 UI 构建；根目录不应替换为 npm install。

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build

配置说明

配置主要围绕状态目录、工作区、Gateway 认证、端口和容器网络展开。下面的字段均来自 docker-compose.yml 或 .env.example；“默认值”只记录资料明确写出的默认表达式，不把未提供的实际运行时值补写为猜测。

.env.example 说明环境变量来源优先级为：进程环境、当前目录的 ./.env、~/.openclaw/.env，再到 openclaw.json 的 env 块。直接配置键，例如 gateway.auth.token 或渠道令牌，单独解析，且经常优先于环境变量回退值；具体字段仍应以配置文档为准。

进阶用法

进阶使用的重点是扩展和部署边界，而不是把所有能力默认打开。项目资料提供了插件、平台节点、Docker、Nix、CLI 和开发渠道等入口，但没有给出每个插件的完整参数，因此扩展时应先确认插件来源、依赖和权限。

插件扩展

插件可以通过插件 SDK 构建，并通过 ClawHub 共享。Dockerfile 允许使用构建参数 OPENCLAW_EXTENSIONS 选择可选插件依赖，值可以是以空格或逗号分隔的 ID；这一步发生在镜像构建阶段，不是运行时动态下载。

# 选择 diagnostics-otel 和 matrix 扩展
docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel,matrix" .

该示例直接取自 Dockerfile 注释中的用法。是否适合启用某个扩展，取决于它的依赖、原生模块和数据访问范围；资料没有提供扩展逐项的安全审计结果，不能把“可构建”理解为“已完成业务合规评估”。

容器化运行

Compose 提供 Gateway 和 CLI 两个服务，并把主机配置、工作区及认证配置目录挂载到容器。Gateway 服务使用 restart: unless-stopped、健康检查、no-new-privileges:true，并丢弃 NET_RAW 与 NET_ADMIN 能力；这些是仓库示例中的容器运行设置。

docker compose build
docker compose up -d openclaw-gateway
docker compose run --rm openclaw-cli gateway status

资料只明确给出 Compose 服务和其入口配置，未提供完整的首次容器 onboarding 流程。实际部署前应确认卷目录权限、Gateway 令牌、模型访问凭据和需要暴露的端口，避免直接把示例配置视为生产配置。

可观测性与运维

仓库资料显示，Gateway 有独立健康检查，Compose 的检查命令是 node dist/docker-healthcheck.js，检查间隔为 30 秒、超时为 5 秒、重试次数为 5、启动宽限期为 20 秒。这个配置适合用于容器编排层判断进程是否处于可用状态，但资料没有定义健康检查的全部判定条件。

Docker Compose 同时预留了 OpenTelemetry（OpenTelemetry）导出环境变量，包括 OTLP/HTTP 端点、Trace、Metric、Log 端点、协议、服务名和语义约定稳定性选项。Prometheus 的说明指向已有认证 Gateway 路由，资料没有给出完整抓取 URL、指标名称或认证接口，不能在此补写。

生产运维中应保存配置和工作区卷的备份，记录实际使用的包版本和镜像摘要，并在更新前验证模型认证、渠道配对和插件兼容性。根据本文作者的经验判断，Gateway、渠道凭据和插件状态集中在同一控制面后，备份与变更审查应被视为同一项运维工作，而不宜只备份容器镜像。

安全与合规边界

OpenClaw 会处理消息、模型输入、工具调用和设备动作，因此安全边界首先取决于谁能向 Gateway 发送消息，以及工具在什么主机权限下执行。README 明确要求把入站消息视为不可信输入，并建议在连接其他用户或远程暴露 Gateway 前阅读安全、暴露面和沙箱文档。

消息来源与配对

具备 DM 能力的渠道默认对未知发送者进行配对。只有操作者使用 openclaw pairing approve <channel> <code> 批准后，配对请求才会被接受；渠道名称和代码必须来自实际运行中的配对流程，本文不虚构具体渠道值。

工具执行与沙箱

在主会话中，工具默认运行在宿主机上，除非配置了沙箱（Sandboxing）。这意味着工具调用不应被当作纯文本生成：它可能接触工作区、主机文件或其他本地资源，具体权限取决于启用的工具和沙箱配置。

Docker Compose 中的沙箱卷挂载被注释掉，注释说明它依赖镜像中的 Docker CLI 或脚本配置，并涉及 Docker socket 和 DOCKER_GID。Docker socket 会扩大容器控制宿主机的边界，是否启用必须基于明确的授权、隔离和审计要求决定，本文不提供面向未授权目标的操作方法。

隐私、授权与合规

• 只连接由操作者拥有或获得明确授权的消息账号、模型账号、设备和工作区。
• 不要把真实 API 密钥、渠道令牌、会话密钥或 Cookie 提交到 Git；.env.example 明确要求真实秘密信息不要进入 Git。
• 将消息内容、会话状态、模型输入输出和设备采集能力纳入隐私影响评估。
• 对远程暴露 Gateway 设置认证和网络访问控制，不能只依赖端口映射。
• 在启用相机、屏幕、语音和主机工具前，单独确认操作系统权限、组织政策和适用法律。

资料未提供数据保留周期、加密算法、审计日志覆盖范围、渗透测试结论、漏洞响应时限或 SLA。上述项目不应被宣传为已满足某一特定行业合规认证；需要满足监管、合同或组织安全要求时，应由部署方完成独立评估。

许可证与商用条款

仓库 LICENSE 文件明确为 MIT License，版权声明为 Copyright (c) 2026 OpenClaw Foundation。MIT 条款授予获得软件者使用、复制、修改、合并、发布、再许可和销售副本的许可，但前提是软件副本或实质性部分保留版权声明和许可声明。

该许可证文本允许商业使用，且要求分发时保留相应版权与许可条款。软件按“原样”提供，不提供适销性、特定用途适用性和不侵权保证，作者对许可文本列出的损害责任作了排除；实际分发还应同时检查 THIRD_PARTY_NOTICES.md，因为仓库说明其中记录了纳入或改编代码的第三方声明。

GitHub 仓库元信息显示许可证为 NOASSERTION，但 package.json 和实际 LICENSE 均为 MIT。本文按 LICENSE 解释许可范围；若发布版本或第三方依赖另有条款，应以对应文件和具体版本材料为准。

局限性与已知限制

所给资料足以说明安装、架构和若干部署边界，但没有提供性能基准、并发上限、资源消耗、可用性承诺或完整渠道兼容矩阵。任何关于吞吐量、延迟、最大会话数或生产规模的结论都超出资料范围，官方仓库未提供该信息，建议以最新 README 和官方文档为准。

• 不同模型提供商的认证字段、模型清单和能力差异未在给定资料中完整说明。
• 不同消息渠道的具体授权流程、限流行为和消息格式未在给定资料中完整说明。
• 节点对相机、屏幕、语音和本地动作的权限细节未在给定资料中完整说明。
• 插件的安全审计、维护状态、版本兼容关系和依赖许可未在给定资料中逐项说明。
• Dockerfile 对跨架构构建中的 A2UI bundle 提供了非致命 stub 路径，这表示该构建场景存在明确的构建差异，不能把生成 stub 的镜像等同于完整 A2UI 构建结果。
• 仓库使用 pnpm 工作区，根目录不支持普通的 npm install，源码贡献者需要遵循项目指定的开发流程。

适合谁

是否采用该项目，应以运行边界、模型来源和消息渠道要求判断，而不应只看仓库热度。以下信号来自项目提供的架构与部署方式，具体成本和性能仍需在目标环境中验证。

• 需要在个人设备或自有服务器运行 Gateway，并希望从 WhatsApp、Telegram、Slack、Discord 等已有聊天渠道访问助手。
• 已经能够管理模型提供商凭据，或已经在本地运行 README 和 Compose 提到的 LM Studio、Ollama，并愿意完成 onboarding。
• 需要通过 CLI、Control UI 或 TUI 管理同一个本地控制平面，而不是分别维护多个聊天机器人进程。
• 需要以插件 SDK 扩展工具和集成，并能审查插件依赖、权限和第三方声明。
• 能够承担 Gateway 认证、消息配对、工作区备份、主机工具隔离和容器运维责任。

不适合谁

以下情况说明部署方的前置条件与项目默认边界不匹配。此时不应通过关闭安全控制或扩大权限来弥补设计不匹配，应选择经过组织评估的替代部署方式或重新定义需求。

• 要求服务天然面向大量未知用户开放，而不愿执行 DM 配对、Gateway 认证和入站消息审查。
• 要求项目提供已验证的并发上限、SLA、合规认证或固定的数据保留承诺，但当前资料没有这些信息。
• 不能接受工具默认在主会话宿主机上运行，也无法为工具配置沙箱和最小权限边界。
• 需要完整、稳定且已在目标平台验证的相机、屏幕、语音或设备动作能力，但没有条件核对平台节点文档。
• 团队不使用 Node.js 与 pnpm，且希望直接在仓库根目录执行 npm install 完成源码开发。

常见问题与排查（FAQ / Troubleshooting）

排查顺序应先确认运行时、Gateway 状态和模型访问，再检查渠道配对、工具权限与容器卷。不要在未确认授权和安全边界前，把 Gateway 绑定到更大的网络范围。

安装后找不到或无法启动 Gateway，怎么办

先执行 openclaw gateway status，确认 onboarding 是否完成以及守护进程是否已安装。若使用 npm 安装，先核对 Node.js 是否满足 README 给出的 22.22.3+、24.15+ 或 25.9+ 条件；资料未提供具体错误码和日志路径，遇到错误时应参考官方安装与故障排查文档。

Control UI 能打开但助手没有回复，怎么办

重新检查 onboarding 是否验证了模型访问，以及模型提供商的凭据是否有效。Gateway 状态正常只说明网关进程或健康检查达到相应条件，不代表某个模型账号、消息渠道或插件已经配置成功。

未知发送者的消息没有被处理，怎么办

这是 README 描述的默认配对行为。查看实际渠道产生的配对代码，并在获得授权的前提下执行 openclaw pairing approve <channel> <code>；不要批准无法确认身份或用途的请求。

Docker 中出现宿主机路径权限错误，怎么办

检查 Compose 是否使用容器内固定的 OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR。仓库注释明确说明，这些设置用于避免宿主机写入的环境变量路径泄漏到容器代码；同时检查挂载源目录的权限和实际环境变量文件。

源码安装为什么不能用 npm install

因为 README 明确将仓库定义为 pnpm 工作区，并声明根目录不支持普通 npm install。源码路径应使用 pnpm install、pnpm build 和 pnpm ui:build，贡献流程则参考仓库的 CONTRIBUTING.md。

是否有性能或并发基准

所给仓库资料没有提供 Benchmark、并发上限、延迟分位数、资源规格或 SLA。官方仓库未提供该信息，建议以目标模型、渠道、插件和部署拓扑为条件自行测试，并记录测试版本与配置。

项目地址与资源

以下链接均来自仓库资料或 README 中列出的项目资源，适合用于核对最新安装、配置和安全信息。

• OpenClaw GitHub 仓库
• OpenClaw 官方网站
• OpenClaw 官方文档
• Getting Started 指南
• 安装指南
• Gateway 安全指南
• Gateway 暴露面运行手册
• 沙箱指南
• 架构文档
• 消息渠道文档
• 插件文档
• 插件 SDK 构建指南
• ClawHub 插件共享站点
• OpenClaw Foundation
• OpenClaw DeepWiki 页面
• OpenClaw Discord 社区