Gacfox's Blog
MeowClaw - 喵爪智能体

MeowClaw - 喵爪智能体

#AI#Java
类型：开源软件
授权：开源
语言：简体中文
运行环境：Java21
发布时间：2026-05-28

可自托管的单用户通用智能体（Harness）工具。

官方网址
资源截图1

MeowClaw 喵爪智能体

跟风写的（划掉）可自托管的单用户ReAct风格通用智能体工具，开发目的是解决Java里面SpringAI和LangChain4J用着太不顺手问题，作为Demo沉淀出一套AI Agent框架以备后续使用，这也是为何相比其它同类项目用如此非主流的语言开发的原因。。。

核心特性

登录鉴权

MeowClaw是一个单用户系统，管理员用户具备所有操作权限，首次使用时需创建管理员账户，后续也可在后台修改用户名及密码。

智能体

MeowClaw的核心功能是运行ReAct风格的智能体，在智能体管理菜单创建智能体，可配置的信息包括：

  • 智能体名称：给智能体起的名字。
  • 头像：可以上传一个图片显示在智能体对话气泡旁边。
  • 人设：描述智能体该以哪种身份、如何与用户交互，该部分文本会固定注入系统提示词，在每一次与大语言模型交互时都携带该信息。
  • 启用内置工具：配置智能体可使用的系统内置工具。
  • 启用MCP工具：配置智能体可使用的外部MCP工具，外部工具可在「MCP工具」菜单添加。
  • Agent执行LLM：智能体执行使用的主大语言模型配置。
  • 辅助LLM：生成标题、压缩上下文使用的LLM，通常配置为低成本、速度快的小参数规模模型。
  • 向量嵌入模型：向量嵌入模型用于辅助长期记忆语义存储和召回。
  • 工作区路径：智能体默认的工作目录。

智能体多轮对话

MeowClaw的多“轮”对话中，1个轮（batch）是指1次完整智能体交互，其中包含1条用户消息（User Message）和若干工具调用消息（带Tool Call的Assistant Message，可能还包含reasoning信息）与工具消息（Tool Message，调用工具的返回值），最后一条工具消息通常是final_answer工具调用，意味着智能体结束工作并提交结果显示给前端用户。虽然1个batch会合并显示在1个对话气泡中，但1个batch可能包含数十次迭代，每个迭代都会调用大语言模型接口。多轮对话中，较早的batch会根据配置的大语言模型上下文大小自动进行多级压缩，在尽量不丢失上下文记忆的前提下持续交互。

智能体执行与页面连接是解耦的，刷新浏览器、切换会话都不会中断正在执行的任务，重新进入会话时会从执行起点恢复流式输出现场，左侧会话列表会标记正在执行中的会话；不同会话可以并行执行各自的智能体任务。

会话钉选与项目管理

会话列表分为「已钉选」「项目」「会话」三个可折叠分组：

  • 钉选：会话的钉选按钮可将其固定到顶部「已钉选」分组，再次点击或菜单中取消即回到「会话」
  • 项目：项目类似会话的分类目录，项目归属于智能体，同智能体内项目名唯一，会话可通过行菜单「移入项目」归档，项目内可直接新建会话；项目中的会话也支持钉选，会同时展示在「已钉选」与项目内
  • 删除项目会级联删除其中全部会话
  • 「会话」支持下滑自动分页加载，收纳所有未钉选且未分组的会话

图片输入

当智能体的主LLM配置了vision能力标签时，聊天输入框旁会出现可用的图片上传按钮（未配置时按钮置灰），可随消息携带最多5张图片（png/jpeg/webp/gif，单张不超过10MB），图片以base64内联方式发送给多模态模型。较近轮次（5个batch以内）的历史图片会在后续对话中继续携带，更早的图片会省略为文本占位以控制请求体积。

智能体工作区

智能体工作区是智能体默认的工作目录，与智能体交互时，一次会话有独立的CWD（当前工作目录），它的默认值就是智能体工作区，这意味着智能体工作时产生的文件默认会优先写入自己的工作区中，而不是在操作系统中乱写。多个智能体可以配置相同的工作目录，但注意它们如果同时运行可能导致文件冲突。

左侧的「工作区管理菜单」是一个在线文件浏览器，在这里可以在线维护智能体的工作目录内的文件内容。

内置工具

MeowClaw为所有智能体配备了以下工具，它们默认全部启用以实现完整的智能体能力，在智能体配置界面也可以关闭部分工具，或关闭全部工具将智能体作为纯粹的聊天机器人使用。

  • cd：切换会话级的基础工作路径，默认值是工作区路径。
  • read：读取文件。
  • edit：编辑（更新）文件。
  • grep：在文件中使用正则表达式搜索。
  • glob：查找文件。
  • skill：加载Agent Skill。
  • write：追加或覆盖写文件。
  • exec：执行Shell命令，同时支持Windows CMD和Bash环境。
  • memory_write：异步写入长期记忆，提交后立即返回不阻塞对话。
  • memory_recall：召回长期记忆。
  • spawn_subagent：创建子智能体。

MCP工具

MCP工具通常作为智能体可使用的外部工具，用户可以配置MCP工具来随意扩展智能体的能力，例如context7、Tavily、Firecrawl等，支持stdio、Streamable HTTP、SSE（Legacy）三种MCP交互协议。

Agent Skill

全局Agent Skill管理：MeowClaw中在左侧的「SKILL」菜单可以配置Agent Skill，在这里可以上传一个包含SKILL.md和其它附属文件（包括可执行脚本等）的ZIP格式压缩包，已上传的Agent Skill系统会自动读取SKILL.md的YAML Frontmatter并以卡片形式展示。该菜单只负责Agent Skill的上传、删除和展示，具体使用时，需要将其部署到一个智能体中。

部署Agent Skill到智能体：已上传的Agent Skill可以部署到一个智能体，这其实就是将压缩包解压到智能体工作区的<智能体工作区>/.skill/下，这个文件夹下的内容都会被拥有该工作目录的智能体识别为自己拥有的Agent Skill，并通过skill内置工具访问。“部署”是个一次性操作，UI上没有直接的删除或撤回按钮，如果想删除一个智能体的Agent Skill，需要在对应智能体工作目录的<智能体工作区>/.skill/下删除对应Agent Skill名字的文件夹，或者直接与智能体对话，让其删除工作空间内的某个Agent Skill。

上下文压缩

MeowClaw为长流程对话而设计，上下文压缩分为多个层级。

  • 水位线预警：1个batch（即1轮ReAct Agent交互完成，可能包含多次工具调用迭代）执行完成后，当上下文已达到最大上下文长度的82%和93%时，用户前端会看到上下文不足、上下文严重不足的提示信息。
  • 会话滚动摘要：1个batch执行完成后，会自动对5个batch之前的内容使用大语言模型生成滚动摘要（Rolling Recap）并注入系统提示词，每个batch生成一个滚动摘要，滚动摘要会在达到20个时自动压缩前1-6个为1个合并的滚动摘要（Rolled Up Recap），保持滚动摘要总数不超过20个。
  • 工具消息折叠：智能体交互中，工具调用相关消息可能占用大量上下文，MeowClaw会自动“折叠”之前内容的工具调用信息，分两个层级：
  • Level1折叠：对于5个batch之前的工具调用消息，将返回值中字符数大于100的内容直接截断为“xxxxx... [此处因上下文压缩已截断]”。
  • Level2折叠：对于15个batch之前的交互，直接移除final_answer以外的全部工具调用消息，只保留用户输入和智能体最终回复。
  • 主动消息压缩：在以上压缩基础上，1次交互前上下文占用仍大于93%时立即先触发主动消息压缩再执行任务，这一过程会根据tokens消耗计算将n（n>=0）个batch之前的消息暴力压缩为1个主动压缩滚动摘要（Proactive Recap），以腾出上下文空间继续执行任务。

长期记忆

MeowClaw支持智能体级别跨会话的长期记忆功能，它依赖于memory_write、memory_recall两个内置工具，配置了这些工具意味着智能体开启了长期记忆功能。

  • memory_write：写入记忆工具，异步执行。智能体调用后立即返回，MeowClaw在后台自动召回与新内容最相似的已有记忆，然后调用辅助LLM进行决策，重复内容会跳过写入，与已有记忆矛盾或使其失效的内容会删除对应旧记忆，描述同一事实但更准确的内容会更新已有记忆，其余情况正常插入。插入的记忆会被抽取为记忆和实体关系，并使用Lucene9存储倒排索引和向量（如果配置了嵌入模型），记忆的存储模型是轻量级的图结构，记忆数据通过实体互相关联。
  • memory_recall：智能体尝试召回记忆时，MeowClaw会同时尝试召回记忆和相关实体信息，这些召回通常是BM25和向量混合检索的。

左侧的「记忆」菜单提供记忆管理页面，可以按智能体查看、搜索记忆，也可以手动添加、编辑或删除记忆，手动维护的记忆内容会原样保存，不经过模型提炼。

如果希望智能体始终携带记忆工作而不依赖其主动调用memory_recall，可以在智能体配置中开启激进记忆召回模式，开启后每次用户输入都会直接用于召回相关记忆，召回结果自动注入系统提示词。

安全护栏

MeowClaw为智能体的工具调用提供可配置的安全护栏，在每次工具真正执行前按策略求值并决定直接放行、拒绝执行或挂起等待用户审批。会话输入框的盾牌下拉可随时切换当前会话生效的策略，内置三种：

  • 手动审批模式：所有工具调用（final_answer除外）均需用户审批
  • 工作区读写模式（默认）：工作区内文件读写直接放行，工作区外读写、全部exec命令执行、全部MCP工具调用均需审批，记忆工具直接放行
  • 无限制模式：所有工具调用自动执行，不询问

审批请求以面板形式出现在输入框上方，展示工具名、关键参数与命中规则，支持快捷键操作：Y/Enter批准、N/Esc拒绝，也可以直接中断本轮执行，批准后该工具继续执行，拒绝则向模型返回固定的拒绝结果，审批记录作为独立事件渲染在AI回复气泡中并可展开查看。

左侧「安全护栏策略」菜单中可以用纯JSON自定义策略，例如：

{
  "defaultDecision": "deny",
  "rules": [
    {
      "tools": ["read", "write", "Tavily__tavily_search", "Tavily__*"],
      "paths": ["${cwd}/**", "**/config/*.json"],
      "action": "allow"
    }
  ]
}

匹配语义：

  • rules自上而下首个命中规则生效，无命中时使用defaultDecision，取值可能为allow/ask/deny
  • tools支持*通配，例如Tavily__*匹配该MCP服务全部工具
  • paths为Ant风格路径模式（可选），${cwd}占位符表示智能体当前工作目录，仅对含path参数的内置文件工具有效，无路径参数的工具（如exec）不受paths约束
  • 路径匹配统一忽略大小写，且不区分\与/分隔符，相对路径先按cwd解析为绝对路径再匹配

子智能体

MeowClaw支持父智能体通过内置工具spawn_subagent派发一次性子智能体，该工具是异步的，它会立即返回，一次性调用多次则多个子智能体将并发运行，所有子任务完成后结果自动汇总注入父智能体。子智能体在独立的新会话中运行，会话不出现在会话列表与历史中，父智能体气泡中每个子任务展示为可点击条目，点击可打开抽屉查看子任务的完整运行流程。子智能体会继承父会话的安全护栏策略，其审批请求统一冒泡到父会话的审批面板。父运行被停止时，所有未完成的子任务级联停止。

定时任务

定时任务支持配置Quartz风格的Cron表达式，定时将自然语言命令发给智能体。定时任务可以选择固定在一个会话中执行，或每次执行都重新创建会话。定时任务会话无人值守，安全护栏默认生效「无限制模式」。

大语言模型集成

MeowClaw支持OpenAI兼容协议的/v1/chat/completions大语言模型接口，大多数大语言模型Provider（例如Ollama等）都提供类似的端点。

向量嵌入模型集成

MeowClaw支持OpenAI兼容协议的/v1/embeddings向量嵌入模型接口，最大支持1024维向量。

tokens消耗统计

MeowClaw提供统计图表界面，可按日聚合统计已配置的所有模型中交互次数、tokens消耗等信息，供使用付费大语言模型接口时进行成本参考。

追踪观测

MeowClaw内置轻量级的LLM交互追踪能力（类似简化版LangSmith）。每次智能体交互都会记录为一个可回溯的批次追踪，左侧「追踪观测」菜单中可以按智能体、状态、关键字、时间范围检索，点开任意批次可查看：

  • 事件时间线：该批次的思考、工具调用与返回、最终回答等完整事件流。
  • LLM调用明细：该批次内每一次LLM调用的完整信息，包括调用用途（主循环/标题/摘要/记忆）、请求消息列表、响应内容、推理内容、工具调用、tokens消耗、耗时与状态。
  • 批次的状态、错误信息、tokens消耗与耗时等汇总信息。

技术栈

  • 后端：Java，SpringBoot，H2，Lucene
  • 前端：React，Vite，Tailwind CSS，shadcn/ui

构建部署

开始前需要先下载并本地安装项目关联的另一个基础框架，MeowClaw没有使用LangChain4J或SpringAI这类重型框架，而是专门开发了一个轻量级Agent框架proarc-agentic。

git clone https://github.com/gacfox/proarc-agentic
cd proarc-agentic && mvn clean install

然后构建和运行MeowClaw项目。

# 1. 构建前端
cd meowclaw-web && npm install && npm run build

# 2. 构建后端
cd meowclaw && mvn clean package

# 3. 启动服务
cd meowclaw/target && java -jar meowclaw-0.0.1-SNAPSHOT.jar

配置说明

环境变量 说明
MEOWCLAW_DATA_DIR MeowClaw的数据目录，用于保存系统数据库文件和智能体工作区等，默认为<当前路径>/data

安全提醒

  1. 不建议将MeowClaw暴露到公网，部署在云主机上时，推荐用SSH隧道转发到本地端口访问。
  2. MeowClaw智能体本质上等价于一个操作系统的Shell，当安全护栏策略选择无限制模式时，智能体配置全部内置工具后权限非常高，如果操作不当可能意外导致电脑或云主机失联、文件损坏等情况。