OpenClaw 项目整体架构说明

1. 项目整体定位

• 接入多种消息渠道（Telegram/Slack/Discord/Signal/iMessage/WhatsApp Web 等）

• 统一通过 Gateway 对外提供实时通信与管理能力

• 用插件机制扩展渠道、工具、服务与接口

• 同时支持 CLI、Web 控制台、iOS/macOS/Android 客户端

2. 顶层模块划分（按目录）

2.1 启动与命令入口层

• openclaw.mjs：CLI 可执行入口

• src/entry.ts：运行时初始化 + 主入口桥接

• src/cli/：命令行框架（参数、路由、子命令注册）

• src/commands/：各业务命令实现（agent/status/health/gateway 等）

2.2 网关服务层（后端核心）

• src/gateway/server.ts：网关启动导出

• src/gateway/server.impl.ts：网关装配中枢（配置、插件、通道、HTTP/WS、心跳、发现）

• src/gateway/server-http.ts：HTTP 入口（Control UI、OpenAI 兼容接口、hooks、plugin routes）

• src/gateway/server-methods.ts：RPC 方法聚合处理

• src/gateway/protocol/：网关协议 schema 与校验

2.3 Agent 与模型运行层

• src/agents/：模型认证、模型选择、会话、工具、子代理、沙箱

• src/commands/agent.ts：本地嵌入式 agent 执行入口

• src/commands/agent-via-gateway.ts：通过 gateway RPC 调用 agent

• src/agents/pi-embedded-runner.ts：嵌入式 agent 运行主链路

2.4 渠道与路由层

• src/routing/：绑定规则与会话路由（channel/account/peer -> agent/session）

• src/channels/registry.ts：渠道定义与标准化

• src/channels/plugins/：渠道插件适配规范（配置、onboarding、目录、动作）

• src/telegram/、src/slack/、src/discord/、src/signal/、src/imessage/、src/web/：具体渠道实现

2.5 插件系统层

• src/plugins/discovery.ts：插件发现

• src/plugins/loader.ts：插件加载与注册

• src/plugins/registry.ts：插件注册表（tools/hooks/channels/providers/http/gatewayHandlers）

• src/plugins/runtime.ts：运行时活动插件状态

• src/plugin-sdk/index.ts：插件开发 SDK

• extensions/：扩展插件工作区（渠道、memory、鉴权、诊断等）

2.6 配置与基础设施层

• src/config/：配置读写、校验、迁移、会话配置

• src/infra/：端口、发现、心跳、日志、tailscale、系统能力

• src/daemon/：守护进程安装与管理（systemd/launchd/schtasks）

2.7 前端与客户端层

• ui/：Web Control UI（Vite + Lit）

• apps/ios/：iOS 客户端

• apps/macos/：macOS 客户端（含 menubar 网关管理）

• apps/android/：Android 客户端

• apps/shared/OpenClawKit/：共享协议与客户端基础库

3. 前后端入口与集成方式

3.1 后端启动链

3.2 网关启动链

3.3 前端入口

• Web：ui/src/main.ts

• iOS：apps/ios/Sources/OpenClawApp.swift

• macOS：apps/macos/Sources/OpenClaw/*

3.4 对外接口入口

• WebSocket RPC：Gateway WS（方法来自 server-methods + 插件扩展）

• HTTP API：/v1/chat/completions、/v1/responses

• Hooks/Webhooks：网关 hooks + 插件 HTTP 路由

4. 模块依赖关系（高层）

4.1 命令层依赖

• src/config（读取运行配置）

• src/agents（执行 agent）

• src/gateway（远程调用或启动网关）

• src/plugins（加载插件命令）

4.2 网关层依赖

• src/config（配置）

• src/plugins（插件注册能力）

• src/channels/plugins（渠道插件能力）

• src/gateway/server-methods*（RPC 处理）

• src/infra / src/cron（心跳、发现、定时任务）

4.3 消息流转依赖

4.4 插件扩展依赖

5. 架构设计模式总结

• 插件化扩展：通过统一注册表扩展 channels/tools/hooks/http/gateway methods

• 网关聚合：多端统一走 Gateway 协议，降低客户端差异

• 分层清晰：命令编排与核心执行分离

• 配置驱动：路由、账号、会话策略由配置控制

• 多渠道统一抽象：共性下沉到 src/channels/plugins/*，差异留在渠道实现

6. 关键目录速查

• 核心入口：openclaw.mjs、src/entry.ts

• CLI 框架：src/cli/、src/commands/

• 网关核心：src/gateway/

• Agent 核心：src/agents/

• 渠道路由：src/channels/、src/routing/

• 插件系统：src/plugins/、src/plugin-sdk/、extensions/

• 配置基础设施：src/config/、src/infra/、src/daemon/

• 客户端：ui/、apps/