setup-ghostclaw

name	setup-ghostclaw
description	First-time GhostClaw setup. Handles dependencies, authentication, channel configuration, main chat registration, soul building, and service setup. Use this for all new installs.

GhostClaw Setup

Interactive setup for a fresh GhostClaw install. Handles everything from dependencies to personality.

Phase 1: Dependencies

npm install

Check Node.js version:

node --version  # Must be 20+

Phase 2: Authentication

Claude Code token

Ask: "Do you have a Claude Max subscription or an API key?"

Claude Max (recommended): Tell the user to run this in a separate terminal (not inside Claude Code):

claude setup-token

Then ask them to paste the token. Add to .env:

CLAUDE_CODE_OAUTH_TOKEN=<token>

API key:

ANTHROPIC_API_KEY=<key>

Model selection

AskUserQuestion: Which model should the bot use?

• Sonnet (Recommended) — fast, capable, cost-effective for most tasks
• Opus — most capable, slower, higher cost
• Haiku — fastest, cheapest, good for simple tasks

Add to .env based on choice:

GHOSTCLAW_MODEL=claude-sonnet-4-6    # Sonnet (recommended)
# GHOSTCLAW_MODEL=claude-opus-4-6    # Opus
# GHOSTCLAW_MODEL=claude-haiku-4-5-20251001  # Haiku

If they skip or aren't sure, default to Sonnet. Tell them: "You can change this any time by editing GHOSTCLAW_MODEL in .env and restarting."

Bot name

AskUserQuestion: What should the bot be called?

Add to .env:

ASSISTANT_NAME=<name>

Phase 3: Channels

AskUserQuestion: Which channels do you want?

• Telegram only (recommended — bot gets own identity)
• WhatsApp only
• Both

Telegram setup

If Telegram selected:

1. Tell the user:

   Create a Telegram bot:

   1. Open @BotFather in Telegram
   2. Send /newbot
   3. Pick a name and username
   4. Copy the token

2. Add to .env:

   TELEGRAM_BOT_TOKEN=<token>
   

3. If Telegram-only, add:

   TELEGRAM_ONLY=true
   

WhatsApp setup

If WhatsApp selected:

1. Run the app temporarily to get QR code:

   npm run build && node dist/index.js
   

2. Scan QR code with WhatsApp
3. Stop the process (Ctrl+C)

Phase 4: Build and start

npm run build

Service setup

AskUserQuestion: Set up as a background service? (Yes / No, I'll run it manually)

If yes, detect OS:

macOS:

Read the template from launchd/com.ghostclaw.plist. Replace the {{...}} placeholders with actual values:

• {{NODE_PATH}} → result of which node
• {{PROJECT_ROOT}} → absolute path to the GhostClaw directory (e.g. /Users/username/ghostclaw)
• {{HOME}} → user's home directory (e.g. /Users/username)
• {{ASSISTANT_NAME}} → the bot name from .env

Write the resolved plist to ~/Library/LaunchAgents/com.ghostclaw.plist.

mkdir -p PROJECT_ROOT/logs
launchctl load ~/Library/LaunchAgents/com.ghostclaw.plist

Linux: Create systemd user service and enable it.

Phase 5: Register main chat

Start the service and wait for connection.

Telegram: Tell the user to send /chatid to their bot. They'll get back tg:XXXXXXX. Register it:

node -e "
const { initDatabase, setRegisteredGroup } = require('./dist/db.js');
initDatabase();
setRegisteredGroup('CHAT_JID', {
  name: 'BOTNAME Main',
  folder: 'main',
  trigger: '@BOTNAME',
  added_at: new Date().toISOString(),
  requiresTrigger: false,
});
console.log('Main group registered');
"

Create group directory:

mkdir -p groups/main/logs

Restart the service.

Phase 6: Soul building (onboarding)

This is what makes GhostClaw different. After the bot is running, build its personality.

AskUserQuestion: "Tell me about yourself — what do you do, what are you building, what matters to you? (A few sentences is fine)"

AskUserQuestion: "How do you like AI to communicate? Pick what resonates:"

• Direct and short — no fluff
• Detailed and thorough
• Casual and conversational
• Technical and precise

AskUserQuestion: "Any words, phrases, or patterns you hate in AI responses? (e.g. 'leverage', emoji, 'Great question!')"

AskUserQuestion: "What should the bot proactively help with?"

• Email monitoring
• News/trend watching
• Code review reminders
• Morning briefings
• Nothing — just respond when asked

Generate the soul

If groups/main/CLAUDE.md doesn't exist yet, copy the template first:

cp groups/main/CLAUDE.md.template groups/main/CLAUDE.md

Then customise groups/main/CLAUDE.md based on the user's answers. The template provides the base structure — overwrite the placeholder sections with:

1. Identity section — bot name, what it does
2. Soul section — communication style, banned patterns, user context
3. Capabilities section — what it can do (tools, scheduling, web access)
4. Admin section — file paths, group management, IPC instructions

Use the answers to craft specific instructions. Examples:

If "direct and short":

Don't over-explain. Short answers. Show the work, don't narrate it. Two lines, not ten.

If banned words provided:

Never use these words: [list]. No filler. Write like Orwell.

Write memory seed files

Based on user description, create initial memory files:

• groups/main/about-user.md — what they told you about themselves
• groups/main/preferences.md — communication and tool preferences

Phase 7: Heartbeat (always set up)

The heartbeat is core to GhostClaw — it's what makes the agent proactive rather than reactive.

Create HEARTBEAT.md

Create groups/main/HEARTBEAT.md with a basic checklist. Ask the user what they'd like monitored — suggest:

• GhostClaw error log checks
• Disk space monitoring
• Email checks (if Gmail is set up)
• Any URLs or services they want pinged

Register the heartbeat task

mkdir -p data/ipc/main/tasks
cat > "data/ipc/main/tasks/heartbeat_$(date +%s).json" << 'EOF'
{
  "type": "schedule_task",
  "prompt": "Read $GHOSTCLAW_GROUP_DIR/HEARTBEAT.md (or ./HEARTBEAT.md in the current directory) and run each check listed. Only message the user if something needs attention. If everything is fine, respond with <internal>All checks passed</internal> and nothing else.",
  "schedule_type": "cron",
  "schedule_value": "*/30 * * * *",
  "context_mode": "isolated"
}
EOF

Tell the user: "Heartbeat is running. It checks every 30 minutes and only messages you if something needs attention. Edit groups/main/HEARTBEAT.md any time to add or remove checks."

Phase 8: Verify

Tell the user to send a message to the bot. Check logs to confirm it responds.

tail -20 logs/ghostclaw.log | grep -E "Processing|Agent output|error"

If working: "You're set. Talk to BOTNAME — it knows who you are."

Phase 9: Optional extras

After core setup, offer optional extras. Use AskUserQuestion with multiSelect:

• /add-update-check — weekly check for GhostClaw updates (recommended)
• /add-morning-briefing — scheduled daily/weekly briefings
• /add-gmail-agent — email access for the bot (needs Google Cloud OAuth)
• /add-voice-transcription — voice note transcription (needs ElevenLabs key)
• /add-voice-reply — bot replies with voice notes via ElevenLabs (needs ElevenLabs key)

Run each selected skill in sequence. If none selected, skip — they can always add these later.

After setup, let the user know about the community:

Join the OpenClawOS community on Telegram to share feedback, get help, or see what others are building.