Building ForgeClaw: Multi-Agent AI Orchestration
How we forked OpenClaw to create a customized multi-agent AI environment with the Council of Intellect architecture.
The Fork Decision
OpenClaw is an excellent open-source AI agent framework. It provides the foundation: session management, multi-provider support (OpenAI, Anthropic, Google), tool execution, and a clean CLI interface. But as our needs grew more specialized, we needed deeper customization than upstream supported.
The decision to fork wasn't taken lightly. Forking means taking on maintenance burden, diverging from community updates, and potentially duplicating effort. But it also means freedom — freedom to architect the system exactly as needed for our workflows.
ForgeClaw was born: a fork of OpenClaw with custom routing logic, a multi-agent "Council" architecture, and specialized interfaces for our development workflows.
The Council of Intellect
The core architectural innovation is the Council — five specialized AI agents that collaborate through a shared kernel. Each agent has a distinct role, personality, and underlying model:
| Agent | Role | Model | Provider |
|---|---|---|---|
| Hermes | Speed Daemon / Router | Gemini 3 Flash | |
| Archimedes | Strategic Planner | Gemini 3 Pro | |
| Merlin | Lead Engineer | Claude Opus 4 | Anthropic |
| Hephaestus | Security Auditor | GPT-5.3 Codex | OpenAI |
| Thoth | Memory & Documentation | Gemini 3 Pro |
Merlin: The Council's Lead Engineer in the high-density server environment.
Each agent contributes different strengths. Hermes handles quick queries and routing decisions with Flash-speed responses. Archimedes creates architectural plans and specifications without executing code. Merlin implements with full rewrite authority. Hephaestus audits and hardens. Thoth maintains memory and documentation across sessions.
The Code Assembly Line
Complex tasks (rated complexity greater than 7) trigger a four-step waterfall through the Council:
Planning (Archimedes)
Architectural decomposition — defines the structure without writing code
Drafting (Hermes)
Fast initial implementation — speed over perfection
Review & Rewrite (Merlin)
Full rewrite authority — the code is refined to production quality
Agentic Audit (Hephaestus)
Security and logic audit — final verification before commit
Visualization of the ForgeClaw - Bird CLI integration layer.
The Path Migration
One of the more challenging aspects was migrating from the original OpenClaw directory structure (~/.openclaw) to our custom home (~/.forgeclaw).
This wasn't just a rename operation. Path references were scattered throughout configuration files, session data, credential storage, and logging systems. We implemented a careful migration process:
- Safety backups of all existing state
- Systematic path rewriting in all configuration files
- Verification that the original OpenClaw installation remained unaffected
- Stress testing to ensure no hardcoded paths broke functionality
Multiple Interfaces
ForgeClaw supports three interface modes, all connecting to the same kernel:
- GUI (PyQt5): Full graphical interface with chat, agent status monitoring, and social media integration
- TUI (Textual): Terminal-based interface for SSH accessibility and keyboard-first workflows
- Telegram: Mobile access for on-the-go queries and notifications
System orchestration: Connecting the kernel to diverse interfaces and automation nodes.
The kernel routes requests based on interface_id, allowing each interface to have appropriate "flavor" injection — the GUI might be more verbose, the TUI more compact, Telegram limited by message length constraints.
The Aesthetic
We describe the ForgeClaw visual design as "Dark Techno-Wizard" — deep void backgrounds, cyan and amber neon accents, glassmorphism panels, and pulsing status indicators. It's designed to feel like a command center for AI operations.
The GUI's style.qss runs over 9KB of careful theming. Every widget, from chat bubbles to agent monitors, follows the design language consistently.
Challenges Overcome
Building ForgeClaw wasn't without obstacles:
- Provider rate limits: Coordinating multiple providers means juggling different rate limit strategies and graceful fallbacks
- Session state synchronization: Keeping the GUI, TUI, and Telegram interfaces in sync required careful state management through a shared signal bus
- Agent personality consistency: Each agent needed distinct behavior without hallucinated personality drift over long sessions
- Credential management: OAuth tokens from multiple providers with different expiry patterns required unified refresh logic
Current Status
ForgeClaw is currently in active development. The core Council architecture is stable and serving production workflows. Key areas of ongoing work include:
- Voice integration for hands-free operation
- Enhanced social media automation through the browser subsystem
- Improved saga management for long-running multi-step tasks
- Better resource efficiency for always-on deployment
ForgeClaw represents our vision of what personal AI infrastructure should look like: multi-modal, multi-agent, deeply customizable, and always under user control.