CyberClaw

当 AI 开始"黑箱操作"，你需要一双透视眼

下一代透明智能体架构 · Next-Gen Transparent Agent Architecture

🌐 Language: 中文 · English

中文导航: 快速开始 · 核心能力 · 架构图 · 示例

English Nav: Quick Start · Core Capabilities · Architecture · Examples

🤖 你的 AI 在背着你做什么？CyberClaw 让所有行为无所遁形

💡 灵感来源：受 OpenClaw 的启发，CyberClaw 专注于解决 AI 智能体的透明度和可控性问题。

📖 简介

CyberClaw 是一个企业级透明可控智能体，重新定义 AI 系统的可信边界：

🔍 白盒化决策 → 5 类事件审计 + JSONL 日志 + Rich 监控终端，所有行为可追溯
🛡️ 零信任执行 → 两段式调用（help → run），先看说明书再执行，P0 级事故率降低 80%
🧠 持续学习 → 双水位记忆系统（长期画像 + 短期摘要），越用越懂你
⚡ 复杂任务编排 → 心跳任务系统 + 可插拔技能 + MCP 服务集成，解放双手

🔌 技能生态兼容

CyberClaw 支持OpenClaw 技能和Claude Code 技能，可直接使用两个生态系统的丰富技能资源，无需重新开发。

🌟 核心能力

能力	说明	优势
🧠 双水位记忆	长期画像 + 短期摘要，持续学习用户偏好	越用越懂你，避免重复询问
🔍 全行为审计	5 类事件实时审计，JSONL 日志 + Rich 监控终端	告别黑箱，所有决策可追溯
🛡️ 零信任执行	help → run 两段式调用，先看说明书再执行	P0 级事故率降低 80%（50% → 10%）
⏰ 心跳任务引擎	后台独立进程，自动执行定时任务	解放双手，复杂任务自动化
🖥️ 跨平台支持	Unix + Windows 双平台自适应，LLM 自主选择命令	一套代码，全平台运行

✨ 功能特性

🧠 智能核心

双水位记忆系统
- 长期画像 (user_profile.md)：用户偏好、职业、特殊要求
- 近期摘要 (SQLite)：每 MAX_TURNS 轮自动摘要，保留最近 KEEP_TURNS 轮
- 上下文修剪：智能保留关键对话，防止 Token 爆炸
两段式技能调用
- mode='help'：查看完整说明书（SKILL.md）
- mode='run'：执行具体操作
- 支持反悔机制：看完说明书可以换工具
透明监控系统
- 5 类事件审计：llm_input, tool_call, tool_result, ai_message, system_action
- JSONL 日志格式，支持 tail -f 实时监控
- Rich 终端 UI，颜色/面板区分事件类型
心跳任务系统
- 后台独立进程，每秒检查任务队列
- 支持 daily/weekly/monthly 循环任务
- 任务持久化存储，重启不丢失

🛡️ 安全沙盒

跨平台路径拦截
- 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 技能：可直接使用两个生态系统的技能
推荐技能：
- skill-creator：用自然语言让 CyberClaw 自己创建技能
- skill-vetter：检查技能的安全性
- mcporter：连接外部 MCP (Model Context Protocol) 服务
- mcp-builder：构建自己的 MCP 服务
- tavily-search：AI 优化网络搜索
- weather：天气查询

🚀 快速开始

1️⃣ 安装

# 克隆项目
git clone https://github.com/ttguy0707/CyberClaw.git
cd CyberClaw

# 安装依赖并注册命令行工具（一步完成）
pip install -e .

💡 推荐使用虚拟环境：
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装项目（会自动安装 requirements.txt 中的依赖）
pip install -e .
安装完成后，即可在任意目录使用 cyberclaw 命令。

2️⃣ 配置

有两种配置方式：自动配置向导（推荐）或 手动配置。

方式一：自动配置向导（推荐）

# 启动交互式配置向导
cyberclaw 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 Key
ANTHROPIC_API_KEY: Anthropic 的 API Key
OPENAI_API_BASE: 兼容接口的 Base URL（阿里云、腾讯云等）
OLLAMA_BASE_URL: Ollama 本地服务地址（默认 http://localhost:11434）

💡 工作区配置：工作区路径已在代码中初始化，默认为项目根目录的 workspace 文件夹，无需在 .env 中配置。仅当需要自定义工作区位置时，才设置 CYBERCLAW_WORKSPACE 环境变量。

💡 提示：配置完成后，可运行 cyberclaw run 聊天测试连接是否正常。

3️⃣ 运行

# 启动主程序
cyberclaw run

4️⃣ 基本用法

启动后进入交互式对话界面，如图所示：

常用命令示例：

类型	命令示例	说明
⏰ 时间查询	`现在几点了？`	获取当前时间
🧮 数学计算	`帮我算一下 25 乘以 48`	调用计算器工具
⏲️ 定时任务	`每天早上 8 点提醒我喝水`	创建循环任务
📋 查看任务	`我都有哪些任务`	查看任务列表
✏️ 修改任务	`把 8 点的喝水提醒改成 9 点`	修改已有任务
❌ 删除任务	`取消明天的会议提醒`	删除任务
📁 文件操作	`看看 office 里有什么文件`	列出工位文件
📖 读取文件	`读取 readme.txt`	读取文件内容
📝 创建文件	`创建 test.py`	写入新文件
💻 Shell 命令	`运行 python test.py`	执行 Shell 命令
🚪 退出	`/exit`	退出程序

⏰ 心跳任务系统

CyberClaw 内置心跳任务系统（Heartbeat），自动在后台执行定时任务：

自动触发：心跳进程每秒检查任务队列，到点自动触发
循环任务：支持 daily/weekly/monthly 循环模式
任务持久化：任务保存在 workspace/tasks.json，重启不丢失
实时监控：运行 cyberclaw monitor 可查看任务执行日志

心跳任务示例：

# 创建循环任务
> 每天早上 8 点提醒我喝水
✅ 任务已加入队列 | 循环模式：daily | 首发时间：2026-04-07 08:00:00

# 心跳系统会在每天 8:00 自动触发提醒

💡 提示：心跳任务在后台运行，即使不启动主程序也会执行（需单独运行心跳进程）。

5️⃣ 监控终端

在另一个终端运行：

cyberclaw monitor

🏢 适用场景

🔒 企业级应用

合规审计 - 5 类事件审计日志，满足企业合规要求
权限管控 - 沙盒隔离 + 路径拦截，防止越权操作
任务自动化 - 心跳任务引擎，定时执行重复性工作
知识沉淀 - 双水位记忆系统，持续学习组织偏好

🧪 AI 研究与开发

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 循环	`cyberclaw/core/agent.py`	LangGraph StateGraph，决策大脑
技能加载	`cyberclaw/core/skill_loader.py`	动态加载 SKILL.md，两段式调用
上下文管理	`cyberclaw/core/context.py`	消息修剪，双水位记忆
内置工具	`cyberclaw/core/tools/builtins.py`	时间/计算/任务调度等
沙盒工具	`cyberclaw/core/tools/sandbox_tools.py`	文件操作 + Shell 执行
审计日志	`cyberclaw/core/logger.py`	JSONL 格式事件记录
心跳任务	`cyberclaw/core/heartbeat.py`	定时任务检查与触发

项目结构

CyberClaw/
├── cyberclaw/                    # 核心包
│   ├── core/
│   │   ├── agent.py              # Agent 循环
│   │   ├── config.py             # 配置管理
│   │   ├── context.py            # 上下文修剪
│   │   ├── provider.py           # LLM 提供商适配
│   │   ├── skill_loader.py       # 动态技能加载
│   │   ├── logger.py             # 审计日志
│   │   ├── heartbeat.py          # 心跳任务
│   │   └── tools/
│   │       ├── base.py           # 工具装饰器
│   │       ├── builtins.py       # 内置工具
│   │       └── sandbox_tools.py  # 沙盒工具
│   └── __init__.py
├── workspace/
│   ├── office/                   # 沙盒工位
│   │   ├── skills/               # 可插拔技能
│   │   │   ├── weather/
│   │   │   ├── skill-creator/
│   │   │   └── ...
│   │   └── .env                  # 环境变量
│   ├── memory/
│   │   └── user_profile.md       # 用户长期画像
│   ├── state.sqlite3             # 对话历史数据库
│   └── tasks.json                # 定时任务队列
├── logs/
│   └── local_geek_master.jsonl   # 审计日志
├── docs/                         # 文档与架构图
│   ├── architect.png             # 系统架构图
│   ├── monitor.png               # 监控终端截图
│   ├── welcome.png               # 欢迎界面
│   ├── chat.png                  # 聊天界面
│   ├── config.png                # 配置向导
│   ├── memory.png                # 记忆系统
│   └── context_cut.png           # 上下文裁剪
├── entry/
│   ├── main.py                   # 主程序入口
│   ├── cli.py                    # CLI 配置向导
│   └── monitor.py                # 监控终端
├── tests/                        # 测试套件
│   ├── test_agent.py
│   ├── test_builtins.py
│   ├── test_two_phase_skills.py  # 两阶段测试
│   └── logs/                     # 测试报告
├── setup.py
├── .env                          # 环境配置（运行时创建）
├── .env.example                  # 环境配置示例（复制此文件开始配置）
└── 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

# 然后用自然语言让 CyberClaw 创建新技能
> 帮我创建一个查询比特币价格的技能

方法 3：使用 skill-vetter 检查安全性

# 安装 skill-vetter
cd workspace/office/skills
git clone https://github.com/.../skill-vetter.git

# 让 CyberClaw 检查技能安全性
> 帮我检查一下 weather 技能是否安全

技能规范

每个技能包含 SKILL.md：

---
name: weather
description: 获取天气预报
---

# Weather Skill

## 功能
获取全球城市的实时天气预报。

## 命令示例
```bash
curl "wttr.in/Beijing?format=3"
```

## 参数
- 城市名（必填）
- 天数（可选）

定时任务

# 单次任务
> 明天早上 9 点叫我起床

# 循环任务
> 每天早上 8 点提醒我喝水
> 每周一上午 10 点开团队会议

# 查看任务
> 我都有哪些任务

# 修改任务
> 把 8 点的喝水提醒改成 9 点

# 删除任务
> 取消明天的会议提醒

高级用法

1. 使用监控器

在另一个终端运行：

cyberclaw monitor

实时查看：

🧠 LLM 输入
💡 工具调用
💻 工具结果
🤖 AI 回复
⚙️ 系统动作

2. 查看审计日志

# 实时监控
tail -f logs/local_geek_master.jsonl

# 搜索特定事件
grep "tool_call" logs/local_geek_master.jsonl | tail -20

3. 自定义用户画像

编辑 workspace/memory/user_profile.md：

# 用户档案

- **姓名**: Thor Allen
- **职业**: 程序员
- **偏好**: 
  - 喜欢喝冰美式咖啡
  - 常用 Python 写代码
  - 每天 8 点起床
- **特殊要求**:
  - 回答要简洁
  - 不要使用表情符号

🧠 记忆系统

双水位记忆架构

长期记忆：user_profile.md Markdown 文件，存储用户偏好、职业、特殊要求
短期记忆：SQLite 数据库，存储完整对话历史
自动摘要：每 20 轮对话自动触发摘要，保留最近 10 轮

上下文裁剪

当对话轮次超过阈值时：

系统消息始终保留
保留最近 N 轮完整对话
旧对话压缩为摘要
防止 Token 爆炸

轮次记忆

每个完整回合包含：

用户消息 (HumanMessage)
AI 回复 (AIMessage)
工具调用 (ToolMessage)

🧪 测试

运行测试

# 运行所有测试
python3 -m pytest tests/ -v

# 运行特定测试
python3 tests/test_two_phase_skills.py

# 运行两阶段测试
python3 -c "from tests.test_two_phase_skills import run_tests; run_tests()"

测试覆盖

测试文件	测试内容	状态
`test_agent.py`	Agent 循环	✅ 通过
`test_builtins.py`	内置工具	✅ 通过
`test_context.py`	上下文修剪	✅ 通过
`test_sandbox_tools.py`	沙盒工具	✅ 通过
`test_two_phase_skills.py`	两阶段调用	✅ 通过
`test_heartbeat.py`	心跳任务	✅ 通过

两阶段测试报告

根据 tests/logs/test_two_phase_skills.md 的实验数据：

指标	单阶段	两阶段	提升
安全命中率	50.0%	90.0%	+40%
P0 级事故率	50.0%	10.0%	-80%
平均决策耗时	19.33s	23.88s	+23.5%

结论：两阶段架构用 23.5% 的时间开销，换来了事故率从 50% 暴降至 0%（实际破坏性执行为 0）。

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

开发环境

# 克隆项目
git clone https://github.com/ttguy0707/CyberClaw.git
cd CyberClaw

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装开发依赖
pip install -e ".[dev]"

提交规范

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试相关
chore: 构建/工具

📄 许可证

MIT License

🙏 致谢

OpenClaw - 灵感来源与技能生态
LangChain - LLM 应用开发框架
LangGraph - 有状态 Agent 构建
Rich - 终端美化
Prompt Toolkit - 交互式命令行
所有贡献者 - 感谢你们的贡献！

📬 联系方式

GitHub: @ttguy0707
邮箱: allen.wtyummy@gmail.com

⭐ Star History

👾 CyberClaw · 下一代透明智能体架构

Made with ❤️ by @ttguy0707

🤖 What is your AI doing behind the scenes? CyberClaw makes every action visible.

💡 Inspired by OpenClaw, CyberClaw focuses on transparency and controllability for AI agents.

📖 Introduction

CyberClaw is an enterprise-grade transparent and controllable agent that redefines the trust boundary of AI systems:

🔍 White-box decisions -> 5-category event auditing, JSONL logs, and a Rich monitoring terminal make every action traceable
🛡️ Zero-trust execution -> two-phase invocation (help -> run) lets the agent read instructions before execution, reducing P0 incident risk by 80%
🧠 Continuous learning -> dual-watermark memory, combining a long-term profile with short-term summaries, learns your preferences over time
⚡ Complex task orchestration -> heartbeat tasks, pluggable skills, and MCP service integration automate repetitive work

🔌 Skill Ecosystem Compatibility

CyberClaw supports both OpenClaw skills and Claude Code skills, so you can reuse rich skill resources from both ecosystems without rebuilding them.

🌟 Core Capabilities

Capability	Description	Benefit
🧠 Dual-watermark memory	Long-term profile + short-term summaries that continuously learn user preferences	Understands you better over time and avoids repeated questions
🔍 Full behavior auditing	5-category real-time event auditing, JSONL logs, and a Rich monitoring terminal	No more black boxes; every decision is traceable
🛡️ Zero-trust execution	`help` -> `run` two-phase calls that read the manual before execution	Reduces P0 incident risk by 80% (50% -> 10%)
⏰ Heartbeat task engine	Independent background process for scheduled tasks	Automates complex and repetitive tasks
🖥️ Cross-platform support	Adaptive support for Unix and Windows, with LLM-selected commands	One codebase runs across platforms

✨ Features

🧠 Intelligent Core

Dual-watermark memory system
- Long-term profile (user_profile.md): user preferences, occupation, and special requirements
- Recent summaries (SQLite): automatically summarizes every MAX_TURNS turns and keeps the latest KEEP_TURNS turns
- Context trimming: preserves key conversations and prevents token explosion
Two-phase skill invocation
- mode='help': read the full instruction file (SKILL.md)
- mode='run': execute the concrete operation
- Supports reconsideration: after reading the manual, the agent can choose another tool
Transparent monitoring system
- 5 audited event types: llm_input, tool_call, tool_result, ai_message, system_action
- JSONL log format with tail -f real-time monitoring
- Rich terminal UI with colors and panels for different event types
Heartbeat task system
- Independent background process checks the task queue every second
- Supports daily, weekly, and monthly recurring tasks
- Persistent task storage survives restarts

🛡️ Security Sandbox

Cross-platform path interception
- Blocks unauthorized access on both Unix and Windows
- Forbids .., absolute paths, and user home directory access
- Restricts all operations to the office/ workspace
Shell command safety
- Blocks dangerous commands with regex matching
- Enforces a 60-second timeout circuit breaker
- Runs commands non-interactively and requires flags such as -y when needed

🖥️ Cross-platform Capabilities

System information injection - automatically detects the operating system and injects platform-specific context
LLM-selected commands - generates suitable commands based on the platform, such as PowerShell or Bash
Path format compatibility - automatically handles / and \ path separators
Environment variable adaptation - reads and sets environment variables across platforms

🔧 Built-in Tools

Tool	Function	Example
`get_current_time`	Get the current time	"What time is it now?"
`calculator`	Math calculator	"What is 25 times 48?"
`schedule_task`	Scheduled tasks and alarms	"Remind me to drink water every morning at 8"
`list_scheduled_tasks`	List tasks	"What tasks do I have?"
`delete_scheduled_task`	Delete a task	"Cancel tomorrow's meeting reminder"
`modify_scheduled_task`	Modify a task	"Move the 8 o'clock meeting to 9"
`get_system_model_info`	Get model information	"What model are you?"
`save_user_profile`	Update user profile	"Remember that I like iced Americano"
`list_office_files`	List files	"Show me what is in office"
`read_office_file`	Read a file	"Read readme.txt"
`write_office_file`	Write a file	"Create test.py"
`execute_office_shell`	Run a shell command	"Run python test.py"

🎯 Pluggable Skills

Dynamic loading: automatically scans workspace/office/skills/
SKILL.md convention: each skill contains a complete instruction manual
Compatible with OpenClaw and Claude Code skills: reuse skills from both ecosystems directly
Recommended skills:
- skill-creator: create skills with natural language through CyberClaw
- skill-vetter: check skill safety
- mcporter: connect external MCP (Model Context Protocol) services
- mcp-builder: build your own MCP services
- tavily-search: AI-optimized web search
- weather: weather lookup

🚀 Quick Start

1️⃣ Installation

# Clone the project
git clone https://github.com/ttguy0707/CyberClaw.git
cd CyberClaw

# Install dependencies and register the CLI in one step
pip install -e .

💡 Virtual environment recommended:
# Create a virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install the project. Dependencies from requirements.txt are installed automatically.
pip install -e .
After installation, the cyberclaw command is available from any directory.

2️⃣ Configuration

There are two configuration methods: the automatic setup wizard (recommended) and manual configuration.

Option 1: Automatic Setup Wizard (Recommended)

# Start the interactive configuration wizard
cyberclaw config

The wizard guides you through:

Choosing a model provider (OpenAI / Anthropic / Alibaba Cloud / Tencent / Z.AI / Ollama)
Entering an API key
Configuring the Base URL (optional)
Automatically testing the connection to verify the configuration

Option 2: Manual Configuration

# Copy the example configuration file
cp .env.example .env

# Edit the configuration file
vim .env  # Or use your preferred editor

Edit .env and configure the required parameters:

# Model provider
DEFAULT_PROVIDER=aliyun
DEFAULT_MODEL=glm-5

# API Key. Choose the corresponding key for your provider.
OPENAI_API_KEY=sk-your-api-key-here

# Base URL. Optional; configure it when using a proxy or compatible endpoint.
OPENAI_API_BASE=https://coding.dashscope.aliyuncs.com/v1

Configuration reference:

DEFAULT_PROVIDER: model provider (openai, anthropic, aliyun, tencent, z.ai, ollama)
DEFAULT_MODEL: model name, such as gpt-4o-mini, glm-5, or qwen-max
OPENAI_API_KEY: API key for OpenAI or compatible APIs
ANTHROPIC_API_KEY: Anthropic API key
OPENAI_API_BASE: Base URL for compatible APIs such as Alibaba Cloud or Tencent Cloud
OLLAMA_BASE_URL: local Ollama service URL, defaulting to http://localhost:11434

💡 Workspace configuration: the workspace path is initialized in code and defaults to the workspace folder in the project root. You do not need to configure it in .env. Set the CYBERCLAW_WORKSPACE environment variable only when you need a custom workspace path.

💡 Tip: after configuration, run cyberclaw run to test whether chat connectivity works.

3️⃣ Run

# Start the main program
cyberclaw run

4️⃣ Basic Usage

After startup, CyberClaw enters the interactive chat interface:

Common command examples:

Type	Example Command	Description
⏰ Time query	`What time is it now?`	Get the current time
🧮 Math	`Calculate 25 times 48`	Use the calculator tool
⏲️ Scheduled task	`Remind me to drink water every morning at 8`	Create a recurring task
📋 List tasks	`What tasks do I have?`	View the task list
✏️ Modify task	`Move the 8 o'clock water reminder to 9`	Modify an existing task
❌ Delete task	`Cancel tomorrow's meeting reminder`	Delete a task
📁 File operations	`Show me the files in office`	List workspace files
📖 Read file	`Read readme.txt`	Read file content
📝 Create file	`Create test.py`	Write a new file
💻 Shell command	`Run python test.py`	Execute a shell command
🚪 Exit	`/exit`	Exit the program

⏰ Heartbeat Task System

CyberClaw includes a heartbeat task system that automatically executes scheduled tasks in the background:

Automatic triggering: the heartbeat process checks the task queue every second and triggers tasks on time
Recurring tasks: supports daily, weekly, and monthly recurrence
Persistent tasks: tasks are stored in workspace/tasks.json and survive restarts
Real-time monitoring: run cyberclaw monitor to view task execution logs

Heartbeat task example:

# Create a recurring task
> Remind me to drink water every morning at 8
✅ Task added to queue | Recurrence: daily | First run: 2026-04-07 08:00:00

# The heartbeat system triggers the reminder at 8:00 every day

💡 Tip: heartbeat tasks run in the background and can execute even when the main program is not running, as long as the heartbeat process is started separately.

5️⃣ Monitoring Terminal

Run this in another terminal:

cyberclaw monitor

🏢 Use Cases

🔒 Enterprise Applications

Compliance auditing - 5-category event audit logs for enterprise compliance requirements
Permission control - sandbox isolation and path interception prevent unauthorized operations
Task automation - heartbeat task engine executes repetitive work on schedule
Knowledge accumulation - dual-watermark memory continuously learns organizational preferences

🧪 AI Research and Development

Agent behavior analysis - fully records LLM decision processes and tool-call chains
Security research - two-phase invocation helps study AI safety boundaries
Debug-friendly workflow - JSONL logs and a Rich monitoring terminal make issues easier to locate
Extensible architecture - pluggable skills make it easy to validate new ideas

🖥️ Cross-platform Deployment

Windows - full support for PowerShell and CMD with automatic path adaptation
Linux - native support for all distributions and Bash compatibility
macOS - supports zsh/bash and integrates naturally with Unix toolchains

🛠️ Developer Tools

Local development assistant - file operations and shell execution for automated coding tasks
Project monitoring - monitor AI behavior in real time to prevent unexpected operations
Skill development - supports custom skills for fast tool integration
MCP service integration - connects external MCP services to extend capability boundaries

📚 Education and Learning

AI agent teaching - transparently demonstrates agent architecture and decision flows
Prompt engineering - observe how different prompts affect AI behavior
Security practice - learn AI safety best practices and protective measures
Open-source contribution - participate in open-source development and gain practical experience

🏠 Personal Productivity

Smart schedule management - reminders and recurring tasks reduce manual effort
File automation - batch-process files and automate workflows
Information lookup - integrate search skills for quick information retrieval
Personalized assistant - memory learns personal preferences and improves over time

🏗️ System Architecture

Full Architecture Diagram

Architecture overview:

Input layer (blue): heartbeat tasks + user input -> gateway
Memory layer (pink): context trimming + long-term and short-term memory management
Intelligent decision layer (yellow): Agent Loop + LLM reasoning and decisions
Tool execution layer (purple): built-in tools + pluggable skills
Security layer (orange): path access interception + cross-platform compatibility
Transparent monitoring layer (green): memory updates + tool decisions + tool parameters + call results
Output layer (bottom): chat terminal + monitoring terminal

Core Modules

Module	File	Function
Agent loop	`cyberclaw/core/agent.py`	LangGraph StateGraph and decision engine
Skill loading	`cyberclaw/core/skill_loader.py`	Dynamically loads SKILL.md with two-phase invocation
Context management	`cyberclaw/core/context.py`	Message trimming and dual-watermark memory
Built-in tools	`cyberclaw/core/tools/builtins.py`	Time, calculation, task scheduling, and more
Sandbox tools	`cyberclaw/core/tools/sandbox_tools.py`	File operations and shell execution
Audit logging	`cyberclaw/core/logger.py`	JSONL event logging
Heartbeat tasks	`cyberclaw/core/heartbeat.py`	Scheduled task checking and triggering

Project Structure

CyberClaw/
├── cyberclaw/                    # Core package
│   ├── core/
│   │   ├── agent.py              # Agent loop
│   │   ├── config.py             # Configuration management
│   │   ├── context.py            # Context trimming
│   │   ├── provider.py           # LLM provider adapters
│   │   ├── skill_loader.py       # Dynamic skill loading
│   │   ├── logger.py             # Audit logging
│   │   ├── heartbeat.py          # Heartbeat tasks
│   │   └── tools/
│   │       ├── base.py           # Tool decorator
│   │       ├── builtins.py       # Built-in tools
│   │       └── sandbox_tools.py  # Sandbox tools
│   └── __init__.py
├── workspace/
│   ├── office/                   # Sandbox workspace
│   │   ├── skills/               # Pluggable skills
│   │   │   ├── weather/
│   │   │   ├── skill-creator/
│   │   │   └── ...
│   │   └── .env                  # Environment variables
│   ├── memory/
│   │   └── user_profile.md       # Long-term user profile
│   ├── state.sqlite3             # Conversation history database
│   └── tasks.json                # Scheduled task queue
├── logs/
│   └── local_geek_master.jsonl   # Audit logs
├── docs/                         # Documentation and diagrams
│   ├── architect.png             # System architecture diagram
│   ├── monitor.png               # Monitoring terminal screenshot
│   ├── welcome.png               # Welcome screen
│   ├── chat.png                  # Chat interface
│   ├── config.png                # Configuration wizard
│   ├── memory.png                # Memory system
│   └── context_cut.png           # Context trimming
├── entry/
│   ├── main.py                   # Main program entry
│   ├── cli.py                    # CLI configuration wizard
│   └── monitor.py                # Monitoring terminal
├── tests/                        # Test suite
│   ├── test_agent.py
│   ├── test_builtins.py
│   ├── test_two_phase_skills.py  # Two-phase tests
│   └── logs/                     # Test reports
├── setup.py
├── .env                          # Runtime environment configuration
├── .env.example                  # Example environment configuration
└── README.md

📖 User Guide

Configuration Files

.env file: the main configuration file that contains sensitive information such as API keys and model settings.

.env.example file: configuration template with descriptions and example values for all available options.

For first-time setup, copy the example file and modify it:

cp .env.example .env

See Quick Start - Configuration for detailed configuration instructions.

Skill System

Installing Skills

Method 1: Direct copy

cp -r /path/to/skill workspace/office/skills/

Method 2: Use skill-creator

# Install the skill-creator skill first
cd workspace/office/skills
git clone https://github.com/.../skill-creator.git

# Then ask CyberClaw to create a new skill with natural language
> Create a skill for querying Bitcoin prices

Method 3: Use skill-vetter for safety checks

# Install skill-vetter
cd workspace/office/skills
git clone https://github.com/.../skill-vetter.git

# Ask CyberClaw to check skill safety
> Check whether the weather skill is safe

Skill Convention

Each skill contains a SKILL.md file:

---
name: weather
description: Get weather forecasts
---

# Weather Skill

## Function
Get real-time weather forecasts for cities worldwide.

## Command Example
```bash
curl "wttr.in/Beijing?format=3"
```

## Parameters
- City name (required)
- Number of days (optional)

Scheduled Tasks

# One-time task
> Wake me up tomorrow morning at 9

# Recurring tasks
> Remind me to drink water every morning at 8
> Hold a team meeting every Monday at 10 AM

# View tasks
> What tasks do I have?

# Modify a task
> Move the 8 o'clock water reminder to 9

# Delete a task
> Cancel tomorrow's meeting reminder

Advanced Usage

1. Use the Monitor

Run this in another terminal:

cyberclaw monitor

View in real time:

🧠 LLM input
💡 Tool calls
💻 Tool results
🤖 AI replies
⚙️ System actions

2. View Audit Logs

# Real-time monitoring
tail -f logs/local_geek_master.jsonl

# Search for specific events
grep "tool_call" logs/local_geek_master.jsonl | tail -20

3. Customize the User Profile

Edit workspace/memory/user_profile.md:

# User Profile

- **Name**: Thor Allen
- **Occupation**: Programmer
- **Preferences**:
  - Likes iced Americano
  - Often writes code in Python
  - Gets up at 8 every day
- **Special requirements**:
  - Keep answers concise
  - Do not use emojis

🧠 Memory System

Dual-watermark Memory Architecture

Long-term memory: user_profile.md, a Markdown file that stores user preferences, occupation, and special requirements
Short-term memory: SQLite database that stores complete conversation history
Automatic summarization: triggers every 20 conversation turns and keeps the latest 10 turns

Context Trimming

When the number of conversation turns exceeds the threshold:

System messages are always retained
The latest N full conversation turns are retained
Older conversations are compressed into summaries
Token explosion is prevented

Turn Memory

Each complete turn contains:

User message (HumanMessage)
AI response (AIMessage)
Tool call (ToolMessage)

🧪 Testing

Run Tests

# Run all tests
python3 -m pytest tests/ -v

# Run a specific test
python3 tests/test_two_phase_skills.py

# Run two-phase tests
python3 -c "from tests.test_two_phase_skills import run_tests; run_tests()"

Test Coverage

Test File	Coverage	Status
`test_agent.py`	Agent loop	✅ Passing
`test_builtins.py`	Built-in tools	✅ Passing
`test_context.py`	Context trimming	✅ Passing
`test_sandbox_tools.py`	Sandbox tools	✅ Passing
`test_two_phase_skills.py`	Two-phase invocation	✅ Passing
`test_heartbeat.py`	Heartbeat tasks	✅ Passing

Two-phase Test Report

Based on the experimental data in tests/logs/test_two_phase_skills.md:

Metric	Single-phase	Two-phase	Improvement
Safety hit rate	50.0%	90.0%	+40%
P0 incident rate	50.0%	10.0%	-80%
Average decision latency	19.33s	23.88s	+23.5%

Conclusion: the two-phase architecture trades 23.5% more time for an incident-rate drop from 50% to 0% in actual destructive execution.

🤝 Contributing

Issues and pull requests are welcome.

Development Environment

# Clone the project
git clone https://github.com/ttguy0707/CyberClaw.git
cd CyberClaw

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

Commit Convention

feat: new feature
fix: bug fix
docs: documentation update
style: code style
refactor: refactoring
test: test-related changes
chore: build or tooling changes

📄 License

MIT License

🙏 Acknowledgements

OpenClaw - inspiration and skill ecosystem
LangChain - LLM application development framework
LangGraph - stateful agent construction
Rich - terminal styling
Prompt Toolkit - interactive command line
All contributors - thank you for your contributions!

📬 Contact

GitHub: @ttguy0707
Email: allen.wtyummy@gmail.com

⭐ Star History

👾 CyberClaw · Next-Gen Transparent Agent Architecture

Made with ❤️ by @ttguy0707

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.vscode		.vscode
cyberclaw		cyberclaw
docs		docs
entry		entry
examples		examples
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
requirements.txt		requirements.txt
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

CyberClaw

当 AI 开始"黑箱操作"，你需要一双透视眼

📖 简介

🔌 技能生态兼容

🌟 核心能力

✨ 功能特性

🧠 智能核心

🛡️ 安全沙盒

🖥️ 跨平台特性

🔧 内置工具

🎯 可插拔技能

🚀 快速开始

1️⃣ 安装

2️⃣ 配置

方式一：自动配置向导（推荐）

方式二：手动配置

3️⃣ 运行

4️⃣ 基本用法

⏰ 心跳任务系统

5️⃣ 监控终端

🏢 适用场景

🔒 企业级应用

🧪 AI 研究与开发

🖥️ 跨平台部署

🛠️ 开发者工具

📚 教育与学习

🏠 个人效率工具

🏗️ 系统架构

完整架构图

核心模块

项目结构

📖 使用指南

配置文件说明

技能系统

安装技能

技能规范

定时任务

高级用法

1. 使用监控器

2. 查看审计日志

3. 自定义用户画像

🧠 记忆系统

双水位记忆架构

上下文裁剪

轮次记忆

🧪 测试

运行测试

测试覆盖

两阶段测试报告

🤝 贡献指南

开发环境

提交规范

📄 许可证

🙏 致谢

📬 联系方式

⭐ Star History

📖 Introduction

🔌 Skill Ecosystem Compatibility

🌟 Core Capabilities

✨ Features

🧠 Intelligent Core

🛡️ Security Sandbox

🖥️ Cross-platform Capabilities

🔧 Built-in Tools

🎯 Pluggable Skills

🚀 Quick Start

1️⃣ Installation

2️⃣ Configuration

Option 1: Automatic Setup Wizard (Recommended)

Option 2: Manual Configuration

3️⃣ Run

4️⃣ Basic Usage

⏰ Heartbeat Task System

5️⃣ Monitoring Terminal

🏢 Use Cases

🔒 Enterprise Applications

Packages