DuDuClaw

DuDuClaw 🐾

DuDuClaw turns AI command-line tools such as Claude Code, Codex and Antigravity into AI employees who actually deliver: they staff eleven messaging apps like Telegram, LINE, and Discord, an independent judge reviews their work before it ships, and every dollar they spend gets logged.

All you need is one Rust binary. Channel routing, conversation memory, multi-account rotation, behavioral guardrails, local inference, and a web dashboard are built in; swap the AI brain between twelve CLI backends (Claude Code, Codex, Antigravity, Grok and others; Gemini CLI is deprecated) or any OpenAI-compatible API whenever you like, and your config and memory stay on your own machine. The core is Apache 2.0.

[CI] [Version] [npm] [PyPI] [License: Apache-2.0]

Quick start (needs Node.js 20+; prefer a desktop app? see Install):

npm install -g duduclawduduclaw run                  # then open http://localhost:18789

https://github.com/user-attachments/assets/9f18408a-cf46-4db2-9ab0-dcc8db2486fc

Table of contents

• Why DuDuClaw?
• Architecture at a glance
• Prerequisites
• Install
• Quick start
• Feature overview
• CLI commands
• Trust and security
• Comparison
• Documentation
• License

Why DuDuClaw?

If you run claude or gemini in a terminal now and then, the native CLIs are all you need. The moment you want an AI staffing your LINE official account, covering your team's Discord, or running several agents with different jobs, you end up building a whole infrastructure layer yourself. DuDuClaw ships that layer:

Architecture at a glance

The AI runtime is the brain, DuDuClaw is the plumbing, and MCP (JSON-RPC 2.0) is the bridge. Swap the brain, keep the plumbing:

AI Runtime (brain) — Claude Code / Codex / Antigravity / Grok / … (12 CLIs) / OpenAI-compat  ↕ MCP Protocol (JSON-RPC 2.0, stdin/stdout)DuDuClaw (plumbing)  ├─ Channel Router — Telegram / LINE / Discord / Slack / WhatsApp / Feishu  │                    / Google Chat / Microsoft Teams / WeCom / DingTalk / WebChat  ├─ Multi-Runtime — 13 runtime ids (12 CLIs + OpenAI-compat), auto-detected, per agent  ├─ Session Memory — native --resume + temporal memory + key facts + layered wiki  ├─ MCP Server — 247 tools (channels, memory, agents, skills, tasks, wiki, ERP)  ├─ Evolution Engine — prediction-driven + AEE playbook rules + MistakeNotebook  ├─ Security — PolicyKernel reference monitor + OS sandbox + redaction vault  ├─ Inference Engine — OpenAI-compatible local server (llama-server / Ollama / vLLM) / llamafile  ├─ Account Rotator — OAuth + API key rotation, budgets, health checks  └─ Web Dashboard — React 19 SPA, embedded via rust-embed

The Rust workspace is 24 crates: the duduclaw-core foundation, the duduclaw-gateway service layer, the duduclaw-llm unified API layer, duduclaw-inference for local models, duduclaw-memory for cognitive memory, duduclaw-security, and more. Full design in ARCHITECTURE.md.

Experimental calibrated local routing uses Varun Kotte's UCCI (arXiv:2605.18796). See UCCI calibrated cascade for configuration and data preparation.

The same gateway + dashboard also ships as a whole machine: DuDuClaw OS is a Yocto-built appliance image. Its Yocto layer and release pipeline live in their own repo and vendor this repo's Rust workspace as a trimmed snapshot; see the Install section below.

Prerequisites

DuDuClaw doesn't ship its own LLM — you need an AI brain first. Pick one (you can also set this up later in the browser wizard):

• Install one of the supported AI CLIs, such as Claude Code, Codex or Antigravity (the full list is in multi-runtime; Gemini CLI is deprecated and removed in v1.72.0), and give it an API key. Anthropic and Google block consumer subscription tokens used by third-party products, and accounts have been suspended, so an API key is the supported path
• Bring an API key for any OpenAI-compatible provider
• Or run a local model behind an OpenAI-compatible server (llama-server, Ollama, vLLM, llamafile) — no cloud account needed

Install

Desktop app (recommended for personal use)

A native Tauri build that starts the local gateway automatically when you launch it — no terminal required — and shares ~/.duduclaw with the CLI. Download from Releases:

The macOS desktop build is available again from v1.68.1 (signed and notarized). v1.67.0 through v1.68.0 have no macOS build; Windows and Linux builds exist for those versions.

Open it and you're done — the in-app wizard walks you through picking an AI backend and creating your first agent, no commands needed.

npm (advanced / server use, all platforms including Windows)

For running on a server, scripting automation, or if you just prefer the command line. The only prerequisite is Node.js 20+:

npm install -g duduclaw

This installs a prebuilt binary for your platform (macOS ARM64/x64, Linux x64/ARM64, Windows x64). No compiler, no Rust.

⚠️ If the install asks you for Rust / MSVC Build Tools and a 1.5-hour compile, you took a wrong turn. That path is "build from source" for contributors; regular users should use the npm command above.

DuDuClaw OS (appliance image, pre-GA)

If you would rather not dedicate a computer, get a box that runs the moment you plug it in: DuDuClaw OS is a Yocto-built Linux operating system in which the AI agent is a native resident: it boots into its own desktop (compositor / shell, lock screen, Cmd+K delegation bar), so a person and the AI share one x86-64 box without getting in each other's way — the agent's GUI work runs in a shadow workspace by default, and the moment you touch the keyboard or mouse, whatever it was driving on your desktop yields. The desktop edition ships with A/B atomic updates and rollback, a read-only root, and preloaded Chromium / LibreOffice / Steam plus a Chinese IME; Secure Boot signing, dm-verity and TPM2 are build-time overlay options that remain disabled as of the current v0.2.0 release, so boot with Secure Boot turned off in the BIOS/UEFI.

The current release is v0.2.0 (embedding platform v1.63.0; the prior v0.1.0 is kept as a rollback target). Download the whole-disk .wic.zst (desktop edition), the installer-desktop installer .iso (writes the desktop edition), or the plain installer .iso (writes the base image, without the app layer) from DuDuClaw-OS Releases; every file comes with a .sha256 and a minisign signature, and the verification commands are on the OS README on the docs site. This is a bring-up line (0.x): QEMU-verified, not yet booted on real hardware. Hardware requirements and compatible machines: docs/guides/hardware-requirements.md; product overview: docs/features/50-duduclaw-os-appliance.md.

Build from source

Prerequisites: Rust 1.85+, Node.js 20+.

git clone https://github.com/zhixuli0406/DuDuClaw.gitcd DuDuClawcd web && npm ci --legacy-peer-deps && npm run build && cd ..cargo build --release -p duduclaw-cli -p duduclaw-gateway --features duduclaw-gateway/dashboard./target/release/duduclaw run

Python SDK (optional library)

The core gateway/CLI is a Rust binary and needs no Python. The duduclaw package on PyPI is a pure library for import duduclaw (agents / channels / mcp / memory_eval modules) with no command-line entry point, which is why pipx install duduclaw fails by design. If you need it:

pip install duduclaw

Quick start

• Desktop app: just open it — the gateway starts automatically and the wizard appears right inside the app.

• npm / build from source:

  bash

  duduclaw run                  # start everything (gateway + channels + scheduler + dispatcher)open http://localhost:18789   # open the dashboard

Either way, the first visit takes you through a wizard: pick an AI backend, create your first agent, then chat with it in the built-in WebChat — no need to run duduclaw onboard from a terminal first. Later, paste a bot token on the Channels page to put the same agent on Telegram, LINE, Discord, and the rest, without restarting.

Useful next steps:

duduclaw agent create      # create more agentsduduclaw wizard            # industry-template setupduduclaw status            # system health snapshotduduclaw update            # check for and install updatesduduclaw service install   # start on boot (launchd / systemd)

Feature overview

Full feature list in docs/features/feature-inventory.md; version history in CHANGELOG.md.

CLI commands

duduclaw onboard             # first-run setup; the browser wizard covers this now, use for headless/scripted setups (--yes to skip prompts)duduclaw run                 # start everything (gateway + channels + heartbeat + cron + dispatcher)duduclaw agent               # interactive chat; subcommands create / list / inspect / pause / resume / runduduclaw wizard              # industry-template setupduduclaw status              # system health snapshotduduclaw doctor              # diagnosticsduduclaw test <agent>        # red-team security test (9 built-in scenarios)duduclaw eval                # run the agent behavior eval suiteduduclaw update              # check for and install updatesduduclaw service install     # install as a system service; also start / stop / status / logs / uninstallduduclaw export / import     # export / import ~/.duduclaw (portable personal data)duduclaw migrate from openclaw   # painless migration from OpenClaw / Hermes / paperclip (dry-run by default, --apply to write)duduclaw mcp-server          # start the MCP server (stdio JSON-RPC 2.0)duduclaw http-server         # start the MCP HTTP/SSE transport (Bearer auth)duduclaw acp                 # start the Agent Client Protocol server (Zed / JetBrains / Neovim agent panels)duduclaw acp server          # start the A2A server (agent-to-agent interop)duduclaw license             # license management (activate / status / redeem / rebind / …)

Run duduclaw --help for the full command list and subcommands; developer topics are in the development guide.

Trust and security

What you install is fully transparent:

• What's in the npm package: a small JS wrapper plus platform binaries (@duduclaw/<platform> optionalDependencies). postinstall only checks that the platform package is present (install.js); nothing is downloaded from arbitrary URLs or executed
• No telemetry: no usage data or conversation content is sent to us. The gateway checks GitHub Releases for updates every 6 hours; with a paid license installed it also refreshes the license with the license server (every 3–7 days depending on tier) and fetches the revocation list daily. Without a license file there is no licensing traffic. Secrets stay on your machine, encrypted with AES-256-GCM
• No privilege escalation: runs entirely in user space
• Maintainer: DuDu Digital Technology Co., Ltd. (registered in Taiwan, tax ID 94139082)
• High-risk actions in chat: an employee asks for approval of a high-risk computer-use step in its channel, and you answer with the request's full ID. An operation whose result is unknown is never re-sent automatically; an Admin settles it in the dashboard. See the operator guide

Every release asset ships with three kinds of verification: a SHA-256 checksum, a cosign keyless signature, and a minisign Ed25519 signature (the built-in auto-updater enforces this one and refuses unsigned or tampered releases):

# SHA-256shasum -a 256 -c duduclaw-darwin-arm64.tar.gz.sha256
# minisign (the same public key is pinned inside the binary)minisign -Vm duduclaw-darwin-arm64.tar.gz \  -P RWTh5pOpk0YmdBgm3VyB2bzxFtajNLXr7zFDhbcc75TgM8YfeV+NSzXh

Don't trust prebuilt binaries? Building from source takes three commands. Report vulnerabilities via SECURITY.md.

Why does a "new" package start at version 1.3x? DuDuClaw spent months in a private repo (400+ commits) before going public; the full history is in the git log.

Comparison

Documentation

• ARCHITECTURE.md: full system architecture
• docs/README.md: public docs index (architecture / RFC / ADR / specs / guides)
• docs/guides/deployment-guide.md: production deployment (Tailscale / Docker / systemd / auto-update / monitoring)
• docs/guides/development-guide.md: dev environment and agent development
• docs/guides/custom-mcp-tool.md: writing custom MCP tools
• docs/spec: SOUL.md and CONTRACT.toml format specs
• docs/features/50-duduclaw-os-appliance.md: the DuDuClaw OS appliance; 52-desktop-edition.md: the desktop edition, one machine shared by a person and the AI; hardware requirements in hardware-requirements.md; app compatibility, image build and releases all live in the DuDuClaw-OS repo (see its docs/guides/app-compat.md)
• CHANGELOG.md: version history

License

Open core: the core is Apache License 2.0, free to use, modify, and distribute. Commercial add-ons (commercial/, not in this repository), such as the premium industry packs, are closed source and paid; a license key unlocks them. The license-verification client (crates/duduclaw-license) is part of the Apache 2.0 core. See LICENSING.md.

Commercial licenses, enterprise rollout, training and support are provided by our authorised distributor, Future Corp (未來企業股份有限公司). We do not sell directly.

🐾 Built with louis.li