夜雨聆风
概述
如今 AI 智能体已然遍地开花，但绝大多数都基于 Python 或 Node.js 开发。作为 Java 开发者，你或许一直置身局外观望，好奇 Java 生态何时才能迎头赶上。
事实上，JavaClaw 是一款基于 Java 生态构建的本地化个人 AI 智能体平台，其核心定位是：在用户自有硬件上运行，充当多渠道 AI 智能体的控制平面（Control Plane）。它不仅是一个对话机器人，更是一个具备任务调度、工具调用、多渠道接入、记忆管理能力的全功能智能体运行时。
从官方的描述来看，JavaClaw 最初作为 JobRunr 的演示项目诞生，但已发展成为面向 Java 社区的开放式 AI 智能体基础框架，致力于让开发者能以 Java 为母语构建下一代 AI 智能体系统。
项目口号： "让数据留在本地，让能力延伸到无限。"
核心优势
隐私优先的本地化设计
与大多数 AI 助手依赖云端服务不同，JavaClaw 完全在用户本地运行。对话记忆以 YAML 文件形式落盘，任务以 Markdown 文件形式存储，无需外部数据库，所有敏感数据均不出本机（除非用户主动配置 OpenAI/Anthropic 等外部 LLM）。
深度拥抱 Java 生态
JavaClaw 选用当下最先进的 Java 技术栈：Java 25、Spring Boot 4.0.3、Spring AI 2.0.0，完全依托 JVM 生态，无需 Python 环境，开发者可用熟悉的 Spring 开发范式扩展智能体能力。
多 LLM 后端可插拔
通过 Spring AI 的抽象层，JavaClaw 可无缝切换 OpenAI、Anthropic Claude 或本地 Ollama 模型，不需要修改业务代码，只需在 application.yaml 中更换配置项即可。
多渠道统一接入
支持 Web Chat（WebSocket）、Telegram、Discord 三种开箱即用的通信渠道，所有渠道共享同一个智能体内核和对话记忆，用户可以从 Telegram 发起任务，在 Discord 查看进度，体验真正的全渠道智能体。
运行时可扩展的 Skills 机制
通过在 workspace/skills/ 目录下投放 SKILL.md 文件，智能体在无需重启、无需修改代码的情况下即可习得新技能，这是 JavaClaw 最具差异化的能力之一。
企业级后台任务调度
基于 JobRunr 提供一次性、延迟、Cron 周期性三种任务调度模式，并内置可视化 Dashboard（:8081），任务状态实时可查，具备生产级可靠性。
MCP 协议支持
完整实现了 Model Context Protocol（MCP）客户端，支持 stdio 和 streamable-HTTP 两种模式，可无缝接入任何标准 MCP 工具服务器，大幅扩展工具调用能力边界。
架构
整体架构总览
JavaClaw 采用模块化单体（Modular Monolith）架构，借助 Spring Modulith 对模块边界进行约束，在保留单体部署便利性的同时，实现模块间的低耦合。
模块结构划分
Spring Modulith 内部模块边界
技术栈
Agent 运行原理
核心抽象：Agent 接口
Agent 接口是整个智能体的行为契约，定义了两种基本能力：
publicinterfaceAgent {// 自然语言对话：给定会话ID和用户问题，返回智能体回复 String respondTo(String conversationId, String question);// 结构化输出：给定会话ID和提示词，将回复解析为指定Java类型 <T> T prompt(String conversationId, String input, Class<T> result);}DefaultAgent 是其唯一实现，核心逻辑极为简洁——将调用完全委托给 Spring AI 的 ChatClient，真正的复杂性被封装在 Advisor 链中。
ChatClient 的构建与装配
JavaClawConfiguration 是整个系统的"大脑装配车间"，它在应用启动时构建出一个功能完备的 ChatClient：
@Bean@DependsOn({"mcpHeaderCustomizer"})public ChatClient chatClient( ChatClient.Builder chatClientBuilder, ChatMemory chatMemory, ObjectProvider<ToolSearchToolCallAdvisor> toolSearchAdvisorProvider, SyncMcpToolCallbackProvider mcpToolProvider, TaskManager taskManager, ConfigurationManager configurationManager,@Value("${agent.workspace:Unknown}") Resource workspace, Set<AutoDiscoveredTool<?>> autoDiscoveredTools)throws IOException {// 1. 加载系统提示词（AGENT.md + INFO.md）StringagentPrompt= agentMd.getContentAsString(UTF_8) + infoMd.getContentAsString(UTF_8);// 2. 决定工具调用模式：动态发现 or 全量暴露ToolCallAdvisortoolCallAdvisor= toolSearchAdvisorProvider.getIfAvailable(ToolCallAdvisor.builder()::build);// 3. 注册所有内置工具 chatClientBuilder .defaultSystem(p -> p.text(agentPrompt) .param(ENVIRONMENT_INFO_KEY, AgentEnvironment.info())) .defaultToolCallbacks(mcpToolProvider.getToolCallbacks()) .defaultToolCallbacks(SkillsTool.builder() .addSkillsDirectory(skillsDir(workspace)).build()) .defaultTools( TaskTool.builder().taskManager(taskManager).build(), CheckListTool.builder().build(), McpTool.builder().configurationManager(configurationManager).build(), FileSystemTools.builder().build(), SmartWebFetchTool.builder(chatClientBuilder.clone().build()).build()) .defaultAdvisors(newSimpleLoggerAdvisor(), toolCallAdvisor, // 工具调用 MessageChatMemoryAdvisor.builder(chatMemory).build()); // 记忆注入// 4. 自动发现并注册插件工具 autoDiscoveredTools.forEach(t -> chatClientBuilder.defaultTools(t.tool()));return chatClientBuilder.build();}完整的消息处理流程
Advisor 链的执行顺序与职责
JavaClaw 的 Advisor 链按以下顺序执行，每个 Advisor 都可以在请求到达 LLM 前后进行拦截和增强：
动态工具发现机制
当 javaclaw.tools.dynamic-discovery.enabled=true 时，系统启用工具搜索模式（Tool Search Pattern）：
配置示例：
javaclaw:tools:dynamic-discovery:enabled:truemax-results:8# 最多注入 8 个工具lucene-min-score-threshold:0.25# 相关性最低分阈值后台任务执行流程
后台任务是 JavaClaw 区别于普通聊天机器人的核心特性。任务的创建和执行形成了一个完整的异步闭环：
对话记忆的持久化策略
JavaClaw 采用基于文件系统的对话记忆，对话历史存储为 YAML 文件，支持跨进程重启的记忆持久化：
Skills扩展
JavaClaw 提供了三种层次的扩展方式，从零代码到完整插件，覆盖不同的扩展场景。
扩展方式一：零代码 SKILL.md 技能文件
这是最轻量的扩展方式，无需修改任何代码，无需重启服务，适合快速为 Agent 添加新的知识、流程或行为规范。
工作原理：
SkillsTool 在每次被 LLM 调用时，动态扫描 workspace/skills/ 目录，将所有 SKILL.md 文件的内容作为上下文注入 Agent。
示例：创建一个"每日周报"技能
在 workspace/skills/daily-report/SKILL.md 中写入：
# Daily Report Skill你可以帮助用户生成每日工作总结报告。## 使用场景当用户要求"生成今日报告"、"写工作总结"时，触发此技能。## 报告格式1.**今日完成工作**：列出当天已完成的任务2.**进行中的工作**：当前仍在处理的任务3.**明日计划**：下一个工作日的计划4.**遇到的问题**：任何阻塞项或需要协助的事项报告语言：中文，语气专业简洁。文件放入目录后，Agent 立即具备生成标准化报告的能力，无需任何重启。
扩展方式二：实现 AutoDiscoveredTool 插件工具
当需要实现有状态的工具或调用外部 API 时，通过 Java 代码实现工具类，并注册为 AutoDiscoveredTool Bean，框架会在启动时自动发现并将其注入 ChatClient。
扩展步骤：
第一步：定义工具类
package com.example.tools;import org.springframework.ai.tool.annotation.Tool;import org.springframework.stereotype.Component;/** * 自定义天气查询工具示例 */@ComponentpublicclassWeatherTool {privatefinal WeatherApiClient weatherApiClient;publicWeatherTool(WeatherApiClient weatherApiClient) {this.weatherApiClient = weatherApiClient; }@Tool(name = "getWeather", description = "根据城市名称查询当前天气情况。返回温度、天气状况和湿度信息。")public String getWeather(String city) {try {WeatherDatadata= weatherApiClient.fetchWeather(city);return String.format("城市：%s，温度：%s°C，天气：%s，湿度：%s%%", city, data.temperature(), data.condition(), data.humidity() ); } catch (Exception e) {return"无法获取 " + city + " 的天气信息：" + e.getMessage(); } }@Tool(name = "getWeatherForecast", description = "获取指定城市未来 N 天的天气预报，N 最大为 7。")public String getWeatherForecast(String city, int days) {// 实现天气预报逻辑...return weatherApiClient.fetchForecast(city, Math.min(days, 7)).toString(); }}第二步：注册为 AutoDiscoveredTool
package com.example.config;import ai.javaclaw.tools.AutoDiscoveredTool;import com.example.tools.WeatherTool;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;@ConfigurationpublicclassWeatherToolConfiguration {/** * 将 WeatherTool 包装为 AutoDiscoveredTool， * JavaClawConfiguration 会自动发现并注册它。 */@Beanpublic AutoDiscoveredTool<WeatherTool> weatherAutoDiscoveredTool(WeatherTool weatherTool) {returnnewAutoDiscoveredTool<>(weatherTool); }}框架自动发现机制（源码）：
在 JavaClawConfiguration.chatClient() 方法中，框架通过如下方式自动注册所有 AutoDiscoveredTool：
// 自动将所有 AutoDiscoveredTool Bean 注册到 ChatClientautoDiscoveredTools.forEach(autoDiscoveredTool -> chatClientBuilder.defaultTools(autoDiscoveredTool.tool()));扩展方式三：实现完整的 Channel 渠道插件
当需要接入新的消息渠道（如企业微信、飞书、SMS 等）时，实现 Channel 接口并将其注册到 ChannelRegistry。
扩展步骤：
第一步：实现 Channel 接口
package com.example.channels;import ai.javaclaw.channels.Channel;import ai.javaclaw.channels.ChannelRegistry;import ai.javaclaw.channels.ChannelMessageReceivedEvent;import ai.javaclaw.agent.Agent;import org.springframework.stereotype.Component;/** * 企业微信渠道插件示例 */@ComponentpublicclassWeChatWorkChannelimplementsChannel {privatestaticfinalStringCONVERSATION_ID="wechat-work-channel";privatefinal Agent agent;privatefinal ChannelRegistry channelRegistry;privatefinal WeChatWorkClient weChatClient;publicWeChatWorkChannel(Agent agent, ChannelRegistry channelRegistry, WeChatWorkClient weChatClient) {this.agent = agent;this.channelRegistry = channelRegistry;this.weChatClient = weChatClient;// 注册自身到渠道注册中心 channelRegistry.registerChannel(this);// 启动消息接收监听 startMessageListener(); }@Overridepublic String getName() {return"WeChatWorkChannel"; }@OverridepublicvoidsendMessage(String message) {// 通过企业微信 API 发送消息 weChatClient.sendTextMessage(message); }privatevoidstartMessageListener() {// 企业微信消息回调处理 weChatClient.onMessageReceived(event -> {StringuserId= event.getUserId();Stringcontent= event.getContent();// 通知 ChannelRegistry 当前活跃渠道 channelRegistry.publishMessageReceivedEvent(newChannelMessageReceivedEvent(this.getName()) );// 转发给 Agent 处理，使用 userId 作为会话ID以隔离对话记忆Stringresponse= agent.respondTo(userId, content);// 回复用户 sendMessage(response); }); }}第二步：添加 Onboarding 步骤（可选）
实现 OnboardingProvider 接口，在引导流程中为用户提供渠道配置 UI：
package com.example.channels;import ai.javaclaw.onboarding.OnboardingProvider;import ai.javaclaw.configuration.ConfigurationManager;import org.springframework.stereotype.Component;import java.util.Map;@ConfigurationpublicclassWeChatWorkOnboardingProviderimplementsOnboardingProvider {privatefinal ConfigurationManager configurationManager;publicWeChatWorkOnboardingProvider(ConfigurationManager configurationManager) {this.configurationManager = configurationManager; }@Overridepublic String getStepId() {return"wechat-work"; }@Overridepublic String getTitle() {return"企业微信配置"; }@OverridepublicbooleanisCompleted() {// 检查配置是否已完成return configurationManager.hasProperty("agent.channels.wechat-work.corp-id"); }publicvoidsaveConfig(String corpId, String agentId, String secret) { configurationManager.updateProperties(Map.of("agent.channels.wechat-work.corp-id", corpId,"agent.channels.wechat-work.agent-id", agentId,"agent.channels.wechat-work.secret", secret )); }}三种扩展方式对比
MCP 服务器动态注册
JavaClaw 支持在运行时通过 McpTool 注册新的 MCP 服务器，这一操作可以直接通过自然语言对话触发：
// 用户对话示例：// "帮我添加一个 MCP 服务器，地址是 http://localhost:8000/mcp，名字叫 my-tools"// Agent 自动调用 McpTool.addStreamableHttpMcpServer()@Tool(description = "添加新的 streamable-HTTP MCP 服务器到应用配置中")public String addStreamableHttpMcpServer(String name, String url, String headers) {// 持久化到 application.private.yaml configurationManager.updateProperties(Map.of("spring.ai.mcp.client.streamable-http.connections." + name + ".url", url ));return"MCP 服务器已添加，重启后生效";}总结
JavaClaw 以其"本地优先、Java 原生、极简扩展"的设计哲学，为 Java 开发者提供了一个生产级的 AI 智能体运行时平台。
在架构层面，它借助 Spring Modulith 实现模块化约束，以 Spring AI 的 ChatClient 和 Advisor 模式为核心，将记忆管理、工具调用、日志追踪等横切关注点优雅地解耦；在智能体运行层面，Advisor 链的洋葱式执行模型和动态工具发现机制使得 Agent 既高效又灵活；在可扩展性层面，从零代码的 SKILL.md 到插件式的 AutoDiscoveredTool，再到渠道级别的 Channel 扩展，形成了层次清晰、门槛渐进的完整扩展体系。
对于 Java 团队而言，JavaClaw 提供的不仅是一个可直接使用的个人助手，更是一套可以作为企业级 AI 智能体平台基础的参考架构，值得深入研究与实践。
