ZeroClaw Setup + Troubleshooting Guide (Codespaces, WSL, Linux)

Zero to ZeroClaw Running — Kimi K2 via Groq on GitHub Codespaces

Written from a real setup session. Covers everything from a fresh environment all the way to a working Telegram-connected AI agent. No steps assumed, no shortcuts skipped.

What is ZeroClaw?

ZeroClaw is an autonomous AI agent runtime written in Rust. It's the spiritual successor to OpenClaw but built as a single static binary — no Node.js, no Python, no dependency sprawl. It runs on as little as 5MB of RAM, starts in under 10ms, and works with 22+ AI providers out of the box.

This guide sets it up with Kimi K2 Instruct via Groq (free tier, ultra-fast LPU inference) on GitHub Codespaces, connected to Telegram.

What You'll Need

Before starting, have these ready:

A GitHub Codespaces environment (free tier works)
A Groq API key — free account, no credit card needed
A Telegram account
An ngrok account + auth token — mandatory for Codespaces, free tier works
About 15–20 minutes

Part 1: Environment Setup

1.1 Update Linux packages

Always do this first on a fresh Codespace to avoid stale package issues during builds:

sudo apt update && sudo apt upgrade -y

Then install build essentials — required to compile Rust projects:

sudo apt install -y build-essential pkg-config libssl-dev curl git

1.2 Install Rust

ZeroClaw is a Rust project. You need the Rust toolchain to build it.

Check if Rust is already installed:

rustc --version
cargo --version

If not installed (or version is below 1.70), install via rustup — the official Rust installer:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

During the install prompt, choose option 1 (default installation).

After it finishes, load Rust into your current shell session:

source $HOME/.cargo/env

Verify it worked:

rustc --version
# Expected: rustc 1.7x.x (...)
cargo --version
# Expected: cargo 1.7x.x (...)

For persistence across sessions, add this to your ~/.bashrc or ~/.zshrc:
echo 'source $HOME/.cargo/env' >> ~/.bashrc
source ~/.bashrc

1.3 Install ngrok

ngrok creates a public HTTPS tunnel to your local ZeroClaw gateway — required for Codespaces (covered in detail later). Install it now so it's ready.

Check if it's already installed:

ngrok version

If not, install directly (bypasses apt to avoid unrelated repo errors):

curl -Lo ngrok.zip https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.zip
unzip ngrok.zip
sudo mv ngrok /usr/local/bin/

Verify:

ngrok version
# Expected: ngrok version 3.x.x

Connect your ngrok account with your auth token (get it from ngrok dashboard):

ngrok config add-authtoken YOUR_AUTH_TOKEN_HERE

Confirm it saved:

ngrok config check

Part 2: Install ZeroClaw

Option A: Bootstrap script (easiest)

The official bootstrap script handles Rust detection, compilation, and install in one command:

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh

For a fresh machine that needs Rust installed as part of the process:

./bootstrap.sh --install-system-deps --install-rust

Option B: Manual build (more control)

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
cargo build --release --locked
cargo install --path . --force --locked

Note on build time: The first cargo build compiles all dependencies and can take 5–15 minutes on Codespaces. Subsequent builds are much faster. This is normal — Rust compiles everything from source for the optimized release binary.

Low memory tip: The default --release profile uses codegen-units=1 specifically for compatibility with 1GB RAM devices. If your Codespace has 16GB+ and you want a faster compile, use --profile release-fast instead.

Add ZeroClaw to PATH

After install, make sure the binary is accessible:

export PATH="\(HOME/.cargo/bin:\)PATH"

Make it permanent:

echo 'export PATH="\(HOME/.cargo/bin:\)PATH"' >> ~/.bashrc
source ~/.bashrc

Verify ZeroClaw is installed:

zeroclaw --version

Part 3: Onboarding Wizard

Now run the interactive setup wizard:

zeroclaw onboard --interactive

This is an 11-step wizard. Here's what to do at each step.

[1/11] Workspace Setup

Accept the default location — just press Enter:

/home/codespace/.zeroclaw/workspace

If a config file already exists from a previous run, select Full onboarding (overwrite config.toml) to start fresh.

[2/11] AI Provider & API Key

Category: Fast inference (Groq, Fireworks, Together AI, NVIDIA NIM)
Provider: Groq — ultra-fast LPU inference
Paste your Groq API key when prompted
Fetch live models: yes — this pulls the live model list from Groq (18 models at time of writing)
Model: moonshotai/kimi-k2-instruct-0905

Known bug — Groq provider /v1 path issue: The built-in groq provider sometimes hits /openai instead of /openai/v1, causing 404 errors on chat completions. If you see this after setup, edit ~/.zeroclaw/config.toml and change default_provider to:
custom:https://api.groq.com/openai/v1
This uses Groq's OpenAI-compatible endpoint directly and bypasses the bug entirely. No other changes needed.

[3/11] Channels

CLI is always available. To also connect Telegram:

Open Telegram and message @BotFather
Send /newbot and follow the prompts to create a bot
BotFather will give you a bot token — copy-paste it, do not type it manually

Common mistake: The bot token contains both the digit 0 and the letter O. One wrong character gives you a "Connection failed" error. If your first attempt fails, look closely at the token — it's almost always a character mix-up.

When asked for allowed identities, enter your Telegram username without the @ (e.g. Vobasi). This locks the bot so only you can use it. Use * only for temporary open testing — always restrict it to your username for actual use.

[4/11] Tunnel — DO NOT SKIP ON CODESPACES

⚠️ This step is mandatory if you're on GitHub Codespaces. The wizard says "Skip this if you only use CLI or local channels" — that's misleading here.

Your ZeroClaw process runs inside a Codespace container with no public inbound access. Even with Telegram polling, your bot will be completely silent without a tunnel. This was confirmed during the real setup session — everything was configured correctly but the bot gave zero responses until the tunnel was running.

Select: ngrok — instant public URLs

Paste your ngrok auth token (the same one you used in Part 1)
Skip the custom domain — press Enter to leave it blank. Custom domains require a paid ngrok plan.

[5/11] Tool Mode & Security

Select: Sovereign (local only) — full privacy, you own every key

Composio is a managed OAuth service that routes your connections through a third party. Sovereign mode keeps everything local and self-managed, which is the whole point of self-hosting. The official ZeroClaw documentation also favours this approach.

[5b] Encrypted Secret Storage

Select Y.

Your config lives in a remote Codespace container. Encrypting secrets means your Groq API key, Telegram token, and ngrok token are not sitting as plaintext in config.toml — important if you ever accidentally expose or commit the file.

[6/11] Web & Internet Tools

web_search: Enable → DuckDuckGo (free, no API key needed)
web_fetch: Enable → fast_html2md — converts pages to Markdown, preserving headings, links, and code blocks. The model can actually parse structured content this way. The plaintext option strips all that out.
http_request: Enable this if you want the agent to make direct API calls (REST endpoints, webhooks, trading APIs etc.). When asked for allowed domains, enter * for now. You can restrict it later in config once you know which endpoints you need.

[7/11] Hardware

Codespaces has no physical hardware. Select Software Only and move on.

[8/11] Memory Configuration

Select: SQLite with Vector Search (recommended)

This combines exact keyword matching with semantic/embedding similarity search. The agent recalls context intelligently across sessions. Runs fully local with no extra setup or dependencies.

[9/11] Autonomy Level

Supervised is the right default. The agent operates within your workspace and stays within defined boundaries. You can adjust this later once you know what you want it doing autonomously.

[10/11] Project Context

Fill in your name, timezone, agent name, and preferred communication style. This populates IDENTITY.md and USER.md in your workspace. You can edit those files directly anytime to tune behaviour without re-running onboarding.

[11/11] Workspace Files

The wizard creates this layout:

/home/codespace/.zeroclaw/workspace/
├── sessions/
├── memory/
├── state/
├── cron/
├── skills/
├── IDENTITY.md       ← agent persona
├── AGENTS.md         ← behaviour guidelines
├── HEARTBEAT.md
├── SOUL.md           ← core personality
├── USER.md           ← your context and preferences
├── TOOLS.md
└── BOOTSTRAP.md

When it asks "Launch channels now?", say yes.

Part 4: Starting the Agent

After onboarding, you need two processes running simultaneously — ZeroClaw and ngrok. Use tmux to keep both alive even if your terminal closes.

Start a tmux session

tmux new -s zeroclaw

Split into two panes

Press Ctrl+B then % to split vertically.

Pane 1 — Start ZeroClaw:

zeroclaw channel start

Switch to Pane 2 (press Ctrl+B then the arrow key), then start ngrok:

ngrok http 3000

You should see ngrok output a public HTTPS URL like https://abc123.ngrok-free.app. ZeroClaw uses this as the tunnel for inbound connections.

Detach from tmux (keeps everything running)

Ctrl+B then D

Reattach when you come back

tmux attach -t zeroclaw

Part 5: Verify Everything Works

Test the CLI

zeroclaw agent -m "Hello, ZeroClaw!"

Expected output:

💬 User: Hello, ZeroClaw!
⏳ Processing message...
🤖 Reply (342ms): Hello! I'm ZeroClaw, your AI assistant...

Test Telegram

Send a message to your bot on Telegram. In your ZeroClaw terminal you should see:

💬 [telegram] from YourUsername: Hello
⏳ Processing message...
🤖 Reply (1629ms): ...

Response times of 1.5–2.5s on first messages are normal. The connection pool warms up and speeds up from there.

Screenshot of chat with AI agent

![](https://cdn.hashnode.com/uploads/covers/65173a5408392cd5ab4811b5/ff4bd254-c68f-4ffc-b311-d3983d4261ac.jpg align="middle")

Health check

zeroclaw status     # full system status
zeroclaw doctor     # diagnoses provider/connectivity issues
zeroclaw channel doctor  # channel-specific health check

Part 6: Fixing Tool Call Errors

After getting the agent running, you may see errors like this in the terminal:

tool call validation failed: attempted to call tool 'shell' which was not in request.tools

This means Kimi K2 tried to call a tool (like shell for checking the time, or ls for listing files) that wasn't included in the API request. Fix it in ~/.zeroclaw/config.toml:

Option A — Disable the shell tool (model won't attempt OS calls):

[tools]
shell = false

Option B — Enable it properly with an allowlist (recommended):

[tools]
shell = true

[autonomy]
level = "supervised"
workspace_only = true
allowed_commands = ["date", "ls", "cat", "grep", "git", "cargo", "python3", "curl", "find"]

Adding date specifically lets the agent answer time and date questions without failing. Restart zeroclaw channel start after any config change.

Part 7: Coming Back After a Break

When you return to your Codespace after closing the terminal:

# Reattach to existing tmux session (if still running)
tmux attach -t zeroclaw

# Or start fresh
tmux new -s zeroclaw
# Pane 1:
zeroclaw channel start
# Ctrl+B % for new pane, then Pane 2:
ngrok http 3000

No re-onboarding needed. Config, memory, and Telegram connection all persist.

Quick Config Reference

~/.zeroclaw/config.toml — key fields after a clean setup:

api_key = "YOUR_GROQ_API_KEY"
default_provider = "custom:https://api.groq.com/openai/v1"
default_model = "moonshotai/kimi-k2-instruct-0905"
default_temperature = 0.7

[memory]
backend = "sqlite"
auto_save = true

[tunnel]
provider = "ngrok"

[autonomy]
level = "supervised"
workspace_only = true
allowed_commands = ["date", "ls", "cat", "grep", "git", "cargo", "python3", "curl", "find"]

[tools]
shell = true

[secrets]
encrypt = true

Useful Commands

zeroclaw channel start        # start all configured channels
zeroclaw agent -m "message"   # single CLI message
zeroclaw agent                # interactive CLI mode
zeroclaw daemon               # run as background daemon
zeroclaw status               # system status
zeroclaw doctor               # diagnose issues
zeroclaw channel doctor       # channel-specific diagnostics
zeroclaw onboard --channels-only  # repair/re-add channels without full re-onboard
zeroclaw models list --provider groq  # list available models

Terminal view below:

![](https://cdn.hashnode.com/uploads/covers/65173a5408392cd5ab4811b5/702e1457-1925-4f66-b73c-79e0fd3f2d08.png align="middle")

What to Explore Next

Once the agent is running:

Skills — drop .md instruction files into ~/.zeroclaw/workspace/skills/ for domain-specific agent behaviour
Cron — schedule autonomous tasks in ~/.zeroclaw/workspace/cron/
IDENTITY.md — edit directly to shape the agent's persona beyond onboarding defaults
SOUL.md — deeper personality and values configuration
Migrate from OpenClaw — zeroclaw migrate openclaw --dry-run if you're coming from OpenClaw

For 24/7 uptime

Codespaces is great for setup and testing but not persistent hosting — processes die when the session ends. For always-on deployment, a small VPS works well:

# On your VPS, install as a system service
zeroclaw service install
zeroclaw service status

A $4–6/month DigitalOcean or Hetzner droplet runs ZeroClaw comfortably given its sub-5MB memory footprint.

Credentials Security

Never share or commit your bot token, Groq API key, or ngrok auth token
If any credential is exposed, revoke immediately:
- Telegram: @BotFather → /mybots → your bot → API Token → Revoke
- ngrok: dashboard.ngrok.com/tunnels/authtokens → delete → regenerate
- Groq: console.groq.com/keys → revoke → create new
After revoking, update ~/.zeroclaw/config.toml with the new values

Troubleshooting

Problem	Likely Cause	Fix
Telegram bot not responding	No tunnel running	Start `ngrok http 3000` alongside `zeroclaw channel start`
`404` on chat completions	Built-in groq provider bug	Set `default_provider = "custom:https://api.groq.com/openai/v1"`
Tool call validation failed	Shell tool not registered	Add `[tools] shell = true` and `allowed_commands` to config
"Connection failed" on Telegram token	Token typo	Copy-paste directly from BotFather — check `0` vs `O`
`zeroclaw: command not found`	PATH not set	Run `export PATH="$HOME/.cargo/bin:$PATH"` and add to `~/.bashrc`
`cargo build` out of memory	Codespace RAM limit	Use default `--release` (not `release-fast`) — it's optimised for 1GB RAM
`ignoring message from unauthorized user`	Identity not allowlisted	Add your Telegram username to the channel allowlist in config, or run `zeroclaw onboard --channels-only`
SQLite database error	Workspace permissions	Check disk space and that `~/.zeroclaw/workspace` is writable

Written from a real setup session on GitHub Codespaces — March 2026

Command Palette