Docs / Bot / Setup

Setup guide.

From zero to running bot in under five minutes. The interactive wizard handles project scaffolding, Docker config, and API key setup. You just answer the prompts.

Quick start

Run the wizard.

One command scaffolds everything: Docker Compose file, .env with your keys, IDENTITY.md and SOUL.md templates, and OpenClaw configuration.

npx @keyoku/bot init

Init wizard

What the wizard asks.

The wizard runs interactively in your terminal. Each prompt has sensible defaults — press Enter to accept them.

Step 01

Prerequisites check

Verifies Docker and Docker Compose are installed on your system

Step 02

Bot LLM provider

OpenAI (API key), OpenAI (ChatGPT subscription), Anthropic, or Google Gemini

Step 03

Bot model

Choose the specific model for chat (e.g., openai/gpt-5.4, anthropic/claude-sonnet-4-6)

Step 04

API key / OAuth

Enter your LLM provider API key, or configure ChatGPT OAuth (no key needed)

Step 05

Extraction LLM

Which provider and model handles memory extraction (can differ from chat LLM for cost savings)

Step 06

Embedding provider

Choose Gemini or OpenAI for semantic memory search embeddings

Step 07

Channel

Telegram, Discord, or API-only

Step 08

Channel credentials

Telegram bot token or Discord bot token and app ID (skipped for API-only)

Step 09

Generate config and start

Writes .env and docker-compose.yml, then optionally runs docker compose up -d

Telegram bot setup.

Create a bot through Telegram's official @BotFather, then paste the token into the wizard (or your .env file).

Step 1

Create the bot

Open Telegram, message @BotFather, send /newbot. Follow the prompts to set a name and username.

Step 2

Copy the token

BotFather replies with an HTTP API token. Copy it — this goes into TELEGRAM_BOT_TOKEN in your .env file.

Step 3

Set commands

Send /setcommands to @BotFather, select your bot, then paste: start - Start the bot, help - Show help. This registers slash commands in the Telegram UI.

Discord

Discord bot setup.

Discord requires an application, a bot user, gateway intents, and an OAuth2 invite URL. It takes a few more steps than Telegram but the wizard guides you through it.

Step 1

Create application

Go to discord.com/developers/applications and click New Application. Give it a name.

Step 2

Create bot

In your application, go to the Bot tab and click Add Bot. Copy the token — this is DISCORD_BOT_TOKEN.

Step 3

Enable intents

On the Bot tab, enable Message Content Intent under Privileged Gateway Intents. This lets the bot read message content.

Step 4

Generate invite URL

Go to OAuth2 > URL Generator. Select the bot scope. Under Bot Permissions, enable: Send Messages, Read Message History, Embed Links, Attach Files, Use Slash Commands.

Step 5

Invite to server

Copy the generated URL and open it in your browser. Select your server and authorize the bot.

Step 6

Copy App ID

On the General Information tab, copy the Application ID. This goes into DISCORD_APP_ID in your .env file.

Running

Start the stack.

If you didn't start during init, bring up the Docker Compose stack manually. The status command confirms everything is healthy.

# Start all services in background
docker compose up -d

# Verify health, memory stats, and watcher
npx @keyoku/bot status

Configuration

Environment variables.

All configuration lives in the .env file generated by the wizard. Edit it directly to change providers, models, or channel settings.

required

BOT_MODEL

The LLM model used for chat responses.

Uses provider prefix format. Examples: openai/gpt-5.4, anthropic/claude-sonnet-4-6, gemini/gemini-2.5-flash.

default: Provider-dependent

optional

OPENAI_API_KEY

OpenAI API key.

Required when using OpenAI as bot, extraction, or embedding provider.

default: ---

optional

ANTHROPIC_API_KEY

Anthropic API key.

Required when using Anthropic as bot or extraction provider.

default: ---

optional

GEMINI_API_KEY

Google Gemini API key.

Required when using Gemini as bot, extraction, or embedding provider.

default: ---

optional

KEYOKU_EXTRACTION_PROVIDER

LLM provider for memory extraction.

Accepts "openai", "anthropic", or "gemini". Can differ from the chat provider for cost optimization.

default: Same as chat provider

optional

KEYOKU_EXTRACTION_MODEL

Specific model for extraction.

Use a cheaper/faster model here if chat uses a premium one.

default: Provider-dependent

optional

KEYOKU_EMBEDDING_PROVIDER

Provider for semantic memory search embeddings.

Accepts "gemini" or "openai".

default: gemini

optional

KEYOKU_EMBEDDING_MODEL

Model used for generating embeddings.

Examples: gemini-embedding-001, text-embedding-3-small.

default: gemini-embedding-001

optional

KEYOKU_SESSION_TOKEN

Authentication token for the Keyoku engine API.

Auto-generated during init as a secure random hex string.

default: Auto-generated

optional

KEYOKU_DB_PATH

Path to the Keyoku SQLite database file inside the container.

default: /data/keyoku.db

optional

KEYOKU_PORT

Port the Keyoku engine listens on inside the container.

default: 18900

optional

KEYOKU_WATCHER_AUTO_START

Whether the heartbeat watcher starts automatically when the engine launches.

default: true

optional

KEYOKU_ADAPTIVE_HEARTBEAT

Enable adaptive heartbeat intervals.

Adjusts based on activity, time of day, and signal density.

default: true

optional

KEYOKU_WATCHER_ENTITY_IDS

Comma-separated list of entity IDs the watcher monitors for heartbeat signals.

default: default

optional

KEYOKU_WATCHER_BASE_INTERVAL

Base heartbeat interval in milliseconds (300000 = 5 minutes).

Adaptive mode adjusts this dynamically.

default: 300000

optional

OPENCLAW_GATEWAY_TOKEN

Authentication token for the OpenClaw gateway.

Auto-generated during init as a secure random hex string.

default: Auto-generated

required

BOT_CHANNEL

Active channel: "telegram", "discord", or omitted for API-only.

Determines which adapter loads at startup.

default: telegram

optional

TELEGRAM_BOT_TOKEN

Bot token from @BotFather.

Required when BOT_CHANNEL is telegram.

default: ---

optional

DISCORD_BOT_TOKEN

Bot token from the Discord Developer Portal.

Required when BOT_CHANNEL is discord.

default: ---

optional

DISCORD_APP_ID

Application ID from the Discord Developer Portal.

Required for Discord channel.

default: ---

Bot running?

Now customize its personality with IDENTITY.md and SOUL.md, or explore the CLI commands for debugging and memory inspection.

Customization CLI commands →