Obsidian-Vault/Personal/Areas/Servers/TrueNAS/OpenClaw.md

OpenClaw on TrueNAS SCALE

Self-hosted AI agent gateway that connects LLMs to messaging platforms (Telegram, Discord, WhatsApp). Runs as a persistent daemon — can message proactively, execute shell commands, manage files, and automate tasks.

• Previously known as: ClawdBot, MoltBot
• GitHub: https://github.com/openclaw/openclaw
• Docs: https://docs.openclaw.ai

Prerequisites

• TrueNAS SCALE (24.10 Electric Eel or newer recommended — native Docker support)
• Dockge running on TrueNAS for Docker Compose management
• A dataset for OpenClaw storage: tank/configs/openclaw
• NanoGPT API key from https://nano-gpt.com (or OpenRouter key from https://openrouter.ai)
• Telegram bot token from @BotFather

1. Create Storage Datasets

In TrueNAS web UI, create two datasets under your apps pool:

tank/configs/openclaw/config    # maps to ~/.openclaw
tank/configs/openclaw/workspace # maps to ~/openclaw/workspace

Set permissions to UID 1000 (the container runs as node uid 1000):

chown -R 1000:1000 /mnt/tank/configs/openclaw/config
chown -R 1000:1000 /mnt/tank/configs/openclaw/workspace

2. Create the Telegram Bot

1. Open Telegram, search for @BotFather
2. Send /newbot
3. Choose a name and username (username must end in bot)
4. Save the bot token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

3. Deploy via Dockge

In Dockge, create a new stack called openclaw.

Compose YAML

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - /mnt/tank/configs/openclaw/config:/home/node/.openclaw
      - /mnt/tank/configs/openclaw/workspace:/home/node/workspace
    environment:
      - NANO_GPT_API_KEY=${NANO_GPT_API_KEY}
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
    command: ["node", "openclaw.mjs", "gateway", "--allow-unconfigured", "--bind", "lan"]

  openclaw-cli:
    image: ghcr.io/openclaw/openclaw:latest
    volumes:
      - /mnt/tank/configs/openclaw/config:/home/node/.openclaw
      - /mnt/tank/configs/openclaw/workspace:/home/node/workspace
    environment:
      - NANO_GPT_API_KEY=${NANO_GPT_API_KEY}
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
    entrypoint: ["node", "openclaw.mjs"]
    profiles:
      - cli

Environment Variables

In the Dockge .env section, add:

NANO_GPT_API_KEY=your-nanogpt-key-here
OPENROUTER_API_KEY=your-openrouter-key-here

First Run

Before starting the stack normally, run the onboarding wizard via SSH:

cd /mnt/tank/stacks/openclaw
docker compose run --rm openclaw-cli onboard --no-install-daemon

The --no-install-daemon flag is required in Docker since the gateway runs as a separate container, not as a system daemon.

After onboarding completes, start the stack from the Dockge UI (or docker compose up -d openclaw-gateway).

4. Configure OpenClaw

After the container is running, the config file lives at:

/mnt/tank/configs/openclaw/config/openclaw.json

NanoGPT as Provider (OpenAI-compatible)

NanoGPT exposes an OpenAI-compatible API at https://nano-gpt.com/api/v1. Configure it as a custom provider:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "nanogpt/claude-sonnet-4.5",
        "fallbacks": ["openrouter/anthropic/claude-sonnet-4.5"]
      }
    }
  },
  "env": {
    "NANO_GPT_API_KEY": "your-nanogpt-key",
    "OPENROUTER_API_KEY": "sk-or-your-openrouter-key"
  }
}

Note: If NanoGPT is not natively supported as a provider, configure it as a custom provider with base URL https://nano-gpt.com/api/v1. Check the custom providers docs for exact syntax.

OpenRouter as Provider (alternative)

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.5"
      }
    }
  },
  "env": {
    "OPENROUTER_API_KEY": "sk-or-your-key"
  }
}

5. Connect Telegram

From SSH on TrueNAS, use the CLI service:

cd /mnt/tank/stacks/openclaw
docker compose run --rm openclaw-cli channels add --channel telegram --token "YOUR_BOT_TOKEN"

Then approve the pairing. Send a message to your bot in Telegram — it will reply with a pairing code. Approve it:

docker compose run --rm openclaw-cli pairing approve telegram <CODE>

6. Verify

• Check gateway status: docker compose run --rm openclaw-cli gateway status
• View logs: docker logs -f openclaw
• Run diagnostics: docker compose run --rm openclaw-cli doctor
• Access Control UI via SSH tunnel:

  ssh -L 18789:localhost:18789 truenas_admin@<truenas-ip>
  

  Then open http://localhost:18789/ (must be localhost — the UI requires HTTPS or localhost)

7. Security Considerations

• Do not expose port 18789 to the public internet. Use Tailscale, WireGuard, or VPN to access the Control UI remotely.
• Enable explicit consent mode to require approval before OpenClaw executes write/exec commands.
• Treat the /mnt/tank/configs/openclaw/config directory as sensitive — it contains API keys and session data.
• The container runs as non-root (uid 1000), which is good practice.
• Consider network isolation: create a dedicated Docker network or VLAN if your TrueNAS hosts other services.

Useful Commands

All CLI commands below assume you are in /mnt/tank/stacks/openclaw.

Command	Description
docker compose run --rm openclaw-cli gateway status	Check if gateway is running
docker compose restart openclaw-gateway	Restart the gateway
docker compose run --rm openclaw-cli doctor	Automated health checks
docker logs -f openclaw	Stream live logs
docker compose run --rm openclaw-cli channels list	List connected channels
docker compose pull && docker compose up -d openclaw-gateway	Update to latest version

Troubleshooting

• Gateway Bridge errors: Common with Docker networking. Ensure the container can reach the internet. Try host network mode if bridge fails:

  network_mode: host
  

• Permission denied on volumes: Verify UID 1000 owns the host directories.
• OAuth/auth issues on headless setup: Copy the redirect URL from the onboarding wizard and paste it back manually.
• Container won't start: Check docker logs openclaw for config validation errors — OpenClaw rejects malformed JSON5.