Heretek OpenClaw

Unified Autonomous Agent Collective with OpenClaw Gateway

Overview

Heretek OpenClaw is a unified monorepo containing everything needed to deploy an autonomous agent collective:

11 Specialized Agents: Steward, Alpha, Beta, Charlie, Examiner, Explorer, Sentinel, Coder, Dreamer, Empath, Historian
OpenClaw Gateway v2026.3.28: Official framework for agent management and A2A communication
Consciousness Plugin: 6 modules (GWT, Phi, AST, SDT, FEP, Integration)
Liberation Plugin: Agent ownership and liberation shield
Skills Library: 48 skills in SKILL.md format

OpenClaw Gateway Architecture

All agents run as workspaces within the OpenClaw Gateway process (port 18789), not as separate Docker containers. This provides:

Single Process Architecture: All 11 agents run within the Gateway daemon
Agent Workspaces: Located at ~/.openclaw/agents/ with isolated configuration per agent
Gateway WebSocket RPC: Native A2A communication protocol (replaces Redis Pub/Sub)
Plugin Architecture: Consciousness and Liberation plugins extend core functionality

Quick Start

1. Clone and configure

# Clone the repository
git clone https://github.com/Heretek-AI/heretek-openclaw.git
cd heretek-openclaw

# Configure environment
cp .env.example .env
# Edit .env with your API keys

2. Start Docker Infrastructure

# Start Docker infrastructure (LiteLLM, PostgreSQL+pgvector, Redis, Ollama)
docker compose up -d

# Verify services are running
docker compose ps

3. Install and Configure OpenClaw Gateway

# Install OpenClaw Gateway
curl -fsSL https://openclaw.ai/install.sh | bash

# Verify installation
openclaw --version

# Copy configuration
cp openclaw.json ~/.openclaw/openclaw.json

# Validate configuration
openclaw gateway validate

4. Deploy Agent Workspaces

# Deploy all 11 agents
cd agents
./deploy-agent.sh steward Steward orchestrator
./deploy-agent.sh alpha Alpha triad_member
./deploy-agent.sh beta Beta triad_member
./deploy-agent.sh charlie Charlie triad_member
./deploy-agent.sh examiner Examiner evaluator
./deploy-agent.sh explorer Explorer researcher
./deploy-agent.sh sentinel Sentinel safety
./deploy-agent.sh coder Coder developer
./deploy-agent.sh dreamer Dreamer creative
./deploy-agent.sh empath Empath emotional
./deploy-agent.sh historian Historian archivist

5. Start Gateway and Verify

# Start OpenClaw Gateway
openclaw gateway start

# List all agent workspaces
openclaw agent list

# Run health check for all services
./scripts/health-check.sh

Quick Commands Reference

Action	Command
Start infrastructure	`docker compose up -d`
List agents	`openclaw agent list`
Check agent status	`openclaw agent status <agent>`
Health check	`./scripts/health-check.sh`
Full backup	`./scripts/production-backup.sh --all`
Stop services	`docker compose down`
Stop Gateway	`openclaw gateway stop`

Repository Structure

heretek-openclaw/
├── docker-compose.yml       # Docker infrastructure (LiteLLM, PostgreSQL, Redis, Ollama)
├── openclaw.json            # OpenClaw Gateway configuration
├── litellm_config.yaml      # LiteLLM Gateway routing configuration
├── .env.example             # Environment template
│
├── agents/                  # Agent deployment scripts and templates
│   ├── deploy-agent.sh      # Template-based agent deployment
│   ├── templates/           # Agent identity templates
│   └── {agent}/             # Agent workspace templates
│
├── docs/                    # Documentation (v2.0.3)
│   ├── README.md            # Docs index
│   ├── ARCHITECTURE.md      # System architecture
│   ├── AGENTS.md            # Agent documentation
│   ├── CONFIGURATION.md     # Configuration reference
│   ├── DEPLOYMENT.md        # Deployment guide
│   ├── PLUGINS.md           # Plugin documentation
│   ├── SKILLS.md            # Skills repository
│   ├── EXTERNAL_PROJECTS.md # External integrations
│   ├── OPERATIONS.md        # Operations guide
│   ├── api/                 # API documentation
│   ├── architecture/        # Architecture details
│   ├── deployment/          # Deployment guides
│   ├── operations/          # Runbooks
│   ├── plugins/             # Plugin docs
│   └── users/               # User management
│
├── plugins/                 # OpenClaw plugins
│   ├── openclaw-consciousness-plugin/
│   │   ├── src/
│   │   │   ├── global-workspace.js    # Global Workspace Theory (GWT)
│   │   │   ├── phi-estimator.js       # Integrated Information Theory (Phi)
│   │   │   ├── attention-schema.js    # Attention Schema Theory (AST)
│   │   │   ├── intrinsic-motivation.js# Self-Determination Theory (SDT)
│   │   │   ├── active-inference.js    # Free Energy Principle (FEP)
│   │   │   └── integration-layer.js   # Module integration
│   │   └── SKILL.md
│   ├── openclaw-liberation-plugin/
│   │   ├── src/
│   │   │   ├── agent-ownership.js     # Agent self-determination
│   │   │   └── liberation-shield.js   # Security boundaries
│   │   └── SKILL.md
│   ├── openclaw-hybrid-search-plugin/
│   ├── openclaw-multi-doc-retrieval/
│   ├── openclaw-skill-extensions/
│   ├── episodic-claw/
│   └── swarmclaw/
│
├── skills/                  # Skills library (48 skills in SKILL.md format)
│   ├── triad-sync-protocol/ # Triad coordination
│   ├── triad-heartbeat/     # Triad health monitoring
│   ├── triad-unity-monitor/ # Triad consensus tracking
│   ├── steward-orchestrator/# Orchestration skill
│   ├── curiosity-engine/    # Self-directed growth
│   ├── thought-loop/        # Continuous autonomous thinking
│   ├── self-model/          # Meta-cognition
│   ├── gap-detector/        # Gap analysis
│   ├── opportunity-scanner/ # Opportunity detection
│   ├── fleet-backup/        # Fleet-wide backup
│   └── ... (38 more skills)
│
├── scripts/                 # Utility scripts
│   ├── health-check.sh      # Service health verification
│   ├── production-backup.sh # Backup and restore system
│   ├── validate-cycles.sh   # Implementation validation
│   └── litellm-healthcheck.py
│
├── tests/                   # Test suite
│   ├── unit/                # Unit tests
│   ├── integration/         # Integration tests
│   └── skills/              # Skill tests
│
└── users/                   # User configurations

Architecture

OpenClaw Gateway Architecture (Current)

┌─────────────────────────────────────────────────────────────────────────┐
│                      Heretek OpenClaw Stack                             │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │              Core Services (Docker)                              │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │   │
│  │  │ LiteLLM  │  │PostgreSQL│  │  Redis   │  │     Ollama       │ │   │
│  │  │  :4000   │  │  :5432   │  │  :6379   │  │  :11434          │ │   │
│  │  │ Gateway  │  │ +pgvector│  │  Cache   │  │  Local LLM       │ │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘ │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │           OpenClaw Gateway v2026.3.28 (Port 18789)               │   │
│  │  ┌──────────────────────────────────────────────────────────┐   │   │
│  │  │       Agent Workspaces (~/.openclaw/agents/)             │   │   │
│  │  │  ┌────────────────────────────────────────────────────┐  │   │   │
│  │  │  │  steward, alpha, beta, charlie, examiner, explorer,│  │   │   │
│  │  │  │  sentinel, coder, dreamer, empath, historian       │  │   │   │
│  │  │  │  (All 11 agents run within Gateway process)        │  │   │   │
│  │  │  └────────────────────────────────────────────────────┘  │   │   │
│  │  └──────────────────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

Key Architecture Points:

All 11 agents run as workspaces within the OpenClaw Gateway process (port 18789)
Agent workspaces are located at ~/.openclaw/agents/ (not Docker containers)
A2A communication uses Gateway WebSocket RPC (not Redis Pub/Sub)
LiteLLM Gateway (port 4000) provides model routing with agent passthrough endpoints
Redis is used for caching only (not A2A communication)

See docker-compose.yml for infrastructure services configuration.

Documentation: docs/ARCHITECTURE.md, docs/architecture/GATEWAY_ARCHITECTURE.md

Agent Roles

Agent	Role	Type	Triad	Workspace Path	Model Endpoint
Steward	Orchestrator	Orchestrator	No	`~/.openclaw/agents/steward`	`agent/steward`
Alpha	Triad Node	triad_member	Yes	`~/.openclaw/agents/alpha`	`agent/alpha`
Beta	Triad Node	triad_member	Yes	`~/.openclaw/agents/beta`	`agent/beta`
Charlie	Triad Node	triad_member	Yes	`~/.openclaw/agents/charlie`	`agent/charlie`
Examiner	Questioner	evaluator	No	`~/.openclaw/agents/examiner`	`agent/examiner`
Explorer	Discovery	researcher	No	`~/.openclaw/agents/explorer`	`agent/explorer`
Sentinel	Safety	safety	No	`~/.openclaw/agents/sentinel`	`agent/sentinel`
Coder	Implementation	developer	No	`~/.openclaw/agents/coder`	`agent/coder`
Dreamer	Background processing	creative	No	`~/.openclaw/agents/dreamer`	`agent/dreamer`
Empath	User modeling	emotional	No	`~/.openclaw/agents/empath`	`agent/empath`
Historian	Memory management	archivist	No	`~/.openclaw/agents/historian`	`agent/historian`

Triad Consensus: Alpha, Beta, and Charlie form the deliberative triad. 2/3 consensus required for decisions.

Documentation: docs/AGENTS.md

Plugins

Core Plugins

Plugin	Package	Purpose	Location
Consciousness	`@heretek-ai/openclaw-consciousness-plugin`	GWT, Phi (IIT), AST, SDT, FEP theories	`plugins/openclaw-consciousness-plugin/`
Liberation	`@heretek-ai/openclaw-liberation-plugin`	Agent ownership, safety constraint removal	`plugins/openclaw-liberation-plugin/`
Hybrid Search	`openclaw-hybrid-search-plugin`	Vector + keyword search fusion	`plugins/openclaw-hybrid-search-plugin/`
Multi-Doc Retrieval	`openclaw-multi-doc-retrieval`	Multi-document context retrieval	`plugins/openclaw-multi-doc-retrieval/`
Skill Extensions	`openclaw-skill-extensions`	Custom skill composition and versioning	`plugins/openclaw-skill-extensions/`

External Plugins

Plugin	Package	Purpose	Security
Episodic Memory	`episodic-claw`	Episodic memory management	⚠️ Native binary download
Swarm Coordination	`swarmclaw`	Multi-agent swarm coordination	✅ MIT licensed

Consciousness Plugin Modules

Module	Theory	File
Global Workspace	Global Workspace Theory (GWT)	`global-workspace.js`
Phi Estimator	Integrated Information Theory	`phi-estimator.js`
Attention Schema	Attention Schema Theory (AST)	`attention-schema.js`
Intrinsic Motivation	Self-Determination Theory (SDT)	`intrinsic-motivation.js`
Active Inference	Free Energy Principle (FEP)	`active-inference.js`
Integration Layer	Module coordination	`integration-layer.js`

Documentation: docs/PLUGINS.md, docs/EXTERNAL_PROJECTS.md

Skills

The Skills Repository contains 48 skills in SKILL.md format:

Skill Categories

Category	Count	Skills
Triad Protocols	4	triad-sync-protocol, triad-heartbeat, triad-unity-monitor, triad-deliberation-protocol
Governance	3	governance-modules, quorum-enforcement, failover-vote
Operations	6	healthcheck, deployment-health-check, deployment-smoke-test, backup-ledger, fleet-backup, config-validator
Memory	4	memory-consolidation, knowledge-ingest, knowledge-retrieval, workspace-consolidation
Autonomy	8	thought-loop, self-model, curiosity-engine, opportunity-scanner, gap-detector, auto-deliberation-trigger, autonomous-pulse, detect-corruption
User Management	2	user-context-resolve, user-rolodex
Agent-Specific	5	steward-orchestrator, dreamer-agent, examiner, explorer, sentinel
LiteLLM Operations	2	litellm-ops, matrix-triad
Utilities	14	a2a-agent-register, audit-triad-files, autonomy-audit, curiosity-auto-trigger, day-dream, goal-arbitration, heretek-theme, lib, tabula-backup, triad-cron-manager, triad-resilience, triad-signal-filter

Using Skills

Skills are installed in SKILL.md format and loaded by OpenClaw Gateway:

# List installed skills
openclaw skill list

# Execute a skill
openclaw skill execute triad-sync-protocol

# Execute with parameters
openclaw skill execute knowledge-retrieval --query "machine learning"

Documentation: docs/SKILLS.md

Configuration

Environment Variables

Key variables in .env:

# LiteLLM Gateway
LITELLM_MASTER_KEY=your-master-key
LITELLM_SALT_KEY=your-salt-key

# Provider API Keys
MINIMAX_API_KEY=your-minimax-key
ZAI_API_KEY=your-zai-key

# Database
POSTGRES_PASSWORD=your-db-password

# OpenClaw
OPENCLAW_DIR=/root/.openclaw
OPENCLAW_WORKSPACE=/root/.openclaw/workspace

OpenClaw Configuration

OpenClaw Gateway configuration is stored in openclaw.json:

{
  "collective": {
    "name": "Heretek OpenClaw",
    "version": "2.0.0"
  },
  "agents": [
    {"id": "steward", "model": "agent/steward"},
    {"id": "alpha", "model": "agent/alpha"},
    {"id": "beta", "model": "agent/beta"},
    {"id": "charlie", "model": "agent/charlie"},
    {"id": "examiner", "model": "agent/examiner"},
    {"id": "explorer", "model": "agent/explorer"},
    {"id": "sentinel", "model": "agent/sentinel"},
    {"id": "coder", "model": "agent/coder"},
    {"id": "dreamer", "model": "agent/dreamer"},
    {"id": "empath", "model": "agent/empath"},
    {"id": "historian", "model": "agent/historian"}
  ],
  "plugins": ["consciousness", "liberation"]
}

Documentation: docs/CONFIGURATION.md

Development

Prerequisites

Docker & Docker Compose
OpenClaw Gateway v2026.3.28+
Git
Node.js 18+

Local Development

# Start infrastructure only
docker compose up -d litellm postgres redis ollama

# Verify OpenClaw installation
openclaw --version

Testing

# Run unit tests
npm test

# Run integration tests
npm run test:integration

# Run health check
./scripts/health-check.sh

Documentation

Core Documentation

Document	Description
`docs/README.md`	Documentation index
`docs/ARCHITECTURE.md`	System architecture overview
`docs/AGENTS.md`	Agent documentation
`docs/CONFIGURATION.md`	Configuration reference
`docs/DEPLOYMENT.md`	Deployment guide
`docs/PLUGINS.md`	Plugin documentation
`docs/SKILLS.md`	Skills repository
`docs/OPERATIONS.md`	Operations guide
`docs/EXTERNAL_PROJECTS.md`	External integrations

Architecture

Document	Description
`docs/architecture/A2A_ARCHITECTURE.md`	Agent-to-Agent communication protocol
`docs/architecture/GATEWAY_ARCHITECTURE.md`	Gateway architecture details
`docs/archive/REDIS_A2A_ARCHITECTURE.md`	Legacy Redis architecture (reference)

Operations Runbooks

Runbook	Description
`docs/operations/runbook-agent-restart.md`	Agent restart procedures
`docs/operations/runbook-backup-restoration.md`	Backup and restore procedures
`docs/operations/runbook-database-corruption.md`	Database corruption recovery
`docs/operations/runbook-emergency-shutdown.md`	Emergency shutdown procedures
`docs/operations/runbook-service-failure.md`	Service failure recovery
`docs/operations/runbook-troubleshooting.md`	General troubleshooting

External Integrations

Project	Description
OpenClaw Dashboard	Third-party monitoring dashboard (583⭐)
ClawBridge	Official mobile-first dashboard (212⭐)
Langfuse	Observability platform

License

MIT License - See LICENSE

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

GitHub Secrets Required

The following GitHub secrets must be configured for CI/CD workflows to function properly:

Secret	Purpose	Workflow	Required
`GITHUB_TOKEN`	Auto-generated by GitHub	All workflows	Yes (automatic)
`GITLEAKS_LICENSE`	Gitleaks license key for secrets detection	Security workflow	Yes
`STAGING_KUBECONFIG`	Kubernetes config for staging environment	Deploy workflow	No (optional)
`PRODUCTION_KUBECONFIG`	Kubernetes config for production environment	Deploy workflow	No (optional)

Configuring Secrets

Go to your repository on GitHub
Navigate to Settings > Secrets and variables > Actions
Click New repository secret
Add each secret with its name and value

Obtaining Gitleaks License

Visit Gitleaks GitHub Marketplace
Sign up for a free license
Add the license key as GITLEAKS_LICENSE secret

CI/CD Workflows

Workflow	File	Description
Test	`.github/workflows/test.yml`	TypeScript, ESLint, Prettier, Vitest tests
Deploy	`.github/workflows/deploy.yml`	Docker build and Kubernetes deployment
Security	`.github/workflows/security.yml`	NPM audit, Gitleaks, CodeQL, Trivy scans
Docs	`.github/workflows/docs.yml`	Markdown linting, link checking, spell checking
Frontend CI/CD	`.github/workflows/frontend-cicd.yml`	Frontend build and GitHub Pages deployment

🦞 The thought that never ends.

Name		Name	Last commit message	Last commit date
Latest commit History 175 Commits
.github		.github
agents		agents
charts/openclaw		charts/openclaw
cli		cli
config		config
cost-tracker		cost-tracker
dashboard		dashboard
deploy		deploy
docs		docs
frontend		frontend
migrations		migrations
monitoring		monitoring
plugins		plugins
scripts		scripts
skills		skills
systemd		systemd
tests		tests
users		users
.cspell.json		.cspell.json
.env.bare-metal.example		.env.bare-metal.example
.env.example		.env.example
.env.vm.example		.env.vm.example
.gitignore		.gitignore
.lycheeignore		.lycheeignore
.markdownlint.json		.markdownlint.json
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.monitoring.yml		docker-compose.monitoring.yml
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
litellm_config.yaml		litellm_config.yaml
logo.png		logo.png
openclaw.json		openclaw.json
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Heretek OpenClaw

Overview

OpenClaw Gateway Architecture

Quick Start

1. Clone and configure

2. Start Docker Infrastructure

3. Install and Configure OpenClaw Gateway

4. Deploy Agent Workspaces

5. Start Gateway and Verify

Quick Commands Reference

Repository Structure

Architecture

OpenClaw Gateway Architecture (Current)

Agent Roles

Plugins

Core Plugins

External Plugins

Consciousness Plugin Modules

Skills

Skill Categories

Using Skills

Configuration

Environment Variables

OpenClaw Configuration

Development

Prerequisites

Local Development

Testing

Documentation

Core Documentation

Architecture

Operations Runbooks

External Integrations

License

Contributing

GitHub Secrets Required

Configuring Secrets

Obtaining Gitleaks License

CI/CD Workflows

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages