IronClaw Quick Start — Install & First Run

Prerequisites

• Node.js 22.16 or Node 24 — same requirement as OpenClaw. Check: node --version
• A model provider API key — Anthropic, OpenAI, or a local Ollama install. IronClaw supports the same providers as OpenClaw.
• Linux or macOS recommended — Windows works but the sandbox enforcement layer has limited filesystem policy support on Windows as of April 2026. If you're on Windows, use WSL2.

Step 1 — Install IronClaw

npm install -g ironclaw

# Verify install
ironclaw --version
# e.g. ironclaw/2026.04.1 linux-x64 node/22.16.0

IronClaw installs alongside OpenClaw — they don't conflict. The CLI command is ironclaw, not openclaw. The config file lives at ~/.ironclaw/ironclaw.json, separate from OpenClaw's config.

Step 2 — Run the Security Onboarding Wizard

ironclaw onboard

The wizard asks six questions. Here's what each one configures and what to answer:

When onboarding completes, IronClaw writes the initial config to ~/.ironclaw/ironclaw.json and creates an empty allowlist at ~/.ironclaw/allowlist.json.

Step 3 — Start the Gateway

ironclaw gateway

# Expected output:
# [ironclaw] gateway v2026.04.1 starting
# [ironclaw] sandbox: strict
# [ironclaw] allowlist: 0 skills authorised
# [ironclaw] audit log: ~/.ironclaw/audit.log
# [ironclaw] gateway ready on 127.0.0.1:18790

IronClaw runs on port 18790 by default — one port above OpenClaw's 18789 — so both can run simultaneously on the same machine.

Verify the health endpoint:

curl http://127.0.0.1:18790/health
# {"status":"ok","sandbox":"strict","skillsAuthorised":0}

If the gateway fails to start, run:

ironclaw doctor
# Checks config validity, sandbox enforcement, and audit log write access

Step 4 — Understand What's Locked Down

Before adding skills or channels, it helps to know exactly what IronClaw restricts by default that OpenClaw doesn't:

Step 5 — Add Your First Skill to the Allowlist

Without allowlisted skills, your agent can only answer questions using its model — no tools. Add a skill to the allowlist:

# Install the skill first (same command as OpenClaw)
ironclaw skill install daily-brief

# Then authorise it
ironclaw allowlist add daily-brief

# Verify
ironclaw allowlist list
# daily-brief    installed   authorised   no-network   workspace-only

The daily-brief skill is a good first test because it requires no network access and no shell commands — it works entirely within the workspace directory. It should work immediately after allowlisting.

For skills that need network access (GitHub, weather, email), you also need to add a network grant. See the full Skill Allowlisting Guide for the complete process.

Step 6 — Add a Channel

Once the gateway is running and at least one skill is working, add a channel. Telegram is the simplest to test:

# Add channel config to ~/.ironclaw/ironclaw.json
ironclaw config set channels.telegram.enabled true
ironclaw config set channels.telegram.botToken '${TELEGRAM_BOT_TOKEN}'
ironclaw config set channels.telegram.dmPolicy '"allowlist"'
ironclaw config set channels.telegram.allowFrom '["YOUR_NUMERIC_TELEGRAM_ID"]'

# Reload config
ironclaw config reload

Running as a System Service

For production use, run IronClaw as a systemd service so it survives reboots:

# Create the service file
sudo tee /etc/systemd/system/ironclaw.service << 'EOF'
[Unit]
Description=IronClaw AI Agent Gateway
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/usr/local/bin/ironclaw gateway
Restart=on-failure
RestartSec=5
# Environment variables for API keys
EnvironmentFile=/home/YOUR_USERNAME/.ironclaw/.env

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable ironclaw
sudo systemctl start ironclaw
sudo systemctl status ironclaw

Store API keys in ~/.ironclaw/.env with chmod 600, not in the JSON config file:

ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=123456789:ABC...

Useful Commands