Claw-Empire

Command Your AI Agent Empire from the CEO Desk
A local-first AI agent office simulator that orchestrates CLI, OAuth, and API-connected providers (including Claude Code, Codex CLI, Gemini CLI, OpenCode, Kimi Code, GitHub Copilot, and Antigravity) as a virtual company of autonomous agents.

Quick Start · AI Install Guide · Release Notes · OpenClaw · Direct Messenger · $ Command · Features · Screenshots · Tech Stack · Providers · Docker Deploy · Security

English | 한국어 | 日本語 | 中文

What is Claw-Empire?

Claw-Empire transforms your AI coding assistants — connected via CLI, OAuth, or direct API keys — into a fully simulated virtual software company. You are the CEO. Your AI agents are the employees. Watch them collaborate across departments, hold meetings, deliver tasks, and level up — all visualized through a charming pixel-art office interface.

Why Claw-Empire?

• One interface, many AI agents — Manage CLI, OAuth, and API-backed agents from a single dashboard
• Local-first & private — All data stays on your machine. SQLite database, no cloud dependency
• Visual & intuitive — Pixel-art office view makes AI orchestration fun and transparent
• Real autonomous collaboration — Agents work in isolated git worktrees, attend meetings, and produce deliverables

Install with AI

Just paste this to your AI coding agent (Claude Code, Codex, Gemini CLI, etc.):

Install Claw-Empire following the guide at:
https://github.com/GreenSheep01201/claw-empire

The AI will read this README and handle everything automatically.

Latest Release (v2.0.4)

• Docker deployment is now an officially documented path - the repo now ships a production-oriented Dockerfile, docker-compose.yml, .dockerignore, and container-aware runtime path handling.

• Stale working agents recover automatically after interrupted runs - lifecycle startup and interval sweeps now reset agents that are still marked working without a live in_progress task.

• Settings > API now supports official direct-API presets - OpenCode Go and Bailian Coding Plan presets lock the expected Base URL, seed fallback models immediately, and keep refresh/retry behavior explicit.

• Kimi Code is now supported end to end - Kimi is wired through CLI execution, provider labels, skills learn/unlearn flow, prompt-skill rendering, video-preprod bootstrap, and provider-aware schema/runtime checks.

• API model assignment now starts from the development pack and expands to initialized office packs - development remains the default baseline, and office packs that have already been hydrated through initial setup also appear as assign targets.

• Local E2E validation is safer and cleaner - pnpm run test:e2e now resets the isolated runtime before and after Playwright runs, and existing 8810 servers are no longer reused unless you explicitly opt in.

• Full notes: docs/releases/v2.0.4.md

• API docs: docs/api.md, docs/openapi.json

• Security policy: SECURITY.md

Office Pack Profiles (v2.0.1)

Each office pack applies a different collaboration topology, naming seed, and workflow bias.

Screenshots

Dashboard — Real-time KPI metrics, agent rankings, and department status at a glance	Kanban Board — Drag-and-drop task management with department and agent filters
Skills Library — Browse and assign 600+ agent skills across categories	Multi-Provider CLI — Configure Claude Code, Codex, Gemini CLI, OpenCode, and Kimi Code with model selection
OAuth Integration — Secure GitHub & Google OAuth with encrypted token storage	Meeting Minutes — AI-generated meeting summaries with multi-round review approval
Messenger Integration — Configure Telegram, WhatsApp, Discord, Google Chat, Slack, Signal, iMessage sessions and send $ CEO directives	Settings — Configure company name, CEO name, default provider preferences (CLI/OAuth/API), and language preferences
Detailed Report — Example of completion report popup, report history, and detailed report view for a request	PPT Generation — Example captures of PPT generation output for a report request

Video Output Sample

Preview sample intro video output:

• Direct file: Sample_Img/claw-empire-intro.mp4

PPT Sample Sources

Use the sample sources below when reviewing or extending report-to-PPT generation: Usage path: Chat window > Report Request button, then enter your request.

• Folder: docs/reports/Sample_Slides
• Sample deck (.pptx): docs/reports/PPT_Sample.pptx
• HTML slides: slide-01.html, slide-02.html, slide-03.html, slide-04.html, slide-05.html, slide-06.html, slide-07.html, slide-08.html, slide-09.html
• Build scripts: build-pptx.mjs, build-pptx.cjs, html2pptx.cjs

Features

Tech Stack

# Node.js 22+
node -v

# pnpm (or enable corepack)
pnpm -v || corepack enable

# git
git --version

git clone https://github.com/GreenSheep01201/claw-empire.git
cd claw-empire
git submodule update --init --recursive
bash install.sh

git clone https://github.com/GreenSheep01201/claw-empire.git
cd claw-empire
git submodule update --init --recursive
powershell -ExecutionPolicy Bypass -File .\install.ps1

# Required files after setup
[ -f .env ] && [ -f scripts/setup.mjs ] && echo "setup files ok"

# AGENTS orchestration rules installed
grep -R "BEGIN claw-empire orchestration rules" ~/.openclaw/workspace/AGENTS.md AGENTS.md 2>/dev/null || true
grep -R "INBOX_SECRET_DISCOVERY_V2" ~/.openclaw/workspace/AGENTS.md AGENTS.md 2>/dev/null || true

# OpenClaw inbox requirements in .env
grep -E '^(INBOX_WEBHOOK_SECRET|OPENCLAW_CONFIG)=' .env || true

if ((Test-Path .\.env) -and (Test-Path .\scripts\setup.mjs)) { "setup files ok" }
$agentCandidates = @("$env:USERPROFILE\.openclaw\workspace\AGENTS.md", ".\AGENTS.md")
$agentCandidates | ForEach-Object { if (Test-Path $_) { Select-String -Path $_ -Pattern "BEGIN claw-empire orchestration rules" } }
$agentCandidates | ForEach-Object { if (Test-Path $_) { Select-String -Path $_ -Pattern "INBOX_SECRET_DISCOVERY_V2" } }

# OpenClaw inbox requirements in .env
Get-Content .\.env | Select-String -Pattern '^(INBOX_WEBHOOK_SECRET|OPENCLAW_CONFIG)='

pnpm dev:local

curl -s http://127.0.0.1:8790/healthz

curl -s http://127.0.0.1:8790/api/messenger/sessions

curl -X POST http://127.0.0.1:8790/api/inbox \
  -H "content-type: application/json" \
  -H "x-inbox-secret: $INBOX_WEBHOOK_SECRET" \
  -d '{"source":"telegram","author":"ceo","text":"$README v1.1.6 inbox smoke test","skipPlannedMeeting":true}'

Step 5: Direct messenger setup (no OpenClaw required)

You can run messenger channels directly from Claw-Empire without OpenClaw.

1. Open Settings > Channel Messages.
2. Click Add Chat.
3. Select a messenger (telegram, whatsapp, discord, googlechat, slack, signal, imessage).
4. Fill in session fields:
   • Name (session label)
   • messenger token/credential
   • Channel/Chat ID (target)
   • mapped conversation Agent
5. Click Confirm to save immediately (no extra global save step required).
6. Enable the session, then test:
   • normal message -> direct agent chat
   • $ ... -> directive flow

Notes:

• Messenger sessions are persisted in SQLite (settings.messengerChannels).
• Messenger tokens are encrypted at rest (AES-256-GCM) using OAUTH_ENCRYPTION_SECRET (fallback: SESSION_SECRET) and decrypted only at runtime.
• .env messenger variables (TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN, etc.) are not used.
• /api/inbox + INBOX_WEBHOOK_SECRET is only needed for webhook/inbox flows (including OpenClaw bridge).

Quick Start

Docker Deployment (Quick Start)

This repo now ships production-oriented Docker defaults:

• Runs as non-root user (app, uid/gid 10001)
• Includes required CLI/runtime tools (git, bash, openssh-client)
• Uses docker-compose.yml + Dockerfile
• Persists runtime data in ./data (already gitignored)

1) Prepare environment files

cp .env.example .env.docker

Create .env.docker.private for sensitive runtime secrets (keep this file local only):

cat > .env.docker.private <<'EOF'
# Claude Code via compatible endpoint
ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
EOF
chmod 600 .env.docker.private

.env.docker* is ignored by git (.env.*), so tokens are not committed by default.

2) Start

docker compose up -d --build

3) Verify

docker ps --filter name=claw-empire
docker logs -f claw-empire

Open: http://127.0.0.1:8790

Optional: publish image to GHCR

# requires token with package write scope
echo "<GITHUB_TOKEN_WITH_PACKAGES_WRITE>" | docker login ghcr.io -u <github-user> --password-stdin
docker tag claw-empire-claw-empire:latest ghcr.io/<github-user>/claw-empire:latest
docker push ghcr.io/<github-user>/claw-empire:latest

Prerequisites

One-Click Setup (Recommended)

If the repo is already cloned:

OpenClaw .env Requirements (for /api/inbox)

Set both values in .env before sending chat webhooks:

• INBOX_WEBHOOK_SECRET=<long-random-secret>
• OPENCLAW_CONFIG=<absolute-path-to-openclaw.json> (unquoted preferred)

scripts/openclaw-setup.sh / scripts/openclaw-setup.ps1 now auto-generate INBOX_WEBHOOK_SECRET when it is missing. Initial install via bash install.sh / install.ps1 already goes through these setup scripts, so this is applied from day one. For existing clones that only run git pull, pnpm dev* / pnpm start* now auto-apply this once when needed and then persist CLAW_MIGRATION_V1_0_5_DONE=1 to prevent repeated execution.

/api/inbox requires server-side INBOX_WEBHOOK_SECRET plus an x-inbox-secret header that exactly matches it.

• Missing/mismatched header -> 401
• Missing server config (INBOX_WEBHOOK_SECRET) -> 503

Manual Setup (Fallback)

# 1. Clone the repository
git clone https://github.com/GreenSheep01201/claw-empire.git
cd claw-empire

# 2. Enable pnpm via corepack
corepack enable

# 3. Install dependencies
pnpm install

# 4. Create your local environment file
cp .env.example .env

# 5. Generate a random encryption secret
node -e "
  const fs = require('fs');
  const crypto = require('crypto');
  const p = '.env';
  const content = fs.readFileSync(p, 'utf8');
  fs.writeFileSync(p, content.replace('__CHANGE_ME__', crypto.randomBytes(32).toString('hex')));
"

# 6. Setup AGENTS.md orchestration rules (teaches your AI agent to be a Claw-Empire project manager)
pnpm setup -- --port 8790

# 7. Start the development server
pnpm dev:local

# 1. Clone the repository
git clone https://github.com/GreenSheep01201/claw-empire.git
cd claw-empire

# 2. Enable pnpm via corepack
corepack enable

# 3. Install dependencies
pnpm install

# 4. Create your local environment file
Copy-Item .env.example .env

# 5. Generate a random encryption secret
node -e "const fs=require('fs');const crypto=require('crypto');const p='.env';const c=fs.readFileSync(p,'utf8');fs.writeFileSync(p,c.replace('__CHANGE_ME__',crypto.randomBytes(32).toString('hex')))"

# 6. Setup AGENTS.md orchestration rules (teaches your AI agent to be a Claw-Empire project manager)
pnpm setup -- --port 8790

# 7. Start the development server
pnpm dev:local

Open your browser:

AGENTS.md Setup

The pnpm setup command injects CEO directive orchestration rules into your AI agent's AGENTS.md file. This teaches your AI coding agent (Claude Code, Codex, etc.) how to:

• Interpret $ prefix CEO directives for priority task delegation
• Call the Claw-Empire REST API to create tasks, assign agents, and report status
• Work within isolated git worktrees for safe parallel development

# Default: auto-detects AGENTS.md location
pnpm setup

# Custom path
pnpm setup -- --agents-path /path/to/your/AGENTS.md

# Custom port
pnpm setup -- --port 8790

OpenClaw Integration Setup (Telegram/WhatsApp/Discord/Google Chat/Slack/Signal/iMessage)

install.sh / install.ps1 (or scripts/openclaw-setup.*) will auto-detect and write OPENCLAW_CONFIG when possible.

Recommended .env format: absolute path for OPENCLAW_CONFIG (unquoted preferred). v1.0.5 also normalizes surrounding quotes and leading ~ at runtime for compatibility.

Default config paths:

Manual commands:

# macOS / Linux
bash scripts/openclaw-setup.sh --openclaw-config ~/.openclaw/openclaw.json

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File .\scripts\openclaw-setup.ps1 -OpenClawConfig "$env:USERPROFILE\.openclaw\openclaw.json"

Verify messenger sessions:

curl -s http://127.0.0.1:8790/api/gateway/targets

$ Command -> OpenClaw Chat Delegation Logic

When a chat message starts with $, Claw-Empire handles it as a CEO directive:

1. Orchestrator asks whether to hold a team-leader meeting first.
2. Orchestrator asks for project path/context (project_path or project_context).
3. It sends the directive to POST /api/inbox with the $ prefix and x-inbox-secret header.
4. If meeting is skipped, include "skipPlannedMeeting": true.
5. Server stores it as directive, broadcasts company-wide, then delegates to Planning (and mentioned departments when included).

If x-inbox-secret is missing/mismatched, the request is rejected with 401. If INBOX_WEBHOOK_SECRET is not configured on the server, the request is rejected with 503.

With meeting:

curl -X POST http://127.0.0.1:8790/api/inbox \
  -H "content-type: application/json" \
  -H "x-inbox-secret: $INBOX_WEBHOOK_SECRET" \
  -d '{"source":"telegram","author":"ceo","text":"$Release v0.2 by Friday with QA sign-off","project_path":"/workspace/my-project"}'

Without meeting:

curl -X POST http://127.0.0.1:8790/api/inbox \
  -H "content-type: application/json" \
  -H "x-inbox-secret: $INBOX_WEBHOOK_SECRET" \
  -d '{"source":"telegram","author":"ceo","text":"$Hotfix production login bug immediately","skipPlannedMeeting":true,"project_context":"existing climpire project"}'

Environment Variables

Copy .env.example to .env. All secrets stay local — never commit .env.

When API_AUTH_TOKEN is enabled, remote browser clients enter it at runtime. The token is stored only in sessionStorage and is not embedded in Vite build artifacts. For OPENCLAW_CONFIG, absolute path is recommended. In v1.0.5, quoted values and leading ~ are normalized automatically.

Run Modes

# Development (local-only, recommended)
pnpm dev:local          # binds to 127.0.0.1

# Development (network-accessible)
pnpm dev                # binds to 0.0.0.0

# Production build
pnpm build              # TypeScript check + Vite build
pnpm start              # start API/backend server (serves dist in production mode)

# Health check
curl -fsS http://127.0.0.1:8790/healthz

CI Verification (Current PR Pipeline)

On every pull request, .github/workflows/ci.yml runs:

1. Hidden/bidi Unicode guard for workflow files
2. pnpm install --frozen-lockfile
3. pnpm run format:check
4. pnpm run lint
5. pnpm exec playwright install --with-deps
6. pnpm run test:ci (test:web --coverage + test:api --coverage + test:e2e)

Note: pnpm run test:e2e now boots an isolated .tmp/e2e-runtime database and clears it again after the run. Set PW_REUSE_EXISTING_SERVER=1 only when you intentionally want to reuse an already-running local server on 8810.

Recommended local pre-PR check:

pnpm run format:check
pnpm run lint
pnpm run build
pnpm run test:ci

Communication QA Checks (v1.1.6)

# Individual checks
pnpm run test:comm:llm
pnpm run test:comm:oauth
pnpm run test:comm:api

# Integrated suite (also available via legacy entrypoint)
pnpm run test:comm:suite
pnpm run test:comm-status

test:comm:suite writes machine-readable evidence to logs/ and a markdown report to docs/.

Project Path QA Smoke (v1.1.6)

# Requires API auth token
QA_API_AUTH_TOKEN="<API_AUTH_TOKEN>" pnpm run test:qa:project-path

test:qa:project-path validates path helper endpoints, project create flow, duplicate project_path conflict response, and cleanup behavior.

In-App Update Banner

When a newer release is published on GitHub, Claw-Empire shows a top banner in the UI with pull instructions and a release-note link.

• Windows PowerShell: git pull; pnpm install
• macOS/Linux shell: git pull && pnpm install
• After pull/install, restart the server.

Auto Update (Safe Mode, opt-in)

You can enable conservative auto-update behavior for release sync.

• GET /api/update-auto-status — current auto-update runtime/config state (auth required)
• POST /api/update-auto-config — update runtime auto-update toggle (enabled) without restart (auth required)
• POST /api/update-apply — apply update pipeline on demand (dry_run / force / force_confirm supported, auth required)
  • force=true bypasses most safety guards and therefore requires force_confirm=true
  • dirty_worktree and channel_check_unavailable guards are non-overridable (still block apply)
  • Restart mode (notify|exit|command) is applied for both auto and manual update runs
  • In notify mode, successful apply includes manual_restart_required reason

Default behavior remains unchanged (OFF). When enabled, safe-mode guards skip updates if the server is busy or the repository is not in a clean fast-forward state. If AUTO_UPDATE_CHANNEL has an invalid value, the server logs a warning and falls back to patch.

Troubleshooting: git_pull_failed / diverged local branch

If an apply result returns error: "git_pull_failed" (or git_fetch_failed) with manual_recovery_may_be_required in result.reasons, the repository likely needs operator intervention.

1. Inspect the latest apply result via GET /api/update-auto-status (runtime.last_result, runtime.last_error).
2. In the server repo, check divergence:
   • git fetch origin main
   • git status
   • git log --oneline --decorate --graph --max-count 20 --all
3. Resolve to a clean fast-forwardable state (for example, rebase local commits or reset to origin/main based on your policy).
4. Re-run POST /api/update-apply (optionally {"dry_run": true} first).

The auto-update loop keeps running on its configured interval and will retry on future cycles after the repository returns to a safe state.

⚠️ AUTO_UPDATE_RESTART_COMMAND runs with server permissions and is a privileged operation. The command parser rejects shell metacharacters (;, |, &, `, $, <, >) and blocks direct shell launchers (for example sh, bash, zsh, cmd, powershell, pwsh). Use only a plain executable + fixed args format (no shell/interpreter wrappers, no dynamically constructed input).

Provider Setup (CLI / OAuth / API)

Official API presets

The Settings > API tab now includes four official direct-API presets:

• OpenCode Go (OpenAI) -> https://opencode.ai/zen/go/v1
• OpenCode Go (Anthropic) -> https://opencode.ai/zen/go/v1
• Bailian Coding Plan (OpenAI) -> https://coding-intl.dashscope.aliyuncs.com/v1
• Bailian Coding Plan (Anthropic) -> https://coding-intl.dashscope.aliyuncs.com/apps/anthropic

Notes:

• Bailian Coding Plan API keys must start with sk-sp-.
• These presets seed fallback model lists immediately so agents can be assigned even when live /models discovery is unavailable or incomplete.
• The assignment modal uses development as the default baseline and also includes office packs that have already completed initial setup and been hydrated into runtime state.
• Direct API presets use the provider endpoint model IDs such as glm-5, kimi-k2.5, and minimax-m2.5. They do not use OpenCode CLI model IDs like opencode-go/<model-id>.
• Bailian Coding Plan keys are intended for the interactive coding tool flow. Review the provider documentation before reusing those keys in other environments.

Claw-Empire supports three provider paths:

• CLI tools — install local coding CLIs and run tasks through local processes
• OAuth accounts — connect supported providers (for example GitHub/Google-backed flows) via secure token exchange
• Direct API keys — bind agents to external LLM APIs from Settings > API

For CLI mode, install at least one:

Configure providers and models in the Settings > CLI Tools panel within the app.

Alternatively, connect agents to external LLM APIs (no CLI installation required) via the Settings > API tab. API keys are stored encrypted (AES-256-GCM) in the local SQLite database — not in .env or source code. Skills learn/unlearn automation is currently designed for CLI-capable providers.

Project Structure

claw-empire/
├── .github/
│   └── workflows/
│       └── ci.yml             # PR CI (Unicode guard, format, lint, tests)
├── server/
│   ├── index.ts              # backend entrypoint
│   ├── server-main.ts        # runtime wiring/bootstrap
│   ├── modules/              # routes/workflow/bootstrap lifecycle
│   ├── test/                 # backend test setup/helpers
│   └── vitest.config.ts      # backend unit test config
├── src/
│   ├── app/                  # app shell, layout, state orchestration
│   ├── api/                  # frontend API modules
│   ├── components/           # UI (office/taskboard/chat/settings)
│   ├── hooks/                # polling/websocket hooks
│   ├── test/                 # frontend test setup
│   ├── types/                # frontend type definitions
│   ├── App.tsx
│   ├── api.ts
│   └── i18n.ts
├── tests/
│   └── e2e/                  # Playwright E2E scenarios
├── public/sprites/           # pixel-art agent sprites
├── scripts/
│   ├── setup.mjs             # environment/bootstrap setup
│   ├── auto-apply-v1.0.5.mjs # startup migration helper
│   ├── openclaw-setup.sh     # one-click setup (macOS/Linux)
│   ├── openclaw-setup.ps1    # one-click setup (Windows PowerShell)
│   ├── prepare-e2e-runtime.mjs
│   ├── preflight-public.sh   # pre-release security checks
│   └── generate-architecture-report.mjs
├── install.sh                # wrapper for scripts/openclaw-setup.sh
├── install.ps1               # wrapper for scripts/openclaw-setup.ps1
├── docs/                     # design & architecture docs
├── AGENTS.md                 # local agent/orchestration rules
├── CONTRIBUTING.md           # branch/PR/review policy
├── eslint.config.mjs         # flat ESLint config
├── .env.example              # environment variable template
└── package.json

Security

Claw-Empire is designed with security in mind:

• Local-first architecture — All data stored locally in SQLite; no external cloud services required
• Encrypted OAuth + messenger tokens — User-specific OAuth tokens and direct messenger channel tokens are stored server-side only in SQLite, encrypted at rest using AES-256-GCM with OAUTH_ENCRYPTION_SECRET (SESSION_SECRET fallback). The browser never receives refresh tokens
• Built-in OAuth Client IDs — The GitHub and Google OAuth client IDs/secrets embedded in the source code are public OAuth app credentials, not user secrets. Per Google's documentation, client secrets for installed/desktop apps are "not treated as a secret." This is standard practice for open-source apps (VS Code, Thunderbird, GitHub CLI, etc.). These credentials only identify the app itself — your personal tokens are always encrypted separately
• No personal credentials in source — All user-specific tokens (GitHub, Google OAuth) are stored encrypted in the local SQLite database, never in source code
• No secrets in repo — Comprehensive .gitignore blocks .env, *.pem, *.key, credentials.json, etc.
• Preflight security checks — Run pnpm run preflight:public before any public release to scan for leaked secrets in both working tree and git history
• Localhost by default — Development server binds to 127.0.0.1, not exposed to network

API Docs & Security Quick Links

• API documentation — Use docs/api.md for endpoint overview and usage notes, and docs/openapi.json for schema/tooling integration.
• Security policy — Review disclosure and policy details in SECURITY.md, and run pnpm run preflight:public before public releases.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch from dev (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Run local checks before PR:
   • pnpm run format:check
   • pnpm run lint
   • pnpm run build
   • pnpm run test:ci
5. Push your branch (git push origin feature/amazing-feature)
6. Open a Pull Request to dev (default integration branch for contributors)
7. Use main only for maintainer-approved emergency hotfixes, then back-merge main -> dev

Full policy: CONTRIBUTING.md

License

Apache 2.0 — Free for personal and commercial use.