Quickstart

This guide gets you from zero to a working MonoClaw setup that survives real use. Choose a provider, verify a working chat, and know exactly what to do when something breaks.

Since MonoClaw is already pre-installed on your system, you can bypass the installation process and jump straight to choosing a model provider.

The fastest path

Pick the row that matches your goal:

Rule of thumb: if Mona cannot complete a normal chat, do not add more features yet. Get one clean conversation working first, then layer on gateway, cron, skills, voice, or routing.

1. Choose a Provider

The single most important setup step. Use monoclaw model to walk through the choice interactively:

monoclaw model

Good defaults:

For most first-time users: choose a provider, accept the defaults unless you know why you're changing them.

How settings are stored

MonoClaw separates secrets from normal config:

• Secrets and tokens → ~/.monoclaw/.env
• Non-secret settings → ~/.monoclaw/config.yaml

The easiest way to set values correctly is through the CLI:

monoclaw config set model anthropic/claude-opus-4.6
monoclaw config set terminal.backend docker
monoclaw config set OPENROUTER_API_KEY sk-or-...

The right value goes to the right file automatically.

2. Run Your First Chat

monoclaw            # classic CLI
monoclaw --tui      # modern TUI (recommended)

You'll see a welcome banner with your model, available tools, and skills. Use a prompt that's specific and easy to verify:

Summarize this repo in 5 bullets and tell me what the main entrypoint is.

Check my current directory and tell me what looks like the main project file.

What success looks like:

• The banner shows your chosen model/provider
• Mona replies without error
• She can use a tool if needed (terminal, file read, web search)
• The conversation continues normally for more than one turn

If that works, you're past the hardest part.

3. Verify Sessions Work

Before moving on, make sure resume works:

monoclaw --continue    # Resume the most recent session
monoclaw -c            # Short form

That should bring you back to the session you just had.

4. Try Key Features

Use the terminal

❯ What's my disk usage? Show the top 5 largest directories.

The agent runs terminal commands on your behalf and shows results.

Slash commands

Type / to see an autocomplete dropdown of all commands:

Multi-line input

Press Alt+Enter, Ctrl+J, or Shift+Enter to add a new line. Shift+Enter requires a terminal that sends it as a distinct sequence (Kitty / foot / WezTerm / Ghostty by default; iTerm2 / Alacritty / VS Code terminal once the Kitty keyboard protocol is enabled). Alt+Enter and Ctrl+J work in every terminal.

Interrupt the agent

If the agent is taking too long, type a new message and press Enter — it interrupts the current task and switches to your new instructions. Ctrl+C also works.

5. Add the Next Layer

Only after the base chat works. Pick what you need:

Bot or shared assistant

monoclaw gateway setup    # Interactive platform configuration

Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant.

Automation and tools

• monoclaw tools — tune tool access per platform
• monoclaw skills — browse and install reusable workflows
• Cron — only after your bot or CLI setup is stable

Sandboxed terminal

For safety, run the agent in a Docker container or on a remote server:

monoclaw config set terminal.backend docker    # Docker isolation
monoclaw config set terminal.backend ssh       # Remote server

Voice mode

cd ~/.monoclaw/monoclaw-runtime
uv pip install -e ".[voice]"

Then in the CLI: /voice on. Press Ctrl+B to record.

Skills

monoclaw skills search kubernetes
monoclaw skills install openai/skills/k8s

Or use /skills inside a chat session.

MCP servers

# Add to ~/.monoclaw/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Editor integration (ACP)

ACP support ships with the standard [all] extras and is pre-installed. Just run:

monoclaw acp

Common Failure Modes

These are the problems that waste the most time:

Recovery Toolkit

When something feels off, use this order:

1. monoclaw doctor
2. monoclaw model
3. monoclaw setup
4. monoclaw sessions list
5. monoclaw --continue
6. monoclaw gateway status

That sequence gets you from "broken vibes" back to a known state fast.

Quick Reference