CyberClaw Transparent Agent
An enterprise-grade transparent and controllable AI agent: full behavior auditing, two-phase safe invocation, and dual-watermark memory make every decision traceable.
- Source repo
- ttguy0707/CyberClaw
- Stars
- ★ 338
- Last updated
- 1mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 45/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Enterprise teams with compliance requirements that use the 5-category audit logs and JSONL records to trace every LLM decision and tool call
- Not a fit if
- Teams needing Docker or containerized deployment: no deployment docs are provided
- Latency-sensitive workloads that cannot absorb the two-phase invocation overhead
- Source review
- 45/100 · Major gaps
What does this agent do, and when should you use it?
CyberClaw is an open-source, enterprise-grade agent framework built on Python 3.10+, LangChain 1.x, and LangGraph 1.x, focused on eliminating the AI black-box problem. It achieves full traceability through 5-category event auditing (llm_input, tool_call, tool_result, ai_message, system_action), JSONL logs, and a Rich monitoring terminal. Its zero-trust execution uses two-phase skill invocation (help → run), which the repository's own test report says reduces the P0 incident rate from 50% to 10%. Memory uses a dual-watermark design: a long-term profile stored as a Markdown file and short-term summaries in SQLite, with automatic context trimming. It ships CLI commands (cyberclaw run, cyberclaw config, cyberclaw monitor), supports six model providers (OpenAI, Anthropic, Alibaba Cloud, Tencent, Z.AI, Ollama), is compatible with the OpenClaw and Claude Code skill ecosystems, and sandboxes all file operations by default.
After starting with cyberclaw run, the core is a LangGraph StateGraph agent loop in cyberclaw/core/agent.py. It reads the long-term profile at workspace/memory/user_profile.md and short-term conversation history from SQLite, automatically summarizing every 20 turns while keeping the latest 10 to prevent token explosion. Before executing any tool it reads the skill's SKILL.md manual via mode='help', then executes via mode='run', and may change tools after reading the manual. Twelve built-in tools include get_current_time, calculator, schedule_task, save_user_profile, list_office_files, read_office_file, write_office_file, and execute_office_shell; file and shell operations are sandboxed inside workspace/office/, blocking .. and absolute paths, with regex-based dangerous-command interception and a 60-second timeout circuit breaker. A heartbeat process (cyberclaw/core/heartbeat.py) checks the workspace/tasks.json queue every second and triggers daily/weekly/monthly recurring tasks. All events are written as JSONL to logs/local_geek_master.jsonl and viewable live via cyberclaw monitor. Skills are dynamically loaded from workspace/office/skills/, are compatible with OpenClaw and Claude Code skills, and can connect to external MCP services via mcporter.
- Enterprise teams with compliance requirements that use the 5-category audit logs and JSONL records to trace every LLM decision and tool call
- AI safety researchers studying agent safety boundaries using the two-phase invocation mechanism and the experiment data in tests/logs/test_two_phase_skills.md
- Developers deploying across Windows/Linux/macOS who want the LLM to autonomously choose PowerShell or Bash commands from one codebase
- Individuals or teams needing scheduled automation, using the heartbeat system to run reminders and meetings on daily/weekly/monthly cycles
- Developers who want fast tool integration by reusing OpenClaw and Claude Code ecosystem skills directly, or generating new skills with skill-creator in natural language
- Instructors teaching AI agents, using the transparent monitoring terminal to demonstrate agent architecture and decision flows
How do you install or deploy this agent?
- Clone and install:
git clone https://github.com/ttguy0707/CyberClaw.git
cd CyberClawpip install -e .
(Run inside a Python 3.10+ virtual environment; pip installs requirements.txt dependencies and registers the cyberclaw command.)
- Configure a model provider (choose one):
- Wizard: run cyberclaw config, pick a provider (openai / anthropic / aliyun / tencent / z.ai / ollama), enter your API key and optional Base URL; the wizard tests the connection automatically.
- Manual: cp .env.example .env, then edit to set DEFAULT_PROVIDER, DEFAULT_MODEL (e.g. gpt-4o-mini, glm-5, qwen-max), OPENAI_API_KEY or ANTHROPIC_API_KEY, and if needed OPENAI_API_BASE or OLLAMA_BASE_URL (default http://localhost:11434).
- First check: run cyberclaw run to verify chat connectivity.
How do you use this agent?
Main program: cyberclaw run opens an interactive chat. Give instructions in natural language, e.g. "What time is it now?", "Calculate 25 times 48", "Remind me to drink water every morning at 8", "Show me the files in office", "Run python test.py"; exit with /exit. Monitoring: run cyberclaw monitor in another terminal to watch LLM input, tool calls, tool results, AI replies, and system actions; or inspect audit logs with tail -f logs/local_geek_master.jsonl or grep "tool_call" logs/local_geek_master.jsonl. Installing skills: copy a skill directory into workspace/office/skills/, or install skill-creator and ask CyberClaw to create skills in natural language, or use skill-vetter to check skill safety. Scheduled tasks: create one-shot or daily/weekly/monthly recurring tasks via conversation; tasks persist in workspace/tasks.json across restarts. Tests: python3 -m pytest tests/ -v.
What are this agent's strengths and limitations?
- Full behavior auditing: 5-category JSONL event logs plus a Rich monitoring terminal make every LLM decision and tool call traceable — a concrete differentiator most peer frameworks lack
- The two-phase help → run invocation is backed by reproducible in-repo experiment data: safety hit rate 50% → 90%, P0 incident rate 50% → 10%, for only 23.5% extra decision latency
- Concrete, auditable sandbox security: path-interception (blocks .., absolute paths, home directory access), regex-based dangerous command blocking, and a 60-second timeout circuit breaker
- Model-agnostic: adapters for OpenAI, Anthropic, Alibaba Cloud, Tencent, Z.AI, and Ollama; local Ollama enables fully offline model inference
- Directly reuses skills from both the OpenClaw and Claude Code ecosystems, plus MCP integration via mcporter/mcp-builder
- Two-phase invocation adds ~23.5% average decision latency (19.33s → 23.88s), a real cost for latency-sensitive workloads
- The repository's test report is author-reported; sample size and methodology are not detailed in the README, so the safety gains should be independently verified
- All file and shell operations are forcibly confined to the workspace/office/ sandbox; existing toolchains needing paths outside it require rework
- Depends on the LangChain 1.x / LangGraph 1.x ecosystem, which carries upgrade and compatibility maintenance costs
- No additional deployment documentation (e.g., Docker/container packaging), so enterprise deployment requires building the environment yourself
How does this agent compare with similar options?
The README states CyberClaw was inspired by OpenClaw, differing in its focus on transparency and controllability for AI agents, and it stays compatible with both the OpenClaw and Claude Code skill ecosystems.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| CyberClaw Transparent Agent This agent | 45 · Major gaps | CLIFree + model costs | ★ 338 | 1mo ago | Python | OpenAI API · Claude API |
| Dive into LangGraph | 69 · Some gaps | Library / SDKFree + model costs | ★ 461 | 1mo ago | Jupyter Notebook | Claude Code |
| Deep Agents in Action | 39 · Major gaps | CLIFree + model costs | ★ 2.8k | today | Jupyter Notebook | OpenAI API · Claude API |
| AI Agent Engineering Textbook | 55 · Major gaps | FrameworkFree | ★ 612 | 6d ago | HTML | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Path sandbox (office/ confinement, '..' and absolute-path blocking) and regex-based dangerous-command blocking are claimed, but the sandbox implementation files were not provided; the claims rest on README alone and regex blacklists are inherently weak — clear deduction. No user-confirmation gate before writes or shell execution is described; the tool table shows the LLM can run shell commands and overwrite the user profile directly (1). Five-category JSONL auditing plus a Rich monitor terminal are concretely described, scoring 2. API keys in .env and personal-preference profile data have no encryption or minimization notes; dependencies are all lower-bound (>=) with no lockfile or hashes; shell execution, a background heartbeat process, and external curl skills are real external effects without confirmation evidence; only partial rollback via 'reconsider after help' and task delete/modify tools; source attribution thanks OpenClaw/LangChain with links but no SECURITY or contributor files (1).
Self-contradiction in README: tables claim P0 incidents drop 50%→10% (-80%) while the test-conclusion paragraph says incidents 'plummet to 0%' — same data, two figures, scored 1. Dependencies are declared but badges say LangGraph 1.x while requirements say langgraph>=0.1.0; availability claims are unverifiable. Tests show tools return clear Chinese error messages for invalid times, division by zero, and unsafe expressions, scoring 2.
Five audiences (enterprise, R&D, cross-platform, education, personal) are well described (2). Claims of OpenClaw and Claude Code skill-ecosystem compatibility carry no compatibility spec or verification evidence, and boundaries (network isolation, multi-user) are unstated (1). Heartbeat triggers and recurrence are described, but timezone and missed-fire semantics are undefined. Cross-platform handling (paths, env vars, dual shells) is concrete (2).
Clear project structure, module table, and bilingual navigation (2); install covers clone → pip install -e . → wizard or manual .env with venv advice (2); naming (cyberclaw, office, SKILL.md) is consistent; examples are abundant but there is no FAQ or troubleshooting section; no known-limitations or risk disclosure at all — 0; MIT license file complete and consistent — 3; versioning is a lone 1.0.0 badge with no CHANGELOG — 1; single unverified maintainer with no release or support path stated — 1.
Output artifacts (JSONL logs, monitor terminal, chat UI) are described well enough to use (2). The transparency-first positioning is somewhat differentiated, but LangGraph already ships checkpointing/tracing and the incremental value is unargued (1); the cost-benefit claim rests on a single self-reported number (+23.5% latency for -80% incidents) with no visible methodology (1).
The P0 figure cites tests/logs/test_two_phase_skills.md, which is not among the provided files; the baseline definition, sample, and methodology are not traceable (1). The 'Tests Passing' badge cannot be corroborated for the referenced-but-unseen test files, and README badge versions conflict with requirements.txt (1). Marketing conclusions ('plummets to 0%', 'enterprise-grade') are mixed with facts without separating evidence from inference (1).
- The security sandbox and command blocking are README-only claims with no implementation code provided; regex blacklists are easily bypassed — do not trust the isolation in uncontrolled environments.
- The headline '-80% P0 incident' claim comes from a self-reported experiment file not included here, and the README contradicts itself (10% vs 0%) — do not base procurement decisions on it.
- No human-confirmation gate before shell execution or file writes; the LLM can run commands and overwrite the user profile directly.
- All dependencies are open-ended lower bounds with no lockfile; badge versions conflict with requirements.txt — assess supply-chain risk yourself.
- Dynamically loading third-party skills (OpenClaw / Claude Code ecosystems) means executing unaudited external instructions; review SKILL.md and its commands first.
- No known-limitations disclosure, no CHANGELOG, and no stated maintenance commitment; evaluate long-term maintenance risk before adoption.