Skip to content

yuenkang/openclaw-java

BranchesTags

Repository files navigation

OpenClaw Java

OpenClaw 的 Java 全栈实现 —— 基于 Spring Boot 3.3 的 AI Agent Gateway，通过 WebSocket 自定义帧协议（req/res/event）提供全功能 Agent 接口。

当前进度: Phase 51 / 15 模块 / ~108k 行 Java 代码

📊 Java vs TypeScript 进度对比

💬 加入 Telegram 讨论群组 — 欢迎讨论关于项目的一切！

🗣️ GitHub Issues 灌水区 — 有问题欢迎提问 👏

Telegram 群组二维码

架构

┌────────────────────────────────────────────────────────────────────┐
│                           openclaw-app                              │
│          (Spring Boot 入口 + 模块桥接 + OpenAI 兼容 REST API)      │
├──────────┬──────────┬──────────┬──────────┬────────────────────────┤
│ gateway  │  agent   │ channel  │  plugin  │       autoreply        │
│ WebSocket│ Runtime  │ Adapters │   SPI    │     Auto-Reply         │
│ RPC Route│ LLM Loop │ Telegram │  Loader  │     Commands           │
│ Session  │  Tools   │  WeChat  │ Registry │     Dispatch           │
│ Cron     │  Skills  │ Discord  │          │                        │
│ Outbound │          │ Outbound │          │                        │
├──────────┼──────────┼──────────┼──────────┼────────────────────────┤
│  node    │ browser  │  media   │  hooks   │  sandbox · memory ·    │
│ Registry │ Client   │ Format   │ Engine   │  providers             │
│ Pairing  │ Profiles │ Runner   │ Config   │                        │
│ Device   │ Session  │ Apply    │ Install  │                        │
├──────────┴──────────┴──────────┴──────────┴────────────────────────┤
│                            common                                  │
│    Config · Models · Protocol · Sessions · Auth · Security · Infra │
└────────────────────────────────────────────────────────────────────┘

模块说明

模块 说明
openclaw-common 配置管理 (90+ 嵌套类型)、日志脱敏、安全审计、Markdown IR 解析/渲染、基础设施 (infra 16 模块)
openclaw-node 节点注册/配对/设备管理 (NodeConnection 接口解耦 gateway)
openclaw-gateway WebSocket 服务器、会话管理、方法路由、Cron 调度、出站消息投递、运行时重载、OpenAI 兼容 HTTP
openclaw-media 媒体理解框架：scope/format/resolve/provider/runner/apply
openclaw-sandbox 沙箱执行 (Docker)：配置解析/工具策略/运行时状态/清理
openclaw-memory 记忆索引、关键字搜索、后端配置
openclaw-providers 认证工具：GitHub Copilot OAuth、通义千问 Portal OAuth
openclaw-hooks Hooks 引擎/配置/安装/Frontmatter/SoulEvil
openclaw-browser 浏览器控制基础设施：Client/Profiles/Session/ControlServer
openclaw-plugin 插件加载/激活/注册完整链、钩子执行器 (14 种)、命令处理器、工具解析、服务管理 — 📖 plugin-guide.md
openclaw-agent Agent 执行引擎、多模型提供者 (Anthropic/OpenAI/Ollama)、内置工具 (Exec/File/Browser/Image)、指令处理、Skills
openclaw-autoreply 自动回复：命令检测/派发/回复队列/模板/心跳/状态 (120 文件)
openclaw-channel Telegram Bot (18+ 文件) + 微信公众号 (8 文件) + Discord 适配器
openclaw-app Spring Boot 入口、命令系统 (15 个命令模块)、模块桥接、OpenAI 兼容 REST API

总计: 15 模块，~700+ 个 Java 源文件 (~108k 行)

快速开始

环境要求

  • Java 17+
  • Maven 3.8+

构建

mvn clean install

运行

# 设置 API Key
export ANTHROPIC_API_KEY=your-key-here

# 可选：自定义 API 地址（代理、自建网关等）
export ANTHROPIC_BASE_URL=https://your-proxy.example.com/v1

# 启动
mvn spring-boot:run -pl openclaw-app

服务启动在 ws://127.0.0.1:18789

环境变量

变量 说明 默认值
ANTHROPIC_API_KEY Anthropic API 密钥 —
ANTHROPIC_BASE_URL Anthropic API 地址 https://api.anthropic.com/v1
OPENAI_API_KEY OpenAI API 密钥 —
OPENAI_BASE_URL OpenAI API 地址 https://api.openai.com/v1
OLLAMA_BASE_URL Ollama 本地服务地址 http://127.0.0.1:11434/v1
TELEGRAM_BOT_TOKEN Telegram Bot Token —
WECHAT_APP_ID 微信公众号 AppID —
WECHAT_APP_SECRET 微信公众号 AppSecret —
WECHAT_TOKEN 微信公众号验证 Token —

测试

mvn test

WebSocket 协议

采用自定义帧协议（与 TypeScript 版本对齐），非 JSON-RPC。支持三步握手、双向通信和事件推送。

类型 格式 说明
Request {"type":"req", "id":"1", "method":"...", "params":{}} 客户端→服务端请求
Response {"type":"res", "id":"1", "ok":true, "payload":{}} 服务端→客户端响应
Event {"type":"event", "event":"...", "payload":{}} 服务端→客户端事件推送

📖 完整协议文档：websocket-protocol.md（握手流程、方法示例、会话管理、Agent 对话、Cron 调度）

📖 TUI 使用指南：tui-guide.md（命令列表、模型切换、会话管理、快捷操作）

核心模块详解

Agent 执行引擎 (openclaw-agent)

  • 多轮对话: 用户->LLM->工具->LLM->...->回复循环
  • 多模态工具返回: 工具可返回图片等多模态内容给 LLM（截图视觉分析等）
  • 模型提供者: Anthropic Claude、OpenAI GPT、Ollama 本地、OpenAI 兼容 (vLLM/DeepSeek 等)；认证工具: GitHub Copilot OAuth、通义千问 Portal OAuth
  • 内置工具: 命令执行 (ExecTool)、文件读写 (FileTools)、浏览器控制 (BrowserTool)、图片分析 (ImageTool)
  • Skills 系统: 可扩展技能加载/过滤/注入、frontmatter 解析、环境变量覆盖、热重载 — 📖 skills-guide.md
  • Plugin 系统: 插件工具/钩子/命令注入 Agent、热加载、classloader 隔离 — 📖 plugin-guide.md
  • 指令处理: 快速回复、队列验证、Follow-up
  • Hooks 系统: 内置 Hook (boot-md/command-logger/session-memory)、Workspace Hook 加载、优先级管理
  • Memory 系统: 记忆索引、关键字搜索、后端配置
  • Reasoning: 支持 reasoning_content 流式/非流式解析 (Claude extended thinking)

命令系统 (openclaw-app/commands)

独立的 channel-agnostic 命令系统 (15+ 个命令模块):

  • 会话管理: /clear 清除历史、/usage 用量统计
  • 模型切换: /model 切换模型、/models 分页模型列表 (inline keyboard)
  • 信息查询: /help /status /status all /commands
  • 诊断工具: /doctor 环境诊断 (配置/端口/二进制依赖/更新检查)
  • 访问控制: /allowlist 白名单管理 (addme/removeme/list/add/remove)
  • 配置管理: /config 运行时配置查看/修改 (支持嵌套路径)
  • 高级功能: /bash Shell命令、/subagent 子Agent管理、/tools 工具列表、/tts 语音合成、/plugins 插件列表
  • 操作审批: /approve 危险操作批准、/restart 重启服务

日志 · 安全 · Markdown (openclaw-common) 🆕

  • 日志脱敏 (LogRedact): 16 个内置正则脱敏模式 (API key/token/PEM/Bearer 等)
  • 安全审计 (SecurityAudit): 文件权限、敏感变量、root 检测、日志目录审计
  • 安全扫描 (SkillScanner): 行级 (exec/eval/ProcessBuilder) + 源码级 (exfiltration) 安全扫描
  • 外部内容安全 (ExternalContentSecurity): 15 个注入检测模式 + XML 边界隔离
  • Markdown IR 管道: 解析 → 中间表示 → 边界排序标记插入 → Telegram HTML / Discord Markdown 渲染
  • 安全修复: /fix 命令 — chmod 修复 + 凭证文件保护

Telegram Bot (openclaw-channel/telegram) ⭐ 推荐

📌 Telegram Bot 是 OpenClaw 最重要、功能最完整的 Channel 连接方式，支持私聊/群聊、图片收发、流式输出、会话管理等全部特性。

📖 部署指南：telegram-bot-setup.md

完整的 Telegram Bot 实现 (18+ 个类):

  • Bot 生命周期管理 (轮询/Webhook)
  • Update 去重 (LRU) + Media-group 合批
  • 访问控制: DM allowlist + 群组策略 (open/disabled/allowlist) + per-group allowFrom override
  • 群组策略: group/topic enabled 检查 → per-group override → groupPolicy → 群组 ID 白名单
  • 配置热加载: 每条消息获取最新配置 (含 runtime overrides)，无需重启
  • 富消息上下文 (sender/chat/media/mentions)
  • 命令系统: 15+ 斜杠命令 + inline keyboard 回调 + callback query 处理
  • Markdown→HTML 管道: IR 级 fence-aware 分块，表格自动检测转换
  • 图片处理 (接收分析 + 发送图片)
  • 草稿消息实时编辑 (Draft Stream)
  • 连接健康监控 + HTTP 代理支持

微信公众号 (openclaw-channel/wechat) ⚠️ 待验证

📖 接入指南：wechat-setup.md

完整的微信公众号接入 (8 个类):

  • Webhook 验证 (SHA-1 签名) + 消息接收
  • access_token 管理 (Caffeine 缓存 110 分钟 TTL)
  • 入站消息路由 (text/image/voice/event)
  • 客服消息 API 出站发送
  • Spring RouterFunction 条件注册

📖 渠道配置总览：channel-configuration.md

浏览器控制 (openclaw-browser)

  • 独立 Netty HTTP 服务器 (端口 18791) -- 与 TypeScript 架构对齐
  • 19 种浏览器操作 (click/type/fill/press/drag/wait/evaluate/download/set_input_files/response_body 等)
  • CDP + Playwright 1.58 双通道架构 -- 截图/快照走 CDP 低延迟通道，交互走 Playwright auto-wait
  • 截图视觉分析 -- 截图自动作为图片发送给 LLM，LLM 可看到页面内容并分析
  • 带标注截图 (/screenshot-labels) -- 给交互元素加编号标注，便于 LLM 定位
  • 快照截断 (/snapshot?maxChars=N) -- 超大页面自动截断
  • 响应体捕获 (/response/body) -- 拦截并返回匹配 URL 的请求响应体
  • 文件上传/对话框预注册 (arm-upload/arm-dialog) -- 异步事件处理
  • 支持有头/无头模式切换 (headless 参数)
  • HTTP 路由拆分为 6 个独立路由类 (Basic/Snapshot/Tab/Hooks/State/Routes)

📖 浏览器模块指南：browser-guide.md

持久化层

  • 会话历史: JSONL 对话记录 (TranscriptStore) — 追加/读取/清除，Bot 重启自动恢复 50 条上下文
  • 用量追踪: JSONL 用量记录 (UsageTracker) — 多模型成本估算 (Claude/GPT/DeepSeek/Gemini)
  • 会话元数据: sessions.json 原子写入 (SessionPersistence)

出站消息投递 (openclaw-gateway/outbound)

  • 目标解析 (peer/group/channel 路由)
  • Payload 归一化 + 格式化 + 分块
  • 渠道适配注册 + Agent 投递计划

Cron 调度 (openclaw-gateway/cron)

  • Cron 表达式解析 + 下次运行时间计算
  • Job 配置规范化 + 投递目标解析
  • 事件状态持久化

技术栈

  • Spring Boot 3.3 — Web + WebSocket + Scheduling
  • Jackson — JSON 序列化
  • OkHttp — HTTP 客户端（模型 API / 渠道 API）
  • java.net.http.HttpClient — Telegram Bot API
  • Caffeine — 本地缓存
  • Lombok — 代码简化
  • docker-java — 沙箱执行
  • JUnit 5 + Mockito — 测试

配置

默认配置文件路径：~/.openclaw/config.json

{
  "model": "anthropic/claude-sonnet-4-5",
  "modelAliases": {
    "sonnet": "anthropic/claude-sonnet-4-5",
    "gpt4": "openai/gpt-4"
  },
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1"
  },
  "agents": {
    "list": [
      {
        "id": "default",
        "name": "Default Agent",
        "model": "anthropic/claude-sonnet-4-5"
      }
    ]
  },
  "channels": {
    "telegram": {
      "token": "BOT_TOKEN",
      "allowFrom": ["123456789"],
      "dmPolicy": "allowlist"
    },
    "wechat": {
      "appId": "wx...",
      "appSecret": "...",
      "token": "your-verify-token"
    }
  }
}

项目目录结构

openclaw-java/
├── pom.xml                     # 父 POM (Spring Boot 3.3, Java 17)
├── CHANGELOG.md                # 变更日志 (Phase 1-51)
├── README.md                   # 本文件
├── doc/                        # 设计文档 + 学习路线图
│   ├── notes/                  # 16 篇架构学习笔记
│   ├── openclaw_learning_roadmap.md
│   └── walkthrough.md          # 实现进度记录
├── openclaw-common/            # 公共模块
│   └── src/main/java/com/openclaw/common/
│       ├── config/             # OpenClawConfig, ConfigService, 热加载
│       ├── logging/            # 日志脱敏, 子系统日志, 诊断
│       ├── security/           # 安全审计, 注入检测, 内容安全
│       ├── markdown/           # Markdown IR 解析/渲染引擎
│       ├── infra/              # 重试, 事件总线, 运行时守卫
│       ├── models/             # 数据模型
│       └── auth/               # 认证
├── openclaw-node/              # 节点管理模块 [NEW]
│   └── src/main/java/com/openclaw/node/
├── openclaw-gateway/           # Gateway 模块
│   └── src/main/java/com/openclaw/gateway/
├── openclaw-media/             # 媒体理解模块
│   └── src/main/java/com/openclaw/media/
├── openclaw-sandbox/           # 沙箱执行模块
│   └── src/main/java/com/openclaw/sandbox/
├── openclaw-memory/            # 记忆系统模块
│   └── src/main/java/com/openclaw/memory/
├── openclaw-providers/         # 认证提供者模块
│   └── src/main/java/com/openclaw/providers/
├── openclaw-hooks/             # Hooks 模块
│   └── src/main/java/com/openclaw/hooks/
├── openclaw-browser/           # 浏览器控制模块 [NEW]
│   └── src/main/java/com/openclaw/browser/
├── openclaw-plugin/            # 插件模块
│   └── src/main/java/com/openclaw/plugin/
├── openclaw-agent/             # Agent 模块
│   └── src/main/java/com/openclaw/agent/
├── openclaw-autoreply/         # 自动回复模块
│   └── src/main/java/com/openclaw/autoreply/
├── openclaw-channel/           # 渠道模块
│   └── src/main/java/com/openclaw/channel/
└── openclaw-app/               # 启动模块
    └── src/main/java/com/openclaw/app/

开发迭代历程

Phase 内容 文件数
1–3 基础框架 + Gateway + Agent Runtime 24
4–6 渠道适配器 + 插件/Cron + 测试 18
7–12 Agent 高级功能 (指令处理/Follow-up/模型扩展) ~80
13–18 Gateway 扩展 (会话/RPC/聊天/运行时) ~90
19–23 Agent 深度 (工具链/Auth/CLI/系统提示) ~120
24 编译错误全面修复 22
24.5 Media + Memory 基础设施 8
25 Hooks/Plugins/Cron 模块补齐 9
26 Gateway 运行时补全 11
27 Infra 出站消息投递 15
28 Cron + Hooks 补全 6
29 Telegram Bot 完整层 18
30 Channels 桥接层 5
31 微信公众号渠道 8
32 集成测试 + WebSocket 可靠性修复 —
33 浏览器控制 + 图片处理 + 持久化 + 用量追踪 10+
34 infra/ 核心基础设施模块 (重试/安全/事件/运行时) 21
35 Browser Control Netty 独立服务 + 截图多模态 LLM 支持 8
35.1 TUI 修复 (流式/token/模型名/session) + TUI 文档 10
36 日志脱敏 · 安全审计 · Markdown IR · Providers 扩展 34
37 命令系统重构 · 访问控制对齐 · 配置热加载 · 群组策略 25
38–42 Telegram 完善 · WeChat · 端到端测试 · 编译修复 ~30
43 infra/ 补齐 (16 模块: dotenv/binaries/restart 等) 16
43.5 InfraBootstrap 接入主流程 3
44 命令系统深化 (/status /doctor /restart 接入 infra) 4
45 测试覆盖率提升 (9 新测试文件, 612 pass) 9
46 运行时增强与可观测性 (RuntimeMetrics/HealthEndpoint) 7
47–48 Plugin 激活链完整实现 & 死代码清理 ~15
49 模块提取 (browser/node) & 全量包名统一重构 (161+文件) 15
50 Browser & Node 模块功能完善 (78 tests) ~30
51 Browser 双通道架构 + TS 对齐 (Playwright 1.58) ~40

License

MIT

About

OpenClaw 的 Java 全栈实现 — 基于 Spring Boot 的 AI Agent Gateway

Resources

Readme
Activity

Stars

58 stars

Watchers

4 watching

Forks

21 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors 2

Languages