Setup Guide

Get a Gemma-powered AI agent running in minutes. Three paths depending on your setup: cloud API (fastest), Google Cloud Vertex AI (enterprise), or local hardware (private, no data leaves your machine).

Contents

• Install Gemmaclaw
• The Onboarding Wizard (what each prompt means)
• Path 1: Local (private, auto-detects your GPU)
• Path 2: Gemini API (cloud, no local hardware needed)
• Path 3: Vertex AI (enterprise, GCP integration)
• After Setup (create agents, chat, message)
• Backup and Restore (portable instance archives)
• Release Automation
• CLI Reference
• Troubleshooting

Install Gemmaclaw

Install from npm. Requires Node 22+. Docker is recommended for sandboxed tool execution but not required.

npm install -g gemmaclaw
gemmaclaw setup

Shared files: When Docker sandbox is enabled, ~/.gemmaclaw/shared/ on your machine is automatically mounted at /shared inside the container. Drop files there for the agent to use, or find agent output there after a task completes. Created automatically on first run.

Installing from source (contributors)

Contributors who need to modify the codebase use pnpm, which is required by this workspace:

git clone https://github.com/gemmaclaw/gemmaclaw.git
cd gemmaclaw
corepack enable
pnpm install
pnpm build
npm install -g .
gemmaclaw setup

Release Automation

Gemmaclaw releases use the Gemmaclaw npm Release GitHub Action. Trigger it manually to create or update the release PR. After that PR merges to main, the same workflow creates the GitHub release and publishes the tagged package to npm.

The workflow is powered by release-please. Version state lives in .release-please-manifest.json and release behavior lives in release-please-config.json. The config includes a root-level bootstrap-sha so the first release PR starts from the Gemmaclaw npm automation baseline instead of scanning the full upstream history. The workflow requires a RELEASE_PLEASE_TOKEN repository secret with contents and pull request write access because the organization blocks the default GITHUB_TOKEN from creating release PRs. npm publishing expects GitHub Actions trusted publishing to be configured for the gemmaclaw package.

The Onboarding Wizard

Running gemmaclaw setup kicks off a six-question wizard. Press Enter at any prompt to keep the bracketed default. Every question is also exposed as a CLI flag so you can script the whole flow.

1. Agent name — the identity for this assistant. Each agent has its own workspace and memory under ~/.gemmaclaw/agents/<name>/. Use main if you only run one. Flag: --agent-name <name>.
2. Run environment — do tools (shell, files, browser) execute inside a Docker sandbox or directly on your host? Container is the safer default; host is faster but the agent can read and modify your real files. Flag: --no-container.
3. Backend / provider — Local Gemma on this machine, the hosted Gemini API, or Google Cloud Vertex AI. Flag: --setup-mode local|gemini|vertex.
4. Model — for Local you can pick auto (recommended) or a specific Gemma size. Gemini and Vertex offer their own catalogs. Flag: --model <id>.
5. Thinking level — how much chain-of-thought reasoning the agent does before answering. off is fastest, medium is the sweet spot, high is best for hard problems. Flag: --thinking off|low|medium|high.
6. Starter persona (bootstrap profile) — what AGENTS.md / TOOLS.md content the wizard drops into the workspace. general is a friendly default, coding tunes the assistant for code tasks, minimal leaves the workspace empty. Flag: --bootstrap general|coding|minimal.

Example transcript (Local + Docker + auto + medium + general):

$ gemmaclaw setup
Welcome to Gemmaclaw. We'll set up an AI agent in five quick questions.

1. Agent name
   Agent name [main]: <Enter>

2. Where should the agent run its tools (shell, files, browser)?
   Choose [1/2, default=1]: <Enter>

3. Where should the model run?
   Choose [1/2/3, default=1]: <Enter>

4. Which model?
   Choose [1-5, default=1]: <Enter>

5. How much should the agent think before answering?
   Choose [1-4, default=3 (medium)]: <Enter>

6. What should the agent's starter persona look like?
   Choose [1-3, default=1 (general)]: <Enter>

Your setup:
  Agent name:  main
  Run mode:    Container (Docker sandbox for tools)
  Backend:     Local (this machine)
  Model:       auto
  Thinking:    medium
  Persona:     General assistant (recommended)

Setup complete. Try it now:
  gemmaclaw chat --agent main

Where things get written:

• Per-agent state: ~/.gemmaclaw/agents/<name>/ (manifest, sessions, auth profile)
• Workspace bootstrap files: ~/.gemmaclaw/workspace/AGENTS.md for the main agent, or ~/.gemmaclaw/workspaces/<name>/AGENTS.md for everyone else (the bootstrap profile drops AGENTS.md and, for the coding profile, TOOLS.md)
• Global config: ~/.gemmaclaw/openclaw.json (model defaults, thinking level, sandbox toggle)

Non-interactive / CI: combine --non-interactive with the per-question flags to script the whole wizard without prompts. Add --dry-run to skip backend provisioning, gateway start, and smoke tests — useful for CI smoke tests of the wizard itself. Example:

gemmaclaw setup   --non-interactive   --setup-mode local   --agent-name dev-agent   --no-container   --thinking high   --bootstrap coding   --dry-run

The Docker E2E job under test/e2e/Dockerfile.onboard-gemma exercises every major path this way and is wired into CI as a required pass via .github/workflows/onboard-gemma-e2e.yml.

Path 1: Local (Private, auto-detect hardware)

Run Gemma entirely on your machine. No data leaves your network. Gemmaclaw detects your GPU and RAM, picks the best model, downloads and provisions everything automatically.

# Auto-detect everything (recommended)
gemmaclaw setup

# Advanced: choose backend and model manually
gemmaclaw setup --advanced

# CI/scripted: non-interactive with defaults
gemmaclaw setup --non-interactive --accept-risk --no-container

What happens:

1. Hardware detection: probes GPU (NVIDIA CUDA, Apple Metal), CPU, and RAM
2. Tier classification: maps your hardware to the best Gemma 4 model
3. Provisioning: installs Ollama (or llama.cpp), pulls the model, runs smoke test
4. Configuration: writes config with the selected provider and model
5. Verification: confirms the model responds correctly

Supported backends:

Path 2: Gemini API (Cloud, no local hardware needed)

Use Google's hosted Gemini API. No local GPU, no model downloads. Get a free API key from Google AI Studio.

# Set your API key, then run setup
export GEMINI_API_KEY=YOUR_KEY
gemmaclaw setup

# Or run setup interactively (prompts for provider and key)
gemmaclaw setup

Available models: gemma-4-31b-it, gemma-3-27b-it, gemma-3-12b-it, gemma-3-4b-it, gemma-3-1b-it.

Path 3: Vertex AI (Cloud, enterprise)

For GCP-integrated deployments. Uses gcloud credentials or a service account. Requires a GCP project with the Vertex AI API enabled. Auth tokens are resolved at runtime via gcloud, so they never go stale in your config.

# Authenticate with gcloud
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

# Interactive setup (prompts for project, region, API protocol, model)
gemmaclaw setup --vertex

# Non-interactive with flags
gemmaclaw setup --vertex \
  --vertex-project my-gcp-project \
  --vertex-region us-west1 \
  --vertex-model gemma-4-31b-it

# With a service account key
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
gemmaclaw setup --vertex --vertex-project my-project

API protocol: The wizard asks you to choose between the native Gemini API and the OpenAI-compatible API. Native is the default and recommended for most setups. OpenAI-compatible is available if your tooling requires that format.

Available models: gemma-4-31b-it, gemma-3-27b-it, gemma-3-12b-it, gemma-3-4b-it, gemma-3-1b-it.

For Docker, mount your gcloud credentials:

docker run -v ~/.config/gcloud:/root/.config/gcloud gemmaclaw setup --vertex

After Setup

# Create a named agent instance
gemmaclaw create work

# Open local TUI/chat for the "work" agent
gemmaclaw tui work

# Pick an agent interactively (TTY only)
gemmaclaw tui

# Docker-backed agents open browser chat on a persistent 127.0.0.1 port
gemmaclaw tui play --no-open

# Open browser chat UI directly
gemmaclaw chat

# One-shot message from the command line
gemmaclaw message --agent work "summarize today's news"

CLI Reference

Global options available on all commands:

# Auto-detect everything (recommended)
gemmaclaw setup

# Manual backend/model selection
gemmaclaw setup --advanced

# CI/scripted environments
gemmaclaw setup --non-interactive --accept-risk --no-container

# Interactive create
gemmaclaw create work

# Non-interactive with model
gemmaclaw create dev --model ollama/gemma3:4b --workspace ~/.gemmaclaw/workspace/dev

# Scripted/CI
gemmaclaw create play --non-interactive

gemmaclaw list
gemmaclaw list --json

# Interactive picker (TTY required)
gemmaclaw ssh

# Direct shell into named agent
gemmaclaw ssh main

# Script-safe: fail immediately if no agent given
gemmaclaw ssh work --non-interactive

# Check which agents support container shell
gemmaclaw list --json | jq '.[] | {id, shellAvailable, shellUnavailableReason}'

# Create and verify a complete instance backup
gemmaclaw backup create --output ~/gemmaclaw-backups --verify

# Inspect a backup before using it
gemmaclaw backup verify ~/gemmaclaw-backups/2026-05-05T01-00-00.000Z-openclaw-backup.tar.gz

# Restore into a fresh directory for inspection
gemmaclaw backup restore ~/gemmaclaw-backups/backup.tar.gz --target ~/.gemmaclaw-restored

# Replace active state safely. Existing state is moved aside first.
gemmaclaw backup restore ~/gemmaclaw-backups/backup.tar.gz --force

gemmaclaw chat
gemmaclaw chat --agent work
gemmaclaw chat --no-open --port 3001

# One-shot message
gemmaclaw message --agent dev "summarize today's news"

# Pipe from stdin
echo "what is 2+2?" | gemmaclaw message --agent dev

# JSON output
gemmaclaw message --agent dev --text "hi" --json

# Direct named launch
gemmaclaw tui work

# Interactive agent picker (requires a TTY)
gemmaclaw tui

# Container-backed local access: print/open the per-agent localhost URL
gemmaclaw tui play --no-open

# Override the container-backed localhost port after cleanup
gemmaclaw tui play --port 9150

# Separate agents keep separate persisted ports
gemmaclaw tui work
gemmaclaw tui play

gemmaclaw gateway run --verbose
gemmaclaw gateway install && gemmaclaw gateway start
gemmaclaw gateway status

gemmaclaw models status
gemmaclaw models list
gemmaclaw models set gemma3:12b

gemmaclaw channels list
gemmaclaw channels add --channel telegram --token <bot-token>
gemmaclaw channels login --channel whatsapp
gemmaclaw channels status --probe

gemmaclaw benchmark --model gemma3:4b
gemmaclaw benchmark --mock --model gemma3:4b
gemmaclaw benchmark --filter "coding" --model gemma3:4b

gemmaclaw benchmark submit --dry-run
gemmaclaw benchmark submit

gemmaclaw doctor
gemmaclaw doctor --fix
gemmaclaw doctor --deep --fix --non-interactive

gemmaclaw plugins list
gemmaclaw plugins install @example/my-plugin
gemmaclaw plugins doctor

gemmaclaw provision --backend ollama --model gemma3:12b
gemmaclaw provision --backend llama-cpp --port 8081
gemmaclaw provision --backend gemma-cpp

Other Useful Commands

Configuration

Config lives at ~/.gemmaclaw/openclaw.json. Edit directly or use the CLI:

gemmaclaw config get gateway.port
gemmaclaw config set gateway.port 3001
gemmaclaw config validate
gemmaclaw configure

Named profiles (--profile mytest) isolate all state under ~/.gemmaclaw-mytest/, useful for testing or running multiple instances.

Troubleshooting

• Ollama download fails: check network. Binary comes from GitHub releases.
• llama.cpp server won't start: verify model at ~/.gemmaclaw/models/llama-cpp/. Re-run gemmaclaw provision --backend llama-cpp.
• gemma.cpp build fails: ensure cmake and g++ (or clang++) are installed.
• "Healthcheck failed": backend did not respond in time. Run gemmaclaw doctor.
• Port in use: use --port N or gemmaclaw setup --advanced.
• Config validation warnings: run gemmaclaw doctor --fix.
• Plugin load errors: run gemmaclaw plugins doctor.
• Channel disconnected: check gemmaclaw channels status --probe and re-login.
• Gateway won't start: try gemmaclaw gateway run --verbose, then gemmaclaw doctor --deep --fix.