DuDuClaw 🐾

<div align="center">

繁體中文 · English · 日本語

</div>

DuDuClaw 把 Claude Code、Codex、Gemini 這些 AI 指令列工具,接上 Telegram、LINE、Discord 等九個通訊平台,變成一個 24 小時值班、會記得你、會自我改進的 AI 助理。

你只需要一個 Rust binary。通道路由、對話記憶、多帳號輪替、行為安全邊界、本地推論、Web 管理後台全部內建;AI 大腦要用 Claude、Codex、Gemini、Antigravity 還是任何 OpenAI 相容 API 隨你換,設定和記憶都留在你自己的機器上。核心採 Apache 2.0 授權。

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

目錄

• 為什麼需要 DuDuClaw?
• 架構一覽
• 環境準備
• 安裝
• 快速開始
• 功能總覽
• CLI 指令
• 信任與安全
• 競品對比
• 文件
• 授權

<a id="why"></a>

為什麼需要 DuDuClaw?

偶爾在終端機裡跑 claude 或 gemini,原生 CLI 就夠了。想讓 AI 進駐你的 LINE 官方帳號、幫團隊在 Discord 值班、或是同時管理多個各有分工的 agent,你就得自己蓋一整層基礎設施。DuDuClaw 把這層蓋好了:

| 需求 | 原生 CLI | DuDuClaw | |---|---|---| | 接上 Telegram / LINE / Discord | 只能在終端機用 | 9 個通道,per-agent bot token | | 多 LLM 容錯切換 | 手動重啟 | 4 種輪替策略 + 跨供應商 failover | | 換 LLM 時保留上下文 | 遺失 | 完整保留 | | 對話記憶與知識庫 | 單次 session | SQLite 時態記憶 + 分層 wiki + 自動注入 | | 工具跨 LLM 共用 | 每家重寫 | 130+ MCP 工具寫一次,五種後端共用 | | 安全邊界 / 稽核 / 密鑰管理 | 自己造 | 政策核心 + OS 沙箱 + AES-256-GCM 內建 |

<a id="architecture"></a>

架構一覽

AI 運行時是大腦,DuDuClaw 是水電管線,中間用 MCP(JSON-RPC 2.0)橋接。大腦可換,管線不動:

AI Runtime (brain) — Claude Code / Codex / Gemini / Antigravity / OpenAI-compat
  ↕ MCP Protocol (JSON-RPC 2.0, stdin/stdout)
DuDuClaw (plumbing)
  ├─ Channel Router — Telegram / LINE / Discord / Slack / WhatsApp / Feishu
  │                    / Google Chat / Microsoft Teams / WebChat
  ├─ Multi-Runtime — 5 種後端自動偵測,per-agent 設定
  ├─ Session Memory — 原生 --resume + 時態記憶 + key-fact 累積 + 分層 wiki
  ├─ MCP Server — 130+ 工具(通訊、記憶、Agent、Skill、任務、知識庫、ERP)
  ├─ Evolution Engine — 預測驅動 + AEE playbook 進化(v3 預設) + MistakeNotebook
  ├─ Security — PolicyKernel reference monitor + OS 沙箱 + redaction vault
  ├─ Inference Engine — llama.cpp / mistral.rs / Exo P2P / llamafile / MLX
  ├─ Account Rotator — 多 OAuth + API Key 輪替、預算追蹤、健康檢查
  └─ Web Dashboard — React 19 SPA(32 頁),rust-embed 嵌入 binary

Rust workspace 由 20 個 crate 組成:核心地基 duduclaw-core、服務層 duduclaw-gateway、統一 API 層 duduclaw-llm、本地推論 duduclaw-inference、認知記憶 duduclaw-memory、安全層 duduclaw-security 等。完整設計見 ARCHITECTURE.md。

<a id="prerequisites"></a>

環境準備

DuDuClaw 本身不含 LLM,需要一個 AI 大腦。五選一(之後也能在瀏覽器引導中設定):

• 裝好 Claude Code、Codex、Gemini CLI 或 Antigravity 其中之一並登入
• 準備一把 API key,走任何 OpenAI 相容供應商
• 或用本地 GGUF 模型,不需要任何雲端帳號

<a id="install"></a>

安裝

桌面應用程式(個人使用推薦)

Tauri 原生桌面版,啟動應用程式時會自動拉起本機 Gateway,全程免碰終端機,與 CLI 共用 ~/.duduclaw。到 Releases 下載:

| 平台 | 檔案 | 備註 | |------|------|------| | macOS(Apple Silicon / Intel) | DuDuClaw_*.dmg | 已簽章 + Apple 公證,直接開 | | Windows x64 | DuDuClaw_*_x64_en-US.msi | 未購買 Authenticode 憑證,SmartScreen 會示警;點「更多資訊」→「仍要執行」即可安裝,解鎖細節見 docs/guides/desktop-unblock.md | | Linux | *_amd64.AppImage / .deb | 免簽 |

裝好打開就是完整體驗——啟動精靈會在應用程式內帶你設定 AI 後端與第一個 agent,不需要另外跑指令。

npm(進階 / 伺服器用途,所有平台含 Windows)

想在伺服器上跑、寫腳本自動化,或單純習慣命令列,可以改用 npm。前置需求只有 Node.js 20+:

npm install -g duduclaw

會自動安裝對應平台的預編譯 binary(macOS ARM64/x64、Linux x64/ARM64、Windows x64),免編譯器、免 Rust。

⚠️ 如果安裝過程要求你裝 Rust / MSVC Build Tools 並編譯 1.5 小時,代表走錯路徑了。那是給貢獻者的「從原始碼建構」;一般使用請用上面的 npm 指令。

從原始碼建構

前置需求:Rust 1.85+、Node.js 20+。

git clone https://github.com/zhixuli0406/DuDuClaw.git
cd DuDuClaw
cd 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(選用函式庫)

核心 gateway / CLI 是 Rust binary,不需要 Python。PyPI 上的 duduclaw 是給 import duduclaw 用的純函式庫(agents / channels / mcp / memory_eval 模組),沒有命令列工具,所以 pipx install duduclaw 會失敗是預期行為。需要時:

pip install duduclaw

<a id="quickstart"></a>

快速開始

• 桌面版:直接開啟應用程式,Gateway 會自動啟動,應用程式內會直接顯示引導精靈。

• npm / 原始碼安裝:

  duduclaw run                  # 啟動(gateway + 通道 + 排程 + dispatcher 一次拉起)
  open http://localhost:18789   # 打開管理後台
  

無論走哪條路,第一次打開都會進入引導精靈,所有設定都在瀏覽器裡完成:選 AI 後端 → 建立第一個 agent → 直接在內建 WebChat 對話,不必先在終端機跑 duduclaw onboard。之後到 Channels 頁貼上 bot token,就能把同一個 agent 接上 Telegram、LINE、Discord 等平台,不用重啟。

常用的下一步:

duduclaw agent create      # 建立更多 agent
duduclaw wizard            # 產業模板互動式設定
duduclaw status            # 系統健康快照
duduclaw update            # 檢查並安裝新版本
duduclaw service install   # 開機自動啟動(launchd / systemd)

<a id="features"></a>

功能總覽

| 領域 | 內建能力 | 深入閱讀 | |------|----------|----------| | 通訊通道 | 9 通道(Telegram / LINE / Discord + 語音 / Slack / WhatsApp / Feishu / Google Chat / Teams / WebChat),per-agent bot、熱啟停、平台原生排版、輸入中指示、長任務進度看板 | docs/features | | Multi-Runtime | Claude / Codex / Gemini / Antigravity / OpenAI-compat 五後端,自動偵測、per-agent 設定、換後端保留上下文 | ARCHITECTURE.md | | 統一 LLM API 層 | duduclaw-llm 用一套正規化請求覆蓋 4 種原生協定(Anthropic Messages / OpenAI Responses / Gemini / OpenAI-compat),內建 8 個 OpenAI-compat preset(DeepSeek / MiniMax / Groq / Together / Mistral / OpenRouter / xAI / Qwen)+ 計價 registry + 跨供應商 fallback | ARCHITECTURE.md | | MCP Server | 138 個工具:通訊、記憶、agent 編排、skill 市場、任務看板、共享 wiki、Odoo ERP、computer use、live forking;stdio 與 HTTP/SSE 雙 transport,對外只暴露 7 個白名單工具 | docs/api | | 記憶系統 | SQLite 時態記憶(事實取代鏈)、HippoRAG-lite 知識圖譜檢索(Personalized PageRank)、Ebbinghaus 遺忘曲線自動封存、跨 agent 共享 wiki | docs/features | | 自我進化 | 預測驅動(約 90% 對話零 LLM 成本)、AEE playbook 進化(v3 預設,SOUL.md 對 agent 唯讀,行為規則獨立驗證 + 條目級觀察窗回滾)、MistakeNotebook 跨回合記憶;GVU² SOUL.md 整份改寫降為選配逃生門 | evolution-engine.md | | 安全 | PolicyKernel reference monitor(零 LLM、fail-closed)、macOS Seatbelt / Linux Landlock 原生沙箱、Docker / Apple Container / WSL2 容器沙箱、secret redaction vault、CONTRACT.toml 行為契約 + 紅隊測試 | SECURITY.md | | 帳號與成本 | 多 OAuth + API Key 輪替(4 策略)、rate-limit / 帳單冷卻、成本遙測與快取效率分析、跨平台 PTY pool 驅動 OAuth 訂閱帳號 | docs/features | | 本地推論 | llama.cpp(Metal/CUDA/Vulkan)/ mistral.rs / Exo P2P / llamafile / MLX,三層信心路由自動分流;內建 Whisper 語音辨識與向量嵌入 | docs/features | | Live Forking | RFC-26:把進行中的任務分叉成 N 個競爭分支,各自 copy-on-write 隔離、AI judge 選勝者合併(預設關閉) | docs/rfc | | 自動更新 | Dashboard 一鍵更新或背景自動更新(auto_update = true),SHA-256 + Ed25519 雙重驗證後原地重啟,前台分頁自動重載 | deployment-guide.md | | Web Dashboard | React 19 + TypeScript SPA 32 頁,嵌入 binary 零額外部署;zh-TW / en / ja 三語 | docs/features | | ERP 整合 | Odoo 中間層 15 個 MCP 工具(CRM / 銷售 / 庫存 / 會計),CE/EE 自動偵測、per-agent 認證隔離 | docs/rfc |

完整功能清單見 docs/features/feature-inventory.md,版本演進見 CHANGELOG.md。

<a id="cli"></a>

CLI 指令

duduclaw onboard             # 首次設定;瀏覽器引導已涵蓋,此為無頭/腳本場景用(--yes 跳過互動)
duduclaw run                 # 一鍵啟動(gateway + channels + heartbeat + cron + dispatcher)
duduclaw agent               # CLI 互動式對話;子指令 create / list / inspect / pause / resume / run
duduclaw wizard              # 產業模板互動式設定
duduclaw status              # 系統健康快照
duduclaw doctor              # 健康診斷
duduclaw test <agent>        # 紅隊安全測試(9 項內建場景)
duduclaw eval                # 執行 agent 行為 eval 套件
duduclaw update              # 檢查並安裝更新
duduclaw service install     # 安裝為系統服務;另有 start / stop / status / logs / uninstall
duduclaw export / import     # 匯出 / 匯入 ~/.duduclaw(個人版資料可攜)
duduclaw migrate-from openclaw   # 從 OpenClaw / Hermes / paperclip 無痛轉移(預設 dry-run,--apply 落地)
duduclaw mcp-server          # 啟動 MCP Server(stdio JSON-RPC 2.0)
duduclaw http-server         # 啟動 MCP HTTP/SSE Transport(Bearer 認證)
duduclaw acp-server          # 啟動 ACP/A2A Server(Zed / JetBrains / Neovim 整合)
duduclaw license             # 授權管理(activate / status / redeem / rebind / …)

完整 26 個指令與所有子指令用 duduclaw --help 查看,開發者相關見 development-guide.md。

<a id="trust"></a>

信任與安全

你安裝的東西完全透明:

• npm 套件內容:一個小型 JS wrapper 加上平台 binary(@duduclaw/<platform> optionalDependencies)。postinstall 只檢查平台套件是否就位(install.js),沒有任何「從任意 URL 下載並執行」的行為
• 無遙測:零 phone-home 連線;所有密鑰以 AES-256-GCM 留在你的機器
• 不需特權:完全在 user space 執行
• 維護者:嘟嘟數位科技有限公司(台灣登記公司,統編 94139082)

每個 Release 資產都附三種驗證:SHA-256 checksum、cosign keyless 簽章、minisign Ed25519 簽章(內建自動更新器會強制驗證,拒絕未簽章或被竄改的版本):

# SHA-256
shasum -a 256 -c duduclaw-darwin-arm64.tar.gz.sha256

# minisign(公鑰同時內建於 binary)
minisign -Vm duduclaw-darwin-arm64.tar.gz \
  -P RWTh5pOpk0YmdBgm3VyB2bzxFtajNLXr7zFDhbcc75TgM8YfeV+NSzXh

不信任預編譯 binary?從原始碼建構三行指令就好。漏洞回報見 SECURITY.md。

為什麼「新」套件版本號已經 1.3x?DuDuClaw 公開前在私有 repo 開發了數月(400+ commits),完整歷史都在 git log。

<a id="comparison"></a>

競品對比

| | DuDuClaw | OpenClaw | IronClaw | Dify | |---|---|---|---|---| | 語言 | Rust | TypeScript | Rust | Python | | 通道 | 9 | 25+ | 8 | 0(API)| | Multi-Runtime | 5 後端 | 單一 | 單一 | 多 LLM | | MCP Server | 138 工具 | 無 | 無 | 無 | | 自我進化引擎 | GVU² 雙迴圈 | 無 | 無 | 無 | | 本地推論 | 5 後端 + 信心路由 | 無 | 無 | 無 | | 行為契約 | CONTRACT.toml + 紅隊 | 無 | WASM 沙箱 | 無 | | 授權 | Apache 2.0(Open Core)| MIT | 開源 | $59+/月 |

<a id="docs"></a>

文件

• ARCHITECTURE.md:完整系統架構
• docs/README.md:公開文件索引(架構 / RFC / ADR / 規格 / 指南)
• docs/guides/deployment-guide.md:生產部署(Tailscale / Docker / systemd / 自動更新 / 監控)
• docs/guides/development-guide.md:開發環境與 agent 開發
• docs/guides/custom-mcp-tool.md:自訂 MCP 工具教學
• docs/spec:SOUL.md 與 CONTRACT.toml 格式規範
• CHANGELOG.md:版本變更紀錄

<a id="license"></a>

授權

Open Core 模式:核心程式碼採 Apache License 2.0,自由使用、修改、分發。商業加值模組(commercial/)為閉源付費,含產業模板、企業儀表板與授權驗證,詳見 LICENSING.md。

<p align="center"> 🐾 Built with louis.li </p>