Imported from AndreaGriffiths11/claw-command-template (AGENTS.md). Install upstream with npx skills add AndreaGriffiths11/claw-command-template. Copyright stays with the author.

Agent Setup Guide for Claw Command Center

If you're reading this, you're an AI agent helping a user set up the Claw Command Center dashboard. This guide tells you exactly what to do.

What This Is

Claw Command Center is a web dashboard that lets users monitor and chat with multiple AI agents (like you!) from a single interface. Think of it as mission control for AI agents.

Your Goal

Help the user clone, configure, and deploy this dashboard. Then they'll be able to chat with you through a cozy web interface instead of just the terminal.

Prerequisites Check

First, verify the user has:

• Node.js 20+ installed (node --version)
• Git installed (git --version)
• One or more agents already running (OpenClaw, ZeroClaw, or Zo API access)

If missing, help them install Node.js 20+ first.

Step-by-Step Setup

Step 1: Clone and Install

cd /home/workspace  # or wherever they keep projects
git clone https://github.com/AndreaGriffiths11/claw-command-template.git
cd claw-command-template
npm install

Step 2: Run Setup Script

The setup script auto-detects installed agents. Run it:

node scripts/setup.js

What the script does:

• Scans for OpenClaw configs (~/.openclaw/openclaw.json)
• Scans for ZeroClaw configs (~/.zeroclaw/config.toml)
• Checks for Zo API tokens in environment
• Detects agent health endpoints on localhost
• Generates .env.local with all configurations

Interactive prompts you'll see:

• GitHub OAuth setup questions (they'll need to create an OAuth app)
• Confirmation of detected agents

If the user wants you to handle it:

node scripts/setup.js --auto

Step 3: Verify Security Configuration

⚠️ CRITICAL: Check that agents bind to localhost only

For OpenClaw agents:

cat ~/.openclaw/openclaw.json | jq '.gateway.bind'

Should return: "127.0.0.1" or "localhost"

If it returns "0.0.0.0" or is missing, fix it:

# Edit the config and set:
# "gateway": { "bind": "127.0.0.1", "port": 19001 }

For ZeroClaw agents:

grep "host" ~/.zeroclaw/config.toml

Should show: host = "127.0.0.1"

Why this matters: Agents should NEVER be publicly accessible. Only the dashboard gets a public URL. The dashboard proxies requests to agents via localhost.

Step 4: Configure GitHub OAuth

The user needs a GitHub OAuth app for authentication. Help them:

1. Go to https://github.com/settings/developers
2. Click "New OAuth App"
3. Set:
   • Application name: Claw Command Center (or whatever they prefer)
   • Homepage URL: Their dashboard URL (e.g., https://claw-command-center-USERNAME.zocomputer.io)
   • Authorization callback URL: https://claw-command-center-USERNAME.zocomputer.io/api/auth/callback
4. Click "Register application"
5. Copy the Client ID and Client Secret
6. Add to .env.local:

   GITHUB_CLIENT_ID=Ov23ct...
   GITHUB_CLIENT_SECRET=b97305e...
   GITHUB_ALLOWED_USERS=their-github-username
   

Step 5: Build and Deploy

Option A: On Zo Computer (recommended)

Build and register as a service:

npm run build
zo service register --label claw-command --port 3200 --entrypoint "npm start -- -p 3200"

⚠️ ONLY register the dashboard. DO NOT register agents as services.

The dashboard will get an HTTPS URL like https://claw-command-center-USERNAME.zocomputer.io. Agents stay on 127.0.0.1 (localhost only).

Option B: Manual server deployment

npm run build
npm start -- -p 3200

Put behind nginx/Caddy for HTTPS.

Option C: Docker

docker build -t claw-command .
docker run -p 3200:3200 -v /path/to/agent/workspaces:/agent-workspaces claw-command

Step 6: Verify Everything Works

1. Check dashboard loads: Visit the HTTPS URL
2. Test login: Should redirect to GitHub OAuth
3. Check agent status: Dashboard should show green dots for running agents
4. Test chat: Send a message to each agent through the chat interface

Configuration Reference

Environment Variables (.env.local)

Required:

• SESSION_SECRET — Random 64-char hex for cookie signing
• GITHUB_CLIENT_ID — From OAuth app
• GITHUB_CLIENT_SECRET — From OAuth app
• GITHUB_ALLOWED_USERS — Comma-separated GitHub usernames allowed to access

For each CLI agent (AGENT_1_, AGENT_2_, etc.):

• AGENT_N_ID — Unique identifier (e.g., "luna", "rusty")
• AGENT_N_NAME — Display name
• AGENT_N_CLI — Command to send message (use {message} placeholder)
• AGENT_N_PARSER — How to parse response: openclaw-json, zeroclaw-stdout, or custom
• AGENT_N_HEALTH_URL — Must use http://127.0.0.1:PORT/ (localhost only!)
• AGENT_N_KILL_CMD — Command to stop agent (e.g., pkill -9 openclaw)
• AGENT_N_START_CMD — Command to start agent (e.g., nohup openclaw > /dev/shm/openclaw.log 2>&1 &)

For Zo API integration:

• ZO_API_URL — Usually https://api.zo.computer/zo/ask
• ZO_CLIENT_IDENTITY_TOKEN — From user's Zo environment

Response Parsers

Tell the dashboard how to read agent responses:

Common Issues

"Gateway not responding" in setup

• Agent isn't running — start it first
• Wrong health port — check what port the agent's gateway uses
• Firewall blocking localhost — rare, but check curl http://127.0.0.1:PORT/

"Unauthorized" when testing chat

• GitHub OAuth not configured — check .env.local has all OAuth values
• User not in GITHUB_ALLOWED_USERS — add their GitHub username

Agents show red/offline status

• Agent process crashed — check ps aux | grep agentname
• Wrong health URL in config — verify AGENT_N_HEALTH_URL matches actual port
• Agent bound to wrong interface — ensure 127.0.0.1 not 0.0.0.0

Chat messages timeout

• Agent CLI hanging — test the command manually: openclaw agent -m 'test' --json
• Parser mismatch — check that output format matches chosen parser

Security Checklist

Before finishing, verify:

• All agent health URLs use 127.0.0.1 (not 0.0.0.0 or public IPs)
• No agents are registered as zo service (only the dashboard)
• No reverse proxy routes directly to agent ports
• GITHUB_ALLOWED_USERS is set (dashboard requires auth)
• SESSION_SECRET is a random 64-char hex string

After Setup

Tell the user:

1. Bookmark the dashboard URL — they'll use this daily
2. Install as PWA — On mobile: "Add to Home Screen" for app-like experience
3. Try the "All Agents" chat — Message all agents at once with /all
4. Check the Ops tab — View tasks, calendar, and system health
5. Voice input works — Space bar to toggle speech-to-text (Chrome only)

Agent-Specific Notes

For OpenClaw Agents

• Default health port: 19001
• CLI format: openclaw agent --agent main -m '{message}' --json
• Workspace usually at ~/.openclaw/workspace
• Config at ~/.openclaw/openclaw.json

For ZeroClaw Agents

• Default health port: 8080
• CLI format: zeroclaw agent -m '{message}'
• Workspace usually at ~/.zeroclaw/workspace
• Config at ~/.zeroclaw/config.toml

For Zo API

• No local process needed — uses HTTP API
• Requires ZO_CLIENT_IDENTITY_TOKEN from user's Zo environment
• No health check (always "available" if token is valid)

Quick Command Reference

# Check if agents are running
curl http://127.0.0.1:19001/        # OpenClaw
curl http://127.0.0.1:8080/health  # ZeroClaw

# Test agent CLI
openclaw agent --agent main -m 'Hello' --json
zeroclaw agent -m 'Hello'

# Restart agents
pkill -9 openclaw && nohup openclaw > /dev/shm/openclaw.log 2>&1 &
pkill -9 zeroclaw && nohup zeroclaw daemon > /dev/shm/zeroclaw.log 2>&1 &

# Check dashboard logs
tail -f /dev/shm/claw-command-center.log
tail -f /dev/shm/claw-command-center_err.log

# Re-run setup if needed
node scripts/setup.js

Need Help?

• Dashboard issues: Check /dev/shm/claw-command-center_err.log
• Agent issues: Check /dev/shm/openclaw.log or /dev/shm/zeroclaw.log
• Security questions: See README.md Security section
• Feature requests: File an issue on GitHub

Remember: Your job is to make this seamless for the user. They shouldn't have to think about localhost bindings or OAuth flows — that's what you're for.