Skip to content
Skills Library
AI & agents · Tool integration

setup-ghostclaw

/setup-ghostclaw

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

Repository
ghostclaw ↗
Licence
MIT
Last repository change
03.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 03.05.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Original author description

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

How it works

  1. Phase 1: Dependencies
  2. Phase 2: Authentication
  3. Phase 3: Channels
  4. Phase 4: Build and start
  5. Phase 5: Register main chat
  6. Phase 6: Soul building (onboarding)
  7. Phase 7: Heartbeat (always set up)
  8. Phase 8: Verify
  9. Phase 9: Optional extras
Original SKILL.md headings · 267 lines, 1,052 words
SKILL.md preview
---
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

```bash
npm install
```

Check Node.js version:
```bash
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):
```bash
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:
   ```bash
   npm run build && node dist/index.js
   ```
2. Scan QR code with WhatsApp
3. Stop the process (Ctrl+C)

## Phase 4: Build and start

```bash
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`.

```bash
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:

```bash
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:
```bash
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:
```bash
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

```bash
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.

```bash
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](https://t.me/+8qJbqxzBQAZkYTNk) to share feedback, get help, or see what others are building.
Files in this package (6)
  • SKILL.md 7 KB
  • soul-prompt.md 2 KB
  • templates/CLAUDE.md 4 KB
  • templates/memory/identity.md 1 KB
  • templates/memory/log.md 1 KB
  • templates/memory/state.md 1 KB

Versions

The database has no other skills named setup-ghostclaw.

Database snapshot: 13.11.2026 · package version aead5e333077 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100customize
    Add new capabilities or modify GhostClaw behavior. Use when user wants to add channels (Telegram, Slack, email input), change triggers, add integrations, modify the router, or make any other customizations. This is an interactive skill that asks questions to understand what the user wants.
  • 100setup-shared-folder
    Set up a private GitHub repo for syncing files between GhostClaw (Mac mini) and user's main machine (MacBook Air, etc). Use when user wants to share files across machines without Dropbox/iCloud.
  • 100setup-guide
    Use when the user wants to set up LLM training for the first time, or when training_hub is not yet installed/configured in the current environment.
  • 86agent-identity-setup
    Use when setting up or resetting agent SOUL, memory, skills.
  • 100setup-guide
    Use when the user wants to set up synthetic data generation for the first time, or when sdg_hub is not yet installed/configured in the current environment.
  • 100setup-guide
    Use when the user wants to set up inference-time scaling for the first time, or when its_hub is not yet installed/configured in the current environment.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.