下一代透明智能体架构 · Next-Gen Transparent Agent Architecture
🤖 你的 AI 在背着你做什么？MiniClaw 让所有行为无所遁形
💡 灵感来源：受 OpenClaw 的启发，MiniClaw 专注于解决 AI 智能体的透明度和可控性问题。
MiniClaw 是一个企业级透明可控智能体，重新定义 AI 系统的可信边界：
- 🔍 白盒化决策 → 5 类事件审计 + JSONL 日志 + Rich 监控终端，所有行为可追溯
- 🛡️ 零信任执行 → 两段式调用（help → run），先看说明书再执行，P0 级事故率降低 80%
- 🧠 持续学习 → 双水位记忆系统（长期画像 + 短期摘要），越用越懂你
- ⚡ 复杂任务编排 → 心跳任务系统 + 可插拔技能 + MCP 服务集成，解放双手
MiniClaw 支持OpenClaw 技能和Claude Code 技能，可直接使用两个生态系统的丰富技能资源，无需重新开发。
| 能力 | 说明 | 优势 |
|---|---|---|
| 🧠 双水位记忆 | 长期画像 + 短期摘要，持续学习用户偏好 | 越用越懂你，避免重复询问 |
| 🔍 全行为审计 | 5 类事件实时审计，JSONL 日志 + Rich 监控终端 | 告别黑箱，所有决策可追溯 |
| 🛡️ 零信任执行 | help → run 两段式调用，先看说明书再执行 | P0 级事故率降低 80%（50% → 10%） |
| ⏰ 心跳任务引擎 | 后台独立进程，自动执行定时任务 | 解放双手，复杂任务自动化 |
| 🖥️ 跨平台支持 | Unix + Windows 双平台自适应，LLM 自主选择命令 | 一套代码，全平台运行 |
| 🤖 Telegram Bot | 支持远程访问，随时随地使用 AI 助手 | 移动端访问，远程控制 |
| 🐜 飞书 Bot | 支持飞书/Lark 集成，企业级即时通讯 | 团队协作，企业部署 |
-
双水位记忆系统
- 长期画像 (
user_profile.md)：用户偏好、职业、特殊要求 - 近期摘要 (SQLite)：每 40 轮自动摘要，保留最近 10 轮
- 上下文修剪：智能保留关键对话，防止 Token 爆炸
- 长期画像 (
-
两段式技能调用
mode='help'：查看完整说明书（SKILL.md）mode='run'：执行具体操作- 支持反悔机制：看完说明书可以换工具
-
透明监控系统
- 5 类事件审计：
llm_input,tool_call,tool_result,ai_message,system_action - JSONL 日志格式，支持
tail -f实时监控 - Rich 终端 UI，颜色/面板区分事件类型
- 5 类事件审计：
-
心跳任务系统
- 后台独立协程，每 10 秒检查任务队列
- 支持 hourly/daily/weekly/monthly 循环任务
- 任务持久化存储，重启不丢失
-
多渠道 Bot 支持
- Telegram Bot：随时随地通过 Telegram 访问 AI 助手
- 飞书 Bot：企业级即时通讯集成
- 支持命令：
/start,/help,/clear,/status - 仅允许指定用户访问，确保安全性
-
跨平台路径拦截
- Unix + Windows 双平台越权拦截
- 禁止
..、绝对路径、用户主目录访问 - 所有操作限制在
office/工位内
-
Shell 命令安全
- 危险命令正则匹配拦截
- 60 秒超时熔断
- 非交互式执行（必须带
-y等参数）
- 系统信息注入 - 自动识别操作系统，注入平台相关信息
- LLM 自主选择命令 - 根据平台特性生成合适的命令（PowerShell / Bash）
- 路径格式兼容 - 自动处理
/和\路径分隔符 - 环境变量适配 - 跨平台环境变量读取和设置
| 工具 | 功能 | 示例 |
|---|---|---|
get_current_time |
获取当前时间 | "现在几点了？" |
calculator |
数学计算器 | "25 乘以 48 等于多少" |
schedule_task |
定时任务/闹钟 | "每天早上 8 点提醒我喝水" |
list_scheduled_tasks |
查看任务列表 | "我都有哪些任务" |
delete_scheduled_task |
删除任务 | "取消明天的会议提醒" |
modify_scheduled_task |
修改任务 | "把 8 点的会议改成 9 点" |
get_system_model_info |
获取模型信息 | "你是什么模型" |
save_user_profile |
更新用户画像 | "记住我喜欢喝冰美式" |
list_office_files |
列出文件 | "看看 office 里有什么" |
read_office_file |
读取文件 | "读取 readme.txt" |
write_office_file |
写入文件 | "创建 test.py" |
execute_office_shell |
执行 Shell 命令 | "运行 python test.py" |
- 动态加载：自动扫描
workspace/office/skills/目录 - SKILL.md 规范：每个技能包含完整说明书
- 兼容 OpenClaw 和 Claude Code 技能：可直接使用两个生态系统的技能
- 懒加载机制：启动时只扫描元数据，首次调用时才加载完整内容
- LRU 缓存：自动清理不常用的技能，优化内存占用
- 推荐技能：
skill-creator：用自然语言让 MiniClaw 自己创建技能skill-vetter：检查技能的安全性mcporter：连接外部 MCP (Model Context Protocol) 服务mcp-builder：构建自己的 MCP 服务tavily-search：AI 优化网络搜索weather：天气查询
# 克隆项目
git clone https://github.com/2351548518/MiniClaw.git
cd MiniClaw
# 安装依赖并注册命令行工具（一步完成）
pip install -e .💡 推荐使用虚拟环境：
# 创建虚拟环境 python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 安装项目（会自动安装 requirements.txt 中的依赖） pip install -e .安装完成后，即可在任意目录使用
miniclaw命令。
有两种配置方式：自动配置向导（推荐）或 手动配置。
# 启动交互式配置向导
miniclaw config配置向导会引导你：
- 选择模型提供商（OpenAI / Anthropic / 阿里云 / 腾讯 / Z.AI / Ollama）
- 输入 API Key
- 配置 Base URL（可选）
- 自动测试连接，确保配置正确
# 复制示例配置文件
cp .env.example .env
# 编辑配置文件
vim .env # 或使用你喜欢的编辑器编辑 .env 文件，配置必要的参数：
# 模型提供商
DEFAULT_PROVIDER=aliyun
DEFAULT_MODEL=glm-5
# API Key (根据提供商选择对应的 Key)
OPENAI_API_KEY=sk-your-api-key-here
# Base URL (可选，使用代理时配置)
OPENAI_API_BASE=https://coding.dashscope.aliyuncs.com/v1配置说明：
DEFAULT_PROVIDER: 模型提供商 (openai,anthropic,aliyun,tencent,z.ai,ollama)DEFAULT_MODEL: 模型名称 (如gpt-4o-mini,glm-5,qwen-max)OPENAI_API_KEY: OpenAI 或兼容接口的 API KeyANTHROPIC_API_KEY: Anthropic 的 API KeyOPENAI_API_BASE: 兼容接口的 Base URL（阿里云、腾讯云等）OLLAMA_BASE_URL: Ollama 本地服务地址（默认http://localhost:11434）
💡 工作区配置：工作区路径已在代码中初始化，默认为项目根目录的
workspace文件夹，无需在.env中配置。仅当需要自定义工作区位置时，才设置MINICLAW_WORKSPACE环境变量。
💡 提示：配置完成后，可运行
miniclaw run聊天测试连接是否正常。
# 启动主程序
miniclaw run常用命令示例：
| 类型 | 命令示例 | 说明 |
|---|---|---|
| ⏰ 时间查询 | 现在几点了？ |
获取当前时间 |
| 🧮 数学计算 | 帮我算一下 25 乘以 48 |
调用计算器工具 |
| ⏲️ 定时任务 | 每天早上 8 点提醒我喝水 |
创建循环任务 |
| 📋 查看任务 | 我都有哪些任务 |
查看任务列表 |
| ✏️ 修改任务 | 把 8 点的喝水提醒改成 9 点 |
修改已有任务 |
| ❌ 删除任务 | 取消明天的会议提醒 |
删除任务 |
| 📁 文件操作 | 看看 office 里有什么文件 |
列出工位文件 |
| 📖 读取文件 | 读取 readme.txt |
读取文件内容 |
| 📝 创建文件 | 创建 test.py |
写入新文件 |
| 💻 Shell 命令 | 运行 python test.py |
执行 Shell 命令 |
| 🚪 退出 | /exit |
退出程序 |
MiniClaw 内置心跳任务系统（Heartbeat），自动在后台执行定时任务：
- 自动触发：心跳进程每 10 秒检查任务队列，到点自动触发
- 循环任务：支持 hourly/daily/weekly/monthly 循环模式
- 任务持久化：任务保存在
workspace/tasks.json，重启不丢失 - 实时监控：运行
miniclaw monitor可查看任务执行日志
心跳任务示例：
# 创建循环任务
> 每天早上 8 点提醒我喝水
✅ 任务已加入队列 | 循环模式：daily | 首发时间：2026-04-07 08:00:00
# 心跳系统会在每天 8:00 自动触发提醒在另一个终端运行：
miniclaw monitor实时查看：
- 🧠 LLM 输入
- 💡 工具调用
- 💻 工具结果
- 🤖 AI 回复
- ⚙️ 系统动作
通过 Telegram 远程访问 AI 助手：
# 启动 Telegram Bot
miniclaw telegram配置说明：
在 .env 文件中添加以下配置：
# Telegram Bot 配置
TELEGRAM_BOT_TOKEN=your-bot-token-here
TELEGRAM_OWNER_ID=your-telegram-user-id
TELEGRAM_ASSISTANT_NAME=MiniClaw获取方式：
TELEGRAM_BOT_TOKEN：通过 Telegram 的 @BotFather 创建 Bot 获取TELEGRAM_OWNER_ID：通过 @userinfobot 获取你的用户 ID
Telegram Bot 命令：
| 命令 | 功能 |
|---|---|
/start |
显示欢迎信息 |
/help |
显示帮助信息 |
/clear |
重置对话会话 |
/status |
查看系统状态 |
通过飞书/Lark 远程访问 AI 助手：
# 启动飞书 Bot
miniclaw feishu配置说明：
在 .env 文件中添加以下配置：
# 飞书 Bot 配置
FEISHU_APP_ID=your-app-id
FEISHU_APP_SECRET=your-app-secret
FEISHU_ENCRYPT_KEY=your-encrypt-key (可选)
FEISHU_VERIFICATION_TOKEN=your-token (可选)
FEISHU_ALLOW_FROM=user_id1,user_id2 (白名单，可选)- 合规审计 - 5 类事件审计日志，满足企业合规要求
- 权限管控 - 沙盒隔离 + 路径拦截，防止越权操作
- 任务自动化 - 心跳任务引擎，定时执行重复性工作
- 知识沉淀 - 双水位记忆系统，持续学习组织偏好
- Agent 行为分析 - 完整记录 LLM 决策过程和工具调用链
- 安全研究 - 两段式调用机制，研究 AI 安全边界
- 调试友好 - JSONL 日志 + Rich 监控终端，快速定位问题
- 可扩展架构 - 可插拔技能系统，快速验证新想法
- Windows - 完整支持 PowerShell + CMD，路径自动适配
- Linux - 原生支持所有发行版，完美兼容 Bash
- macOS - 支持 zsh/bash，与 Unix 工具链无缝集成
- 本地开发助手 - 文件操作 + Shell 执行，自动化编码任务
- 项目监控 - 实时监控 AI 行为，防止意外操作
- 技能开发 - 支持自定义技能，快速集成新工具
- MCP 服务集成 - 连接外部 MCP 服务，扩展能力边界
- AI 智能体教学 - 透明展示 Agent 架构和决策流程
- Prompt 工程 - 观察不同 Prompt 对 AI 行为的影响
- 安全实践 - 学习 AI 安全最佳实践和防护措施
- 开源贡献 - 参与开源项目，积累实战经验
- 智能日程管理 - 定时提醒 + 循环任务，解放双手
- 文件自动化 - 批量处理文件，自动化工作流
- 信息查询 - 集成搜索技能，快速获取信息
- 个性化助手 - 记忆系统学习个人偏好，越用越顺手
架构说明：
- 输入层 (蓝色)：Heartbeat 心跳任务 + 用户输入 → Gateway 网关
- 记忆层 (粉色)：上下文裁剪 + 长短期记忆管理
- 智能决策层 (黄色)：Agent Loop + LLM 推理决策
- 工具执行层 (紫色)：内置工具集 + 可插拔 Skills
- 安全层 (橙色)：路径越权拦截 + 跨平台兼容
- 透明监控层 (绿色)：记忆更新 + 工具决策 + 工具参数 + 调用结果
- 输出层 (底部)：聊天终端 + 监控终端
| 模块 | 文件 | 功能 |
|---|---|---|
| Agent 循环 | miniclaw/core/agent/agent.py |
LangGraph StateGraph，决策大脑 |
| 上下文管理 | miniclaw/core/agent/context.py |
消息修剪，双水位记忆 |
| 技能加载 | miniclaw/core/skills/skill_loader.py |
动态加载 SKILL.md，两段式调用，懒加载 |
| 内置工具 | miniclaw/core/tools/builtins.py |
时间/计算/任务调度等 |
| 沙盒工具 | miniclaw/core/tools/sandbox_tools.py |
文件操作 + Shell 执行 |
| 工具基类 | miniclaw/core/tools/base.py |
工具装饰器和基类 |
| 审计日志 | miniclaw/core/utils/logger.py |
JSONL 格式事件记录，异步写入 |
| LLM 提供商 | miniclaw/core/utils/provider.py |
多模型适配器工厂 |
| 心跳任务 | miniclaw/core/heartbeat/heartbeat.py |
定时任务检查与触发 |
| 事件总线 | miniclaw/core/bus/bus.py |
异步任务队列 |
| 配置管理 | miniclaw/core/config/config.py |
路径配置和环境变量 |
| Telegram Bot | miniclaw/core/channels/telegram.py |
Telegram 消息处理与命令响应 |
| 飞书 Bot | miniclaw/core/channels/feishu.py |
飞书/Lark WebSocket 集成 |
MiniClaw/
├── miniclaw/ # 核心包
│ ├── core/
│ │ ├── agent/ # Agent 模块
│ │ │ ├── __init__.py
│ │ │ ├── agent.py # Agent 循环 (LangGraph StateGraph)
│ │ │ └── context.py # 上下文修剪 + AgentState
│ │ ├── tools/ # 工具模块
│ │ │ ├── __init__.py
│ │ │ ├── base.py # 工具装饰器 @miniclaw_tool
│ │ │ ├── builtins.py # 内置工具 (时间/计算/任务)
│ │ │ └── sandbox_tools.py # 沙盒工具 (文件/Shell)
│ │ ├── skills/ # 技能模块
│ │ │ ├── __init__.py
│ │ │ └── skill_loader.py # 懒加载技能系统
│ │ ├── channels/ # 通信渠道
│ │ │ ├── __init__.py
│ │ │ ├── telegram.py # Telegram Bot
│ │ │ └── feishu.py # 飞书 Bot
│ │ ├── heartbeat/ # 心跳任务
│ │ │ ├── __init__.py
│ │ │ └── heartbeat.py # 后台心跳协程
│ │ ├── bus/ # 事件总线
│ │ │ ├── __init__.py
│ │ │ └── bus.py # 异步任务队列
│ │ ├── config/ # 配置管理
│ │ │ ├── __init__.py
│ │ │ └── config.py # 路径配置
│ │ ├── utils/ # 工具函数
│ │ │ ├── __init__.py
│ │ │ ├── logger.py # JSONL 审计日志
│ │ │ └── provider.py # LLM 提供商适配
│ │ └── __init__.py
│ └── __init__.py
├── entry/ # 入口文件
│ ├── __init__.py
│ ├── main.py # 主程序入口 (交互式对话)
│ ├── cli.py # CLI 工具 (config/run/monitor/telegram/feishu)
│ └── monitor.py # 监控终端 (Rich UI)
├── workspace/ # 工作区 (运行时创建)
│ ├── office/ # 沙盒工位
│ │ └── skills/ # 可插拔技能目录
│ ├── memory/ # 记忆存储
│ │ └── user_profile.md # 用户长期画像
│ ├── data/ # 数据文件
│ │ └── sessions.json # 会话状态
│ ├── state.sqlite3 # 对话历史数据库
│ └── tasks.json # 定时任务队列
├── logs/ # 日志目录 (运行时创建)
│ └── local_geek_master.jsonl # 审计日志
├── tests/ # 测试套件
│ ├── test_agent.py
│ ├── test_builtins.py
│ ├── test_context_advanced.py
│ ├── test_sandbox_tools.py
│ ├── test_two_phase_skills.py
│ ├── test_heartbeat.py
│ ├── test_lazy_loader.py
│ └── test_config_and_skill_loader.py
├── examples/ # 示例代码
│ ├── basic_usage.py
│ └── benchmark_lazy_loading.py
├── setup.py # 包安装配置
├── requirements.txt # 依赖列表
├── .env.example # 环境配置示例
├── .gitignore
├── LICENSE
└── README.md
.env 文件：主配置文件，包含 API Key、模型设置等敏感信息。
.env.example 文件：配置模板，包含所有可用配置项的说明和示例值。
首次使用时，复制示例文件并修改：
cp .env.example .env详细配置说明见 快速开始 - 配置 部分。
方法 1：直接复制
cp -r /path/to/skill workspace/office/skills/方法 2：使用 skill-creator
# 先安装 skill-creator 技能
cd workspace/office/skills
git clone https://github.com/.../skill-creator.git
# 然后用自然语言让 MiniClaw 创建新技能
> 帮我创建一个查询比特币价格的技能方法 3：使用 skill-vetter 检查安全性
# 安装 skill-vetter
cd workspace/office/skills
git clone https://github.com/.../skill-vetter.git
# 让 MiniClaw 检查技能安全性
> 帮我检查一下 weather 技能是否安全每个技能包含 SKILL.md：
---
name: weather
description: 获取天气预报
---
# Weather Skill
## 功能
获取全球城市的实时天气预报。
## 命令示例
\`\`\`bash
curl "wttr.in/Beijing?format=3"
\`\`\`
## 参数
- 城市名（必填）
- 天数（可选）# 单次任务
> 明天早上 9 点叫我起床
# 循环任务
> 每天早上 8 点提醒我喝水
> 每周一上午 10 点开团队会议
# 查看任务
> 我都有哪些任务
# 修改任务
> 把 8 点的喝水提醒改成 9 点
# 删除任务
> 取消明天的会议提醒在另一个终端运行：
miniclaw monitor实时查看：
- 🧠 LLM 输入
- 💡 工具调用
- 💻 工具结果
- 🤖 AI 回复
- ⚙️ 系统动作
# 实时监控
tail -f logs/local_geek_master.jsonl
# 搜索特定事件
grep "tool_call" logs/local_geek_master.jsonl | tail -20编辑 workspace/memory/user_profile.md：
# 用户档案
- **姓名**: Thor Allen
- **职业**: 程序员
- **偏好**:
- 喜欢喝冰美式咖啡
- 常用 Python 写代码
- 每天 8 点起床
- **特殊要求**:
- 回答要简洁
- 不要使用表情符号- 长期记忆：
user_profile.mdMarkdown 文件，存储用户偏好、职业、特殊要求 - 短期记忆：SQLite 数据库，存储完整对话历史
- 自动摘要：每 40 轮对话自动触发摘要，保留最近 10 轮
当对话轮次超过阈值时：
- 系统消息始终保留
- 保留最近 N 轮完整对话
- 旧对话压缩为摘要
- 防止 Token 爆炸
每个完整回合包含：
- 用户消息 (HumanMessage)
- AI 回复 (AIMessage)
- 工具调用 (ToolMessage)
# 运行所有测试
python3 -m pytest tests/ -v
# 运行特定测试
python3 tests/test_agent.py
python3 tests/test_two_phase_skills.py| 测试文件 | 测试内容 | 状态 |
|---|---|---|
test_agent.py |
Agent 循环 | ✅ 通过 |
test_builtins.py |
内置工具 | ✅ 通过 |
test_context_advanced.py |
上下文修剪 | ✅ 通过 |
test_sandbox_tools.py |
沙盒工具 | ✅ 通过 |
test_two_phase_skills.py |
两阶段调用 | ✅ 通过 |
test_heartbeat.py |
心跳任务 | ✅ 通过 |
test_lazy_loader.py |
懒加载机制 | ✅ 通过 |
test_config_and_skill_loader.py |
配置与技能加载 | ✅ 通过 |
欢迎提交 Issue 和 Pull Request！
# 克隆项目
git clone https://github.com/2351548518/MiniClaw.git
cd MiniClaw
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 安装开发依赖
pip install -e .本项目采用 MIT 许可证 - 详见 LICENSE 文件。
⭐ 如果这个项目对你有帮助，请给一个 Star！⭐
Made with ❤️ by 2351548518