longzhi/clawhive

# clawhive [](https://github.com/longzhi/clawhive/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://www.rust-lang.org/) [](https://github.com/longzhi/clawhive/releases) English | [中文](README_CN.md) 一个开源的、原生 Rust 实现的 [OpenClaw](https://github.com/openclaw/openclaw) 替代方案 —— 使用单一二进制文件跨 Telegram、Discord、Slack、WhatsApp、iMessage 等平台部署你自己的 AI agents。 **单一二进制文件，约 14 MB，零运行时依赖。** 无需 Node.js，无需 npm，无需 Docker —— 只需下载、配置并运行。 ## 安装 ``` curl -fsSL https://raw.githubusercontent.com/longzhi/clawhive/main/install.sh | bash ``` 自动检测操作系统/架构，下载最新版本，将二进制文件和技能安装到 `~/.clawhive/`。 安装完成后，重启你的 shell 或运行： ``` source ~/.zshrc # or ~/.bashrc ``` 或者从 [GitHub Releases](https://github.com/longzhi/clawhive/releases) 手动下载。 ## 设置 使用以下任一方法配置 providers、agents 和 channels： **选项 A: Web 设置向导** — 启动服务器并打开基于浏览器的向导： ``` clawhive start # 在浏览器中打开 http://localhost:3000/setup ``` **选项 B: CLI 设置向导** — 运行交互式终端向导： ``` clawhive setup ``` ## 使用方法 ``` # 设置 / 配置 clawhive setup clawhive validate # 聊天模式 (本地 REPL) clawhive chat # 服务生命周期 clawhive up # start as background daemon (alias for start -d) clawhive start # start in foreground clawhive start --daemon # start as background daemon (alias: -d) clawhive restart clawhive stop # 仪表盘模式 (可观测性 TUI) clawhive dashboard # 代码模式 (开发者 TUI) clawhive code # 代理 / 会话 clawhive agent list clawhive agent show clawhive-main clawhive session reset # 计划 / 任务 clawhive schedule list clawhive schedule run clawhive task trigger clawhive-main "summarize today's work" # 日志 clawhive logs # 认证 clawhive auth status clawhive auth login openai ``` ## CLI 命令 | 命令 | 描述 | |---------|-------------| | `setup` | 交互式配置向导 | | `up` | 作为后台 daemon 启动 (`start -d` 的别名) | | `start [--tui] [--daemon]` | 启动所有配置好的 channel bots 和 HTTP API 服务器 | | `stop` | 停止正在运行的 clawhive 进程 | | `restart` | 重启 clawhive (stop + start) | | `chat [--agent ]` | 用于测试的本地 REPL | | `validate` | 校验 YAML 配置 | | `consolidate` | 手动运行 memory 整合 | | `logs` | 查看最新日志文件的尾部 | | `agent list\|show\|enable\|disable` | Agent 管理 | | `skill list\|show\|analyze\|install` | Skill 管理 | | `session reset ` | 重置会话 | | `schedule list\|run\|enable\|disable\|history` | 定时任务管理 | | `wait list` | 列出后台等待任务 | | `task trigger ` | 向 agent 发送一次性任务 | | `auth login\|status` | OAuth 认证管理 | ## 为什么选择 clawhive？ - **极小占用** — 单一二进制文件，约 14 MB。可在 Raspberry Pi、VPS 或 Mac Mini 上以极低的资源占用运行。 - **设计安全** — 双层安全模型：不可绕过的硬性基线 + 基于来源的信任。外部 skills 必须显式声明权限。 - **有界执行** — 强制执行 token 预算、超时限制和 sub-agent 递归深度。杜绝无限循环，杜绝意外账单。 - **Web + CLI 设置** — 基于浏览器的设置向导或交互式 CLI。在 2 分钟内让第一个 agent 跑起来。 ## 功能特性 - Multi-agent 编排，支持每个 agent 的 personas、model routing 和 memory 策略控制 - 三层 memory 系统：Session JSONL → 每日文件 → MEMORY.md (长期) - Hybrid 搜索：sqlite-vec 向量相似度 + FTS5 BM25 针对 memory chunks - Hippocampus consolidation：周期性 LLM 驱动的综合总结，写入长期 memory - Channel adapters：Telegram, Discord, Slack, WhatsApp, iMessage (多 bot，多 connector) - 带有重复保护和 sub-agent 生成的 ReAct reasoning loop - Skill 系统 (SKILL.md 包含 frontmatter + 权限声明) - 基于令牌桶的每用户 rate limiting - LLM provider 抽象，支持重试 + 指数退避 (Anthropic, OpenAI, Gemini, DeepSeek, Groq, Ollama, OpenRouter, Together, Fireworks，以及任何 OpenAI 兼容的 endpoint) - 实时 TUI 仪表盘和 YAML 驱动的配置 ## 架构 

项目结构

``` crates/ ├── clawhive-cli/ # CLI binary (clap) — start, setup, chat, validate, agent/skill/session/schedule ├── clawhive-core/ # Orchestrator, session mgmt, config, persona, skill system, sub-agent, LLM router ├── clawhive-memory/ # Memory system — file store (MEMORY.md + daily), session JSONL, SQLite index, chunker, embedding ├── clawhive-gateway/ # Gateway with agent routing and per-user rate limiting ├── clawhive-bus/ # Topic-based in-process event bus (pub/sub) ├── clawhive-provider/ # LLM provider trait + multi-provider adapters (streaming, retry) ├── clawhive-channels/ # Channel adapters (Telegram, Discord, Slack, WhatsApp, iMessage) ├── clawhive-auth/ # OAuth and API key authentication ├── clawhive-scheduler/ # Cron-based task scheduling ├── clawhive-server/ # HTTP API server ├── clawhive-schema/ # Shared DTOs (InboundMessage, OutboundMessage, BusMessage, SessionKey) ├── clawhive-runtime/ # Task executor abstraction └── clawhive-tui/ # Real-time terminal dashboard (ratatui) ~/.clawhive/ # Created by install + setup ├── bin/ # Binary ├── skills/ # Skill definitions (SKILL.md with frontmatter) ├── config/ # Generated by `clawhive setup` │ ├── main.yaml # App settings, channel configuration │ ├── agents.d/*.yaml # Per-agent config (model policy, tools, memory, identity) │ ├── providers.d/*.yaml # LLM provider settings │ └── routing.yaml # Channel → agent routing bindings ├── workspaces/ # Per-agent workspace (memory, sessions, prompts) ├── data/ # SQLite databases └── logs/ # Log files ```

安全模型

clawhive 实现了**双层安全架构**以实现深度防御： **硬性基线 (始终强制执行)** | 保护措施 | 阻止内容 | |------------|----------------| | **SSRF 防护** | 私有网络 (10.x, 172.16-31.x, 192.168.x)，loopback，cloud metadata endpoints | | **敏感路径保护** | 写入 `~/.ssh/`、`~/.gnupg/`、`~/.aws/`、`/etc/`，系统目录 | | **私钥保护** | 读取 `~/.ssh/id_*`、`~/.gnupg/private-keys`，cloud credentials | | **危险命令拦截** | `rm -rf /`，fork bombs，磁盘擦除，curl-pipe-to-shell 模式 | | **资源限制** | 30 秒超时，1MB 输出上限，5 个并发执行 | **基于来源的信任模型** | 来源 | 信任级别 | 权限检查 | |--------|-------------|-------------------| | **Builtin** | 受信任 | 仅硬性基线 | | **External** | 沙箱化 | 必须在 SKILL.md frontmatter 中声明所有权限 | 外部 skills 在 SKILL.md 中声明权限： ``` --- name: weather-skill permissions: network: allow: ["api.openweathermap.org:443"] fs: read: ["${WORKSPACE}/**"] exec: [curl, jq] env: [WEATHER_API_KEY] --- ``` 任何超出声明权限的访问都会在运行时被拒绝。

Memory 系统

受神经科学启发的三层架构： 1. **Session JSONL** (`sessions/.jsonl`) — 仅追加的对话日志，类型化条目。用于会话恢复和审计追踪。 2. **每日文件** (`memory/YYYY-MM-DD.md`) — 对话期间由 LLM 写入的每日观察。 3. **MEMORY.md** — 精选的长期知识。由 hippocampus consolidation 更新（LLM 综合近期的每日文件）。 4. **SQLite 搜索索引** — sqlite-vec + FTS5。Hybrid 搜索：向量相似度 × 0.7 + BM25 × 0.3。 注意：JSONL 文件**不**被索引。只有 Markdown memory 文件参与搜索。

``` clawhive start # 在浏览器中打开 http://localhost:8848/setup ```

技术对比 (vs OpenClaw)

| 方面 | clawhive | OpenClaw | |--------|----------|----------| | **Runtime** | 纯 Rust 二进制，嵌入式 SQLite | Node.js runtime | | **安全模型** | 双层策略（硬性基线 + 来源信任） | Tool allowlist | | **权限系统** | 声明式 SKILL.md 权限 | 运行时策略 | | **Memory** | Markdown 原生 (MEMORY.md 为权威来源) | Markdown 原生 (MEMORY.md + memory/*.md) | | **集成面** | Multi-channel (Telegram, Discord, Slack, WhatsApp, iMessage, CLI) | Broad connectors | | **依赖** | 单一二进制文件，无运行时依赖 | Node.js + npm |

### 运行 ``` # 设置 / 配置 clawhive setup clawhive validate # 聊天模式 (本地 REPL) clawhive chat # 服务生命周期 clawhive start clawhive start --daemon # alias: -d clawhive restart clawhive restart --daemon # alias: -d clawhive stop # 仪表盘模式 (可观测性 TUI) clawhive dashboard clawhive dashboard --port 8848 # 代码模式 (开发者 TUI) clawhive code clawhive code --port 8848 # 代理 / 会话 clawhive agent list clawhive agent show clawhive-main clawhive session reset # 计划 / 任务 clawhive schedule list clawhive schedule run clawhive task trigger clawhive-main "summarize today's work" # 认证 clawhive auth status clawhive auth login openai ``` ## 快速开始 (开发者) 前置条件：Rust 1.92+ ``` # 克隆并构建 git clone https://github.com/longzhi/clawhive.git cd clawhive cargo build --workspace # 交互式设置 (配置 providers, agents, channels) cargo run -- setup # 聊天模式 (本地 REPL) cargo run -- chat # 启动所有已配置的频道机器人 cargo run -- start # 作为后台 daemon 启动 cargo run -- start --daemon # alias: -d # 重启 / 停止 cargo run -- restart cargo run -- restart --daemon cargo run -- stop # 仪表盘模式 (可观测性 TUI) cargo run -- dashboard cargo run -- dashboard --port 8848 # 代码代理模式 (将本地 TUI 频道附加到运行中的 gateway) cargo run -- code cargo run -- code --port 8848 ``` ## 开发者工作流 推送前使用本地质量检查： ``` # 一次性：安装 repo 管理的 git hooks just install-hooks # 在本地运行所有 CI 等效检查 just check # 发布流程: check -> push main -> replace tag and push tag just release v0.1.0-alpha.15 ``` 如果你不使用 `just`，直接使用脚本： ``` bash scripts/install-git-hooks.sh bash scripts/check.sh bash scripts/release.sh v0.1.0-alpha.15 ``` `just check` 会运行： 1. `cargo fmt --all -- --check` 2. `cargo clippy --workspace --all-targets -- -D warnings` 3. `cargo test --workspace` ## 配置 配置通过 `clawhive setup` 管理，它会交互式地在 `~/.clawhive/config/` 下生成 YAML 文件： - `main.yaml` — 应用名称，runtime 设置，feature flags，channel 配置 - `agents.d/.yaml` — agent 身份，model 策略，tool 策略，memory 策略 - `providers.d/.yaml` — provider 类型，API base URL，认证信息 - `routing.yaml` — 默认 agent ID，channel 到 agent 的路由绑定 支持的 providers：Anthropic, OpenAI, Gemini, DeepSeek, Groq, Ollama, OpenRouter, Together, Fireworks，以及任何 OpenAI 兼容的 endpoint。 ## 开发

快速开始 (开发者)

前置条件：Rust 1.92+ ``` git clone https://github.com/longzhi/clawhive.git cd clawhive cargo build --workspace cargo run -- setup # Interactive setup cargo run -- chat # Chat mode (local REPL) cargo run -- start # Start all channel bots cargo run -- start -d # Start as background daemon cargo run -- dashboard # Dashboard mode cargo run -- code # Coding agent mode ```

``` # 运行所有测试 cargo test --workspace # Lint cargo clippy --workspace --all-targets -- -D warnings # 格式化 cargo fmt --all # 在本地运行所有 CI 等效检查 just check # 发布 just release v0.1.0-alpha.15 ``` ## 技术栈 | 组件 | 技术 | |-----------|-----------| | 语言 | Rust (2021 edition) | | LLM Providers | Anthropic, OpenAI, Gemini, DeepSeek, Groq, Ollama, OpenRouter, Together, Fireworks | | Channels | Telegram, Discord, Slack, WhatsApp, iMessage, CLI | | 数据库 | SQLite (rusqlite, bundled) | | 向量搜索 | sqlite-vec | | 全文搜索 | FTS5 | | HTTP | reqwest | | Async | tokio | | TUI | ratatui + crossterm | | CLI | clap 4 | ## 许可证 MIT ## 状态 本项目处于活跃开发中。Memory 架构使用 Markdown 原生存储 + Hybrid 检索。

标签：CLI 工具, Discord Bot, IP 地址批量处理, LangChain, LLM 应用, Rust, Slack Bot, Telegram Bot, TUI, Web 仪表盘, 中间件, 人工智能, 企业级, 单文件部署, 即时通讯, 可视化界面, 后台服务, 安全沙箱, 开源, 用户模式Hook绕过, 网络安全, 网络流量审计, 网络调试, 自动化, 轻量级, 通知系统, 隐私保护, 零依赖