ghostclaw

The OpenClaw alternative that actually works. A bare-metal fork of NanoClaw — containers stripped, full system access, Telegram-first. Give your spare computer its own accounts and let an AI agent run wild. 10 minutes to set up.

Why GhostClaw?

| | GhostClaw | OpenClaw | NanoClaw | |---|---|---|---| | Setup | 10 min | 30+ min | 15 min | | Codebase | ~4K LOC | ~500K LOC | ~700 LOC | | System access | Full (bare metal) | Full | Sandboxed (Docker) | | Messaging | Telegram-first | 50+ channels | Telegram, WhatsApp, Slack | | Containers | None | Required | Required | | Best for | Solo devs, tinkerers, personal agents | Teams, enterprises | Security-first setups |

NanoClaw's simplicity. OpenClaw's freedom. None of the mess.

GhostClaw started as a NanoClaw fork with one question: what if you ripped out everything that makes self-hosting painful? No Docker, no container orchestration, no config maze. Agents run as direct Node.js child processes with full machine access — bash, files, web, email. That's the point.

Get started

v0.8.0 is API-direct. From v0.8.0 onwards GhostClaw runs on the Anthropic API (ANTHROPIC_API_KEY) only — Claude Max / OAuth login is no longer supported. Every turn writes a usage_events row and /budget lets you cap daily spend. If you were on a v0.7.x build with CLAUDE_CODE_OAUTH_TOKEN, see Migrating from v0.7.

New to AI agents? Read learn.md first — the full picture on personal agents in 2026, how GhostClaw compares to OpenClaw, Hermes, NanoClaw and others, and what you're getting into. Or drop it into Claude Code as a skill and ask it anything.

curl -fsSL https://ghostclaw.io/install.sh | bash

One command. The installer walks you through everything — API key, Telegram bot, personality, auto-start. Done in 5 minutes.

Requirements: Node.js 20+, Anthropic API key, macOS or Linux, Telegram account.

git clone https://github.com/b1rdmania/ghostclaw.git
cd ghostclaw && npm install && npm run build

Create .env:

ANTHROPIC_API_KEY=sk-ant-your-key-here
TELEGRAM_BOT_TOKEN=your-bot-token
ASSISTANT_NAME=YourName

Start: node dist/index.js

Or use Claude Code guided setup: cd ghostclaw && claude then type /setup-ghostclaw.

What's included

Everything below ships with every install.

Channels

• Telegram — DM it like a person. In groups, responds when mentioned. Voice notes supported. This is the primary interface.

Core capabilities

• Full machine access — bash, files, web search, email. No sandbox, no permission prompts.
• Web research — Perplexity-powered search and deep research. Ask anything current, it searches and cites sources.
• Ralph loops — autonomous multi-task engine. Hand it a checklist, it works through tasks one by one overnight.
• Scheduled tasks — "check Hacker News every morning" or cron syntax. Natural language or precise.
• Per-group personality — each chat gets its own CLAUDE.md defining tone, memory, and rules.
• Model selection — switch between Sonnet, Opus, Haiku from Telegram. Just type /model.
• Cost controls — every turn writes a usage_events row. /budget shows today's spend. /budget set 10 caps daily spend at $10 — once hit, GhostClaw falls back to fast-path-only (cheap chat) until UTC midnight.

Mission Control

Built-in dashboard at localhost:3333. Real-time activity feed, task scheduling, soul editing, research runs.

Architecture

You (Telegram) → GhostClaw → Claude (Agent SDK) → Response

One process. SQLite state. Claude runs as a direct child process. No containers, no Docker, no Kubernetes. Full system access — that's the point.

Optional skills

Add capabilities with a command. Each skill is a markdown file — security-scanned before install.

| Command | What it adds | |---------|-------------| | /add-gmail-agent | Gmail read/send — verification codes, urgent flags, summaries | | /add-voice-transcription | Voice note transcription (ElevenLabs Scribe) | | /add-voice-reply | Bot replies with voice notes (ElevenLabs TTS) | | /add-heartbeat | Periodic health checks — disk, logs, services | | /add-morning-briefing | Daily or weekly briefings | | /add-slack | Slack as an additional channel | | /add-telegram-swarm | Multi-bot agent teams in Telegram | | /pr-babysitter | Automated PR monitoring — CI fixes, review resolution | | /run-ralph | Autonomous overnight task loop | | /update-ghostclaw | Safe update: backup, pull, migrate, rebuild, restart |

Browse all 46 skills → including marketing, SEO, design, and community-built skills.

Build your own — skills are markdown files. Ask Claude to write one or create it yourself.

Telegram commands

| Command | What it does | |---------|-------------| | /reset | Kill stalled agent, wipe session. Next message starts fresh. | | /status | Active agents, queue depth, uptime. | | /model | View or switch AI model (sonnet, opus, haiku). | | /budget | Today's spend; /budget set N to cap, /budget off to disable. | | /skills | List installed skills. | | /update | Pull latest code, rebuild, restart — no SSH needed. | | /ping | Check if the bot is online. |

Updating

Send /update in Telegram. No SSH required.

For a full safe update with backup and rollback tag:

/update-ghostclaw

On a version before v0.6.0? Update manually:

cd ghostclaw
git pull origin main
npm install
npm run build
# macOS: launchctl kickstart -k gui/$(id -u)/com.ghostclaw
# Linux: systemctl --user restart ghostclaw

Migrating from v0.7

v0.8.0 is a redesign around the Anthropic API. Claude Max / OAuth login is no longer supported — the keychain read, CLAUDE_CODE_OAUTH_TOKEN, and the .env write-back fallback are all removed. Every agent turn now hits the API directly and is billed per-token.

If you're on v0.7.x:

1. Get an API key at console.anthropic.com.
2. In .env, replace CLAUDE_CODE_OAUTH_TOKEN=... with ANTHROPIC_API_KEY=sk-ant-....
3. Set a daily cap so the API bill can't surprise you: GHOSTCLAW_DAILY_BUDGET_USD=5 (or /budget set 5 from Telegram). When today's spend hits the cap, GhostClaw falls back to fast-path-only chat until UTC midnight.
4. /update (or pull, build, restart manually).
5. Send /budget in Telegram after a day to sanity-check spend.

Containers and WhatsApp were also removed in this line — if you had TELEGRAM_ONLY=true set, you can drop it (no-op now).

Configuration

All config lives in .env. The setup wizard creates this.

| Variable | Required | Description | |----------|----------|-------------| | ANTHROPIC_API_KEY | Yes | Get one at console.anthropic.com | | ASSISTANT_NAME | Yes | Bot name (trigger word in groups) | | TELEGRAM_BOT_TOKEN | Yes | From @BotFather | | GHOSTCLAW_MODEL | No | Default: claude-sonnet-4-6. Also: claude-opus-4-7, claude-haiku-4-5 | | GHOSTCLAW_FAST_PATH_MODEL | No | Cheap triage layer. Default: claude-sonnet-4-6. Set to claude-haiku-4-5 to cut triage cost ~3x (at the price of weaker handoff behaviour) | | GHOSTCLAW_DAILY_BUDGET_USD | No | Cap daily spend; auto-falls back to fast-path-only when hit. Manage from Telegram with /budget | | ELEVENLABS_API_KEY | No | For voice transcription and replies | | GMAIL_MCP_ENABLED | No | Set 1 for email integration |

FAQ

What does it cost? Anthropic API usage (pay-as-you-go) and optionally ElevenLabs for voice. No platform fees. Set GHOSTCLAW_DAILY_BUDGET_USD or /budget set N to cap daily spend.

Is this secure? The bot has full access to its machine. That's the design — run it on dedicated hardware with fresh accounts, not your daily driver. Skills are security-scanned before install.

Can I run it on a Raspberry Pi? Untested but should work on any Linux ARM/x64 box with Node.js 20+.

Community

Join the GhostClaw community on Telegram to share problems, suggestions, or see what others are building.

Credits

GhostClaw wouldn't exist without the work of others.

NanoClaw by qwibitai — the foundation. GhostClaw is a fork of NanoClaw. The core architecture, ag