Skip to content
Back to search

ClawSwarm

A smaller, lighter-weight version of OpenClaw, natively multi-agent, compiles to Rust, and built on the Swarms framework and Swarms ecosystem. One API, unified messaging across Telegram, Discord, and WhatsApp with optional Claude-powered reasoning.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/the-swarm-corporation--clawswarm/badge.svg)](/listings/the-swarm-corporation--clawswarm)

HTML

<a href="/listings/the-swarm-corporation--clawswarm"><img src="/api/listings/the-swarm-corporation--clawswarm/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip3 install -U claw-swarm

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 392 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ClawSwarm
  2. ![Banner image](images/bg.png)
  3. <p align="center">
  4. <a href="https://pypi.org/project/claw-swarm/" target="_blank">
  5. <picture>
  6. <source srcset="https://img.shields.io/pypi/v/swarms?style=for-the-badge&color=3670A0" media="(prefers-color-scheme: dark)">
  7. <img alt="Version" src="https://img.shields.io/pypi/v/claw-swarm?style=for-the-badge&color=3670A0">
  8. </picture>
  9. </a>
  10. <a href="https://pypi.org/project/claw-swarm/" target="_blank">
  11. <picture>
  12. <source srcset="https://img.shields.io/pypi/dm/swarms?style=for-the-badge&color=3670A0" media="(prefers-color-scheme: dark)">
  13. <img alt="Downloads" src="https://img.shields.io/pypi/dm/claw-swarm?style=for-the-badge&color=3670A0">
  14. </picture>
  15. </a>
  16. <a href="https://twitter.com/swarms_corp/">
  17. <picture>
  18. <source srcset="https://img.shields.io/badge/Twitter-Follow-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white" media="(prefers-color-scheme: dark)">
  19. <img src="https://img.shields.io/badge/Twitter-Follow-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white" alt="Twitter">
  20. </picture>
  21. </a>
  22. <a href="https://discord.gg/EamjgSaEQf">
  23. <picture>
  24. <source srcset="https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white" media="(prefers-color-scheme: dark)">
  25. <img src="https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord">
  26. </picture>
  27. </a>
  28. </p>
  29. **ClawSwarm** is a multi-agent personal productivity operating system powered by hundreds of agents designed to enhance your productivity.
  30. ---
  31. ## Requirements
  32. - Python 3.10+
  33. - Dependencies listed in `requirements.txt` (no version pins; use a venv and pin locally if needed)
  34. - [Swarms](https://github.com/kyegomez/swarms) framework and Swarms ecosystem; [Claude Code](https://docs.anthropic.com/en/docs/build-with-claude/claude-code) (for the Claude tool)
  35. - Platform credentials for the channels you enable: Telegram Bot Token, Discord Bot Token and Channel IDs, and/or WhatsApp Cloud API credentials
  36. ---
  37. ## Installation
  38. ```bash
  39. pip3 install -U claw-swarm
  40. ```
  41. ---
  42. ## Environment variables
  43. Set these in your shell or in a `.env` file (e.g. `--env-file .env` with Docker). Omit a platform’s credentials to disable that channel.
  44. | Variable | Purpose | Default |
  45. |----------|---------|---------|
  46. | **Gateway** | | |
  47. | `GATEWAY_HOST` | Bind address (gateway) or gateway host (agent) | `[::]` (server), `localhost` (agent) |
  48. | `GATEWAY_PORT` | gRPC port | `50051` |
  49. | `GATEWAY_TLS` | Enable TLS: `1`, `true`, or `yes` | - |
  50. | `GATEWAY_TLS_CERT_FILE` | Path to TLS certificate file | - |
  51. | `GATEWAY_TLS_KEY_FILE` | Path to TLS private key file | - |
  52. | **Channels** | | |
  53. | `TELEGRAM_BOT_TOKEN` | Telegram Bot API token | - |
  54. | `DISCORD_BOT_TOKEN` | Discord bot token | - |
  55. | `DISCORD_CHANNEL_IDS` | Comma-separated Discord channel IDs | - |
  56. | `WHATSAPP_ACCESS_TOKEN` | WhatsApp Cloud API access token | - |
  57. | `WHATSAPP_PHONE_NUMBER_ID` | WhatsApp Cloud API phone number ID | - |
  58. | `WHATSAPP_QUEUE_PATH` | Optional WhatsApp queue path | - |
  59. | **Agent** | | |
  60. | `AGENT_MODEL` | Swarms director / default agent model | `gpt-4o-mini` |
  61. | `WORKER_MODEL_NAME` | Worker agents model (Response/Search/TokenLaunch/Developer). If set, overrides `AGENT_MODEL` for workers. | - (falls back to `AGENT_MODEL` then `gpt-4o-mini`) |
  62. | `OPENAI_API_KEY` | OpenAI API key (for agent model) | - |
  63. | `ANTHROPIC_API_KEY` | Anthropic API key (for Claude tool) | - |
  64. | **Memory** | | |
  65. | `AGENT_MEMORY_FILE` | Agent memory markdown filename (project root) | `agent_memory.md` |
  66. | `AGENT_MEMORY_MAX_CHARS` | Max characters of memory to load into context | `100000` |
  67. ---
  68. ## Quick Start
  69. **1. Install:**
  70. ```bash
  71. pip install -U claw-swarm
  72. ```
  73. **2. Create your config** - run the interactive wizard to generate `claw_config.yaml`:
  74. ```bash
  75. clawswarm onboarding
  76. ```
  77. Press **Enter** to accept defaults. This writes `claw_config.yaml` to your project root with gateway host/port/TLS, HTTP API port/key, agent name, worker model, and verbose mode.
  78. **3. Set secrets** - copy `.env.example` to `.env` and fill in your credentials:
  79. ```bash
  80. cp .env.example .env
  81. # then edit .env with your tokens and API keys
  82. ```
  83. **4. Run the full stack:**
  84. ```bash
  85. clawswarm run # gateway + agent (messaging platforms only)
  86. clawswarm run --api # + public REST API on the configured port
  87. ```
  88. ---
  89. ## Overview
  90. ClawSwarm is a streamlined, multi-agent alternative to OpenClaw. It delivers **natively multi-agent** AI that responds to users on Telegram, Discord, and WhatsApp through a centralized **Messaging Gateway**. The gateway normalizes incoming messages; the **ClawSwarm Agent** (Swarms framework, configurable system prompt, Claude as a tool) processes each message and replies via a **Replier** back to the originating channel. Built on the Swarms ecosystem for reliability, security, and minimal operational overhead-with a path to **compile to Rust** for performance and deployment flexibility.
  91. ---
  92. ## Features
  93. | Feature | Description |
  94. |-----------------------------------|-------------|
  95. | **Multi-channel messaging** | One API for Telegram, Discord, and WhatsApp. The gateway normalizes messages; the agent replies back to the correct channel. |
  96. | **Hierarchical multi-agent architecture** | A **director** agent (ClawSwarm) receives each message, creates a plan, and delegates to specialist **worker** agents via structured orders (SwarmSpec). Workers handle response, search, token launch, or code; the director orchestrates and the **Telegram Summarizer** turns combined output into a concise, emoji-free reply for chat. |
  97. | **Specialist workers** | **ClawSwarm-Response** (greetings, short answers), **ClawSwarm-Search** (web/semantic search via Exa), **ClawSwarm-TokenLaunch** (launch tokens and claim fees on Swarms World/Solana), **ClawSwarm-Developer** (implementation and debugging via Claude Code). Each worker has a focused role and tools; the director chooses who does what. |
  98. | **Claude as a tool** | Deep reasoning and code are handled by Claude (e.g. via the Developer worker’s `run_claude_developer`). Configurable system prompts in `claw_swarm.prompts`; override with `create_agent(system_prompt=...)`. |
  99. | **Unified gRPC gateway** | Single ingest API for all channels; add or remove platforms without changing agent logic. Optional TLS, health checks, and normalized `UnifiedMessage` schema. |
  100. | **Lighter than OpenClaw** | Smaller footprint and simpler stack; same multi-channel, multi-agent vision without the full OpenClaw surface area. Path to compile to Rust for performance and deployment flexibility. |
  101. | **Production-ready** | Environment-based configuration, long-running agent loop, Dockerfile, and 24/7 operation under systemd or managed runtimes. |
  102. ---
  103. ## Architecture
  104. ```
  105. Telegram Discord WhatsApp
  106. \ | /
  107. \ v /
  108. +--------------+
  109. | Gateway | unified ingest (gRPC)
  110. +------+-------+
  111. |
  112. v
  113. +--------------+
  114. | Agent | Hierarchical Swarm + Summarizer
  115. +------+-------+
  116. |
  117. v
  118. +--------------+
  119. | Replier | send back to each channel
  120. +------+-------+
  121. |
  122. Telegram Discord WhatsApp
  123. ```
  124. ClawSwarm starts with a gRPC gateway that ingests messages from Telegram, Discord, and WhatsApp, normalizing each into a unified schema. An agent runner polls the gateway on a short cadence, pulling new messages in batches and maintaining its own cursor for reliable delivery without an external broker.
  125. Each message is routed into a hierarchical multi-agent system: a director agent plans and delegates to specialist workers covering simple responses, web search, token operations, and code execution then a summarizer agent condenses the combined output into a clean, concise reply. That reply is delivered back to the originating platform and channel, and the full interaction is saved to a shared memory file so context persists across all channels and restarts.
  126. ### Hierarchical architecture
  127. The core of ClawSwarm is a **hierarchical multi-agent system** built on Swarms’ `HierarchicalSwarm`. A single **director** agent sits at the top: it receives every user message, decides what to do, and delegates to one or more **worker** agents by emitting structured **SwarmSpec** orders (plan + task assignments). Workers are specialists with narrow roles and tools; they run their tasks and return results. The director does not execute tools itself-it only plans and delegates. After the swarm finishes, a dedicated **Telegram Summarizer** agent condenses the raw output into a short, plain-text reply suitable for chat (no emojis).
  128. This design keeps the director focused on orchestration and intent, while search, code, token operations, and simple replies are handled by the right worker. You get multi-agent behavior with a clear chain of responsibility and a single, chat-friendly response to the user.
  129. ### Hierarchical swarm
  130. ```mermaid
  131. flowchart TB
  132. subgraph swarm["Hierarchical Swarm"]
  133. DIR[Director\nClawSwarm]
  134. DIR --> W0[ClawSwarm-Response]
  135. DIR --> W1[ClawSwarm-Search]
  136. DIR --> W2[ClawSwarm-TokenLaunch]
  137. DIR --> W3[ClawSwarm-Developer]
  138. end
  139. USER[User message] --> DIR
  140. W0 --> OUT[Swarm output]
  141. W1 --> OUT
  142. W2 --> OUT
  143. W3 --> OUT
  144. OUT --> SUM[Telegram Summarizer]
  145. SUM --> REPLY[Reply to user]
  146. ```
  147. - **Director (ClawSwarm):** Receives the user message, creates a plan, and outputs **SwarmSpec** (structured plan + orders) so the swarm runtime can invoke the right workers. No tools; orchestration only.
  148. - **Workers:** Execute the assigned tasks (response, search, token launch, or code) and contribute to the combined swarm output.
  149. - **Telegram Summarizer:** Post-processes the swarm output into a concise, emoji-free reply for the channel.
  150. ### Agents
  151. | Agent | Role | Tools / capabilities |
  152. |-------|------|----------------------|
  153. | **ClawSwarm** (Director) | Orchestrator; creates a plan and assigns tasks to workers via SwarmSpec. Does not run tools itself. | Plan + orders (structured output for the swarm). |
  154. | **ClawSwarm-Response** | Simple replies and general questions; greetings, short factual answers, clarifications. | None (LLM only). |
  155. | **ClawSwarm-Search** | Web and semantic search. | `exa_search` - current events, research, fact-checking. |
  156. | **ClawSwarm-TokenLaunch** | Launch tokens and claim fees on Swarms World (Solana). | `launch_token`, `claim_fees`. |
  157. | **ClawSwarm-Developer** | Code, refactor, debug, and implement via Claude Code. | `run_claude_developer` (Read, Write, Edit, Bash, Grep, Glob, etc.). |
  158. | **ClawSwarm-TelegramSummarizer** | Summarize swarm output for chat; plain text, no emojis. | None (LLM only). |
  159. Worker agents are created in `claw_swarm.agent.worker_agents` (e.g. `create_response_agent()`, `create_search_agent()`, `create_developer_agent()`, `create_token_launch_agent()`) and composed into the swarm in `claw_swarm.agent.main` via `create_agent()`, which returns a `HierarchicalSwarm` ready for `.run(task)`.
  160. ### Memory
  161. Conversation history is persisted in a markdown file (default `agent_memory.md` at project root, configurable via `AGENT_MEMORY_FILE`). After each reply, the interaction is appended to the file with timestamp, platform, channel, and user/agent text. When handling a new message, the agent reads this file and injects it into the prompt as prior context so it can refer to past conversations across Telegram, Discord, WhatsApp, and restarts. If the file grows beyond the context window (bounded by `AGENT_MEMORY_MAX_CHARS`), the memory is embedded and RAG is used to retrieve only the most relevant chunks for the current query, so long-term memory is preserved without overflowing the context.
  162. ```mermaid
  163. flowchart LR
  164. subgraph write["Persist"]
  165. A[Interaction] --> B[Append to file]
  166. end
  167. subgraph read["On new message"]
  168. C[Read memory file] --> D{Within context limit?}
  169. D -->|Yes| E[Inject full memory]
  170. D -->|No| F[Embed memory]
  171. F --> G[RAG retrieve]
  172. G --> E
  173. E --> H[Agent context]
  174. end
  175. ```
  176. ### Relationship to OpenClaw
  177. [OpenClaw](https://github.com/openclaw/openclaw) is a full-featured personal AI assistant (gateway, many channels, voice, canvas, nodes, skills). **ClawSwarm** is a smaller, lighter-weight take on that vision: natively multi-agent, built on the Swarms framework and Swarms ecosystem, with a path to compile to Rust. Use ClawSwarm when you want a lean, multi-agent messaging layer; use OpenClaw when you need the full product (companion apps, voice, canvas, etc.).
  178. | Feature | ClawSwarm | OpenClaw |
  179. |---------|-----------|----------|
  180. | **Transport** | gRPC over HTTP/2, Protobuf, optional TLS | WebSockets |
  181. | **Multi-agent** | Native - hierarchical director + workers | Single agent |
  182. | **Customizable agents** | Add workers with any tools, model, and role | Not natively extensible |
  183. | **Skills compatibility** | Backwards compatible with all Swarms skills | Custom skill format |
  184. | **Agent memory** | Persistent markdown memory + RAG for long history | Session-scoped |
  185. | **Swarm memory** | Shared across all channels and restarts | Not shared |
  186. | **Channels** | Telegram, Discord, WhatsApp | Telegram, Discord, WhatsApp, and more |
  187. | **Voice / Canvas / Nodes** | Not included | Full product |
  188. | **Compile to Rust** | Path included | No |
  189. | **Footprint** | Lean, minimal dependencies | Full-featured, larger surface area |
  190. | **Best for** | Multi-agent messaging layer, extensible bots | Full personal AI assistant product |
  191. ---
  192. ## Running with a Local Model
  193. ClawSwarm supports local models via **vLLM** (GPU) or **HuggingFace Transformers** (CPU/GPU) as drop-in replacements for any cloud model.
  194. **vLLM (recommended for GPU):**
  195. ```bash
  196. pip install claw-swarm[vllm]
  197. clawswarm run --model vllm/mistralai/Mistral-7B-Instruct-v0.1
  198. ```
  199. **vLLM server** - start the server separately, then point ClawSwarm at it:
  200. ```bash
  201. python -m vllm.entrypoints.openai.api_server \
  202. --model mistralai/Mistral-7B-Instruct-v0.1
  203. clawswarm run --model vllm-server/mistralai/Mistral-7B-Instruct-v0.1
  204. ```
  205. **HuggingFace Transformers (CPU-friendly):**
  206. ```bash
  207. pip install claw-swarm[hf]
  208. clawswarm run --model hf/microsoft/phi-2
  209. ```
  210. Use different models for the director and workers:
  211. ```bash
  212. clawswarm run \
  213. --model vllm/mistralai/Mistral-7B-Instruct-v0.1 \
  214. --worker-model hf/microsoft/phi-2
  215. ```
  216. Or set via environment variables (useful for Docker/Railway):
  217. ```
  218. AGENT_MODEL=vllm/mistralai/Mistral-7B-Instruct-v0.1
  219. WORKER_MODEL_NAME=hf/microsoft/phi-2
  220. ```
  221. Supported prefixes: `vllm/<model>`, `vllm-server/<model>`, `hf/<model>`. Any spec without a prefix is treated as a cloud model name (existing behaviour).
  222. ---
  223. ## Docs
  224. - [Configuration & CLI Reference](docs/cli_config.md) - `claw_config.yaml` schema, config precedence, all CLI flags, production examples, and troubleshooting
  225. ---
  226. ## Gateway API
  227. gRPC service:
  228. - **PollMessages** - Fetch messages since a timestamp (used by the agent runner).
  229. - **StreamMessages** - Server-streaming delivery of new messages.
  230. - **Health** - Liveness and version.
  231. Messages are normalized to a single schema: `UnifiedMessage` (id, platform, channel_id, thread_id, sender, text, attachments, timestamp). Use TLS and restrict network access in production.
  232. ---
  233. ## Deployment
  234. ### Railway (Recommended)
  235. [Railway](https://railway.app) is the easiest way to deploy ClawSwarm. It handles containers, environment variables, persistent storage, and auto-restarts out of the box - no infrastructure management required.
  236. **Steps:**
  237. 1. **Fork or push** this repo to your GitHub account.
  238. 2. **Create a new Railway project** at [railway.app](https://railway.app) and connect your GitHub repo.
  239. 3. **Add environment variables** in the Railway dashboard under *Variables*. Copy from `.env.example` and fill in your credentials:
  240. ```
  241. TELEGRAM_BOT_TOKEN=...
  242. DISCORD_BOT_TOKEN=...
  243. DISCORD_CHANNEL_IDS=...
  244. OPENAI_API_KEY=...
  245. ANTHROPIC_API_KEY=...
  246. AGENT_MODEL=gpt-4o-mini
  247. WORKER_MODEL_NAME=gpt-4o-mini
  248. ```
  249. 4. **Deploy.** Railway auto-detects the `Dockerfile` and builds the image. The service starts with `clawswarm run`.
  250. 5. **(Optional) Expose the gRPC port** - In Railway's *Settings → Networking*, expose port `50051` if you need external clients to reach the gateway. For most setups the gateway and agent run in the same process and no public port is needed.
  251. **Tips:**
  252. - Use Railway's *Volumes* to persist `agent_memory.md` across deploys (mount at `/app/agent_memory.md`).
  253. - Set `GATEWAY_TLS=1` and add your cert/key files as variables or volume-mounted secrets for production TLS.
  254. - Railway's free tier is sufficient for light workloads; upgrade to a paid plan for always-on 24/7 operation.
  255. ### Docker
  256. Build and run locally or on any host with Docker:
  257. ```bash
  258. docker build -t clawswarm .
  259. docker run --env-file .env clawswarm
  260. ```
  261. For persistent memory across container restarts, mount a volume:
  262. ```bash
  263. docker run --env-file .env -v $(pwd)/agent_memory.md:/app/agent_memory.md clawswarm
  264. ```
  265. ---
  266. ## Security and Operations
  267. - **Secrets** - Do not commit tokens or API keys. Use environment variables or a secrets manager.
  268. - **Transport** - Enable gateway TLS in production (`GATEWAY_TLS=1` and valid certificate and key).
  269. - **Access control** - Restrict which clients can reach the gRPC port (firewall, VPC, or mTLS as required).
  270. ---
  271. ## License
  272. See the repository LICENSE for terms of use.
  273. ---
  274. ## Citation
  275. If you use ClawSwarm in your research or work, please cite:
  276. ```bibtex
  277. @software{gomez2025clawswarm,
  278. author = {Gomez, Kye and {The Swarms Corporation}},
  279. title = {ClawSwarm: A Team of 10,000 Productivity Agents for You},
  280. year = {2025},
  281. publisher = {The Swarms Corporation},
  282. url = {https://github.com/kyegomez/ClawSwarm},
  283. note = {A lightweight, natively multi-agent alternative to OpenClaw, supporting Telegram, Discord, and WhatsApp via a unified gRPC gateway}
  284. }
  285. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.