| name | setup |
| description | Walk through first-time setup of everclaw — prerequisites, config, database, and verification |
/setup — everclaw first-time setup
Guide the developer through a complete, working everclaw setup. Be autonomous: detect what's already done, fix problems yourself, and only ask questions when a real choice is needed.
Instructions
Work through each phase in order. Use TaskCreate to track progress. Verify each phase before moving to the next. If a step fails, diagnose and fix it — don't just report the error.
Phase 1: Prerequisites
Check the following tools are available. Run the checks in parallel.
-
Node.js 22.18+ — run node --version and parse the semver. If missing or too old, stop and tell the user to install Node 22.18+ (link to https://nodejs.org). This is not something we can install for them.
-
pnpm — run pnpm --version. If missing, run corepack enable then corepack prepare pnpm@latest --activate to install it.
-
Docker & Docker Compose — run docker --version and docker compose version. Note availability but don't fail here — the user may choose bare metal.
-
PostgreSQL client — run psql --version. Note availability for bare metal path.
Report what was found and what was installed.
Phase 2: Choose deployment method
Use AskUserQuestion to ask:
How do you want to run PostgreSQL?
- Docker Compose (Recommended) — Postgres runs in a container alongside the app. Simplest setup.
- Bare metal — You manage your own PostgreSQL instance. Requires
psql and a running Postgres server.
If Docker is not installed and user picks Docker, help them understand they need to install Docker first and link to https://docs.docker.com/get-docker/.
Phase 3: Install dependencies
pnpm install
Verify it succeeds (exit code 0, node_modules/ exists). If it fails:
- Check if
pnpm-lock.yaml exists — if not, this is expected for a fresh clone
- Check for network errors and retry once
- Check for Node version incompatibility in the error output
Phase 4: Configure .env
Check if .env already exists in the project root.
If it exists, use AskUserQuestion:
A .env file already exists. What would you like to do?
- Keep it — Skip configuration, use existing values
- Reconfigure — Create a new
.env file
If creating/reconfiguring, collect secrets using AskUserQuestion — one question per secret. NEVER echo secrets to the terminal or pass them as bash arguments. Write the file using the Write tool.
-
ANTHROPIC_API_KEY (required) — Ask for their API key. Mention https://console.anthropic.com/settings/keys.
-
BRAVE_SEARCH_API_KEY (optional) — Use AskUserQuestion to ask if they want web search:
Enable web search? Requires a free Brave Search API key (2000 queries/month free).
If yes, ask for the key. Mention https://brave.com/search/api/.
-
OPENAI_API_KEY (optional) — Use AskUserQuestion to ask if they want voice transcription:
Enable voice message transcription? When configured, the bot transcribes voice messages (Telegram, WhatsApp) using OpenAI Whisper (~$0.006/min of audio).
If yes, ask for the key. Mention https://platform.openai.com/api-keys.
Write the .env file with collected values. No channel configuration here — that comes in Phase 8. Format:
ANTHROPIC_API_KEY=<key>
# Optional: enables the web_search tool (free tier: 2000 queries/month)
# BRAVE_SEARCH_API_KEY=BSA...
# Optional: enables voice message transcription (~$0.006/min of audio)
# OPENAI_API_KEY=sk-...
# Chat ID allowlist — configured during channel setup
# ALLOWED_CHAT_IDS=
Uncomment lines for keys that were provided.
Phase 5: Database setup (bare metal only)
Skip this phase entirely if the user chose Docker — Docker Compose auto-initializes the database via sql/ mount to /docker-entrypoint-initdb.d.
For bare metal:
-
Check the DATABASE_URL environment variable. Default is postgresql://localhost/absurd. Ask the user if this is correct or if they want a custom URL.
-
Check if the database exists:
psql "$DATABASE_URL" -c "SELECT 1" 2>&1
If it doesn't exist, try to create it:
createdb absurd
-
Run the schema migrations:
psql "$DATABASE_URL" -f sql/001-absurd.sql
psql "$DATABASE_URL" -f sql/002-assistant.sql
psql "$DATABASE_URL" -f sql/003-channel-abstraction.sql
-
Verify tables were created:
psql "$DATABASE_URL" -c "SELECT table_schema, table_name FROM information_schema.tables WHERE table_schema IN ('absurd', 'assistant')"
If any step fails, show the error and help diagnose (wrong credentials, Postgres not running, etc).
Phase 6: Ensure writable directories
Create these directories if they don't exist:
mkdir -p data/notes data/auth skills scripts servers
These are where the agent stores notes, auth state, skill files, tool scripts, and MCP server configs at runtime.
Phase 7: Run tests
pnpm test
All tests should pass. If tests fail:
- Read the test output carefully
- Check if it's a dependency issue (re-run
pnpm install)
- Check if it's a TypeScript version issue
- Fix the issue if possible, or report it clearly
Phase 8: Pick first channel
Use AskUserQuestion to ask:
Which messaging channel do you want to set up first?
- Telegram — Chat bot via BotFather. Simplest to set up.
- Discord — Server/DM bot via Discord Developer Portal.
- Slack — Workspace bot via Slack API (Socket Mode).
- WhatsApp — Personal messaging via QR code scan.
- Gmail — Email via Google OAuth2. Most complex setup.
You can add more channels later with /add-channel-*.
Based on their choice, tell the user:
- Telegram → "Run
/add-channel-telegram to set up Telegram."
- Discord → "Run
/add-channel-discord to set up Discord."
- Slack → "Run
/add-channel-slack to set up Slack."
- WhatsApp → "Run
/add-channel-whatsapp to set up WhatsApp."
- Gmail → "Run
/add-channel-gmail to set up Gmail."
Phase 9: Wrap up
Tell the user:
Core setup is complete. Run the channel setup command from Phase 8 to connect your first messaging channel. That skill will walk you through configuration, first start, and verification.
Provide these useful commands:
- Run tests:
pnpm test
- Type check:
npx tsc --noEmit
- Start (Docker):
docker compose up --build
- Start (bare metal):
node src/index.ts
- Stop (Docker):
docker compose down
- Stop (bare metal): Ctrl+C
Adding more channels later:
/add-channel-telegram — Telegram/add-channel-discord — Discord/add-channel-slack — Slack/add-channel-whatsapp — WhatsApp/add-channel-gmail — Gmail
