Your First Agent

After installing, bring up your first agent with the guided wizard:

rantaiclaw setup

The wizard walks you through seven decisions, each with a sensible default. It writes a profile under ~/.rantaiclaw/profiles/default/ (or whichever profile is active — see Profiles).

1. Provider

Pick the LLM provider your agent will use. RantAIClaw ships with 30+ provider integrations — the wizard surfaces the most common:

• OpenRouter — recommended starting point; one API key reaches 200+ models
• Anthropic — Claude Sonnet, Opus, Haiku
• OpenAI — GPT-4o, o1, o3
• Google Gemini — Gemini 2.5 Pro / Flash
• Copilot — GitHub Copilot models (device-code OAuth)
• Local — Ollama, LM Studio, llama.cpp

Plus regional/specialty providers (xAI/Grok, Groq, Mistral, DeepSeek, Together, Fireworks, Perplexity, Cohere, Moonshot/Kimi, GLM/Zhipu, Qwen, MiniMax, Baidu, Doubao, ZAI). Default model out of the box is anthropic/claude-sonnet-4.6 via OpenRouter.

You can add more providers later without restarting (set them up in config or via subsequent rantaiclaw setup runs).

2. Approval preset

Choose how much human-in-the-loop oversight tool calls require. The wizard offers four named presets:

Smart is the recommended starting default. See Autonomy Levels for the full mechanics — the runtime enum has only three values (read_only, supervised, full); the Manual / Smart / Strict / Off names are preset bundles the wizard writes (the numeric L1–L4 prefixes were dropped in v0.6.40, though legacy ids still parse).

3. Channels

Pick where the agent should listen and reply. You can select multiple at once. Built-in channels:

• cli, dingtalk, discord, email_channel, imessage, irc, linq, mattermost, nextcloud_talk, qq, qr_terminal, signal, slack, telegram, whatsapp
• Feature-gated: whatsapp_web, lark, matrix (E2EE)

The wizard prompts for credentials per channel and saves them encrypted as enc2:<hex> strings inline in config.toml.

Allowlist warning. Most channels treat empty allowlist as offline (deny-by-default). The wizard prompts you for the allowlist values it needs — don’t skip them or the channel will silently never respond. Email is the only exception that allows-all on empty allowlist.

4. Persona

A persona is a system-prompt + behavioral profile. The wizard offers built-in presets bundled with the binary, plus a custom option.

Personas are written to <profile>/persona/persona.toml + <profile>/persona/SYSTEM.md. The wizard’s preset choice copies one of the bundled src/persona/presets/*.md files into the active profile.

You can swap personas by editing those files or running rantaiclaw personality to change the active one.

5. Skills

Skills are markdown- or TOML-defined capabilities with embedded tools and instructions. The wizard:

• Materializes the bundled starter pack (5 skills compiled into the binary) into <profile>/skills/
• Optionally enables open-skills auto-sync (pulls from besoeasy/open-skills every 7 days)
• Optionally enables SkillForge auto-discovery (off by default)

You can add skills later from any git URL or local path:

rantaiclaw skills install <git-url-or-path>
rantaiclaw skills list
rantaiclaw skills show <name>
rantaiclaw skills remove <name>

6. MCP servers (optional)

If you want the agent’s process tree to supervise Model Context Protocol  servers, the wizard lets you pick from a curated list (GitHub, Notion, Linear, Slack, Google Drive/Calendar/Gmail, etc.). The wizard:

1. Prompts for credentials (or kicks off OAuth for Google services)
2. Spawns the configured server and runs an initialize handshake (5s timeout) to verify it works
3. Writes the spec into [mcp_servers.<name>] in the active profile’s config.toml

Important caveat: today the supervisor only manages the processes. The MCP servers’ tools are not yet integrated with the agent loop — the LLM cannot directly call MCP-server tools. This is documented work-in-progress; see MCP Servers.

7. Knowledge Base (optional)

The default binary ships with the kb feature, so a bare rantaiclaw setup (or onboard) offers a Knowledge Base step. It lets the agent search documents you ingest. The wizard:

1. Asks whether to enable the Knowledge Base (default: no).
2. Resolves an embedding API key — reuse the main provider key when it’s an OpenRouter key, enter a separate key, or skip (which leaves the Knowledge Base disabled).
3. Optionally resolves an OCR / vision key for scanned documents — reuse the embedding key, enter a different key, or skip OCR.

Both keys are written to [knowledge] in the active profile’s config.toml (embedding_api_key / vision_api_key) and encrypted at rest as enc2:<hex>. Environment variables override the stored config at load: KB_EMBEDDING_API_KEY for embeddings and KB_EXTRACT_VISION_API_KEY for OCR/vision, with OPENROUTER_API_KEY as the final fallback for both.

You can (re)configure just this section later with rantaiclaw setup knowledge. For ingestion, retrieval, and the full option surface, see Knowledge Base and its Configuration reference.

Start chatting

The simplest way to talk to your agent:

rantaiclaw chat                    # launches the TUI (with feature 'tui', the default build)

For a one-shot CLI message:

rantaiclaw agent --message "hello"

For an interactive REPL on the CLI channel:

rantaiclaw agent

For production deployment, run the daemon — it boots the gateway, all configured channels, the heartbeat, and the scheduler:

rantaiclaw daemon

The daemon’s components are each supervised with backoff restart, so a misbehaving channel won’t take the whole agent down.

Where things live

All under ~/.rantaiclaw/:

Same paths on Linux, macOS, and Windows. No XDG, no ~/Library/Application Support. The agent uses home_dir() and tucks everything under <home>/.rantaiclaw/.

Next

• Verify the install with rantaiclaw doctor.
• Learn how the runtime is built so you can extend it.
• Read Profiles if you want to run multiple agents on the same host.