Repository navigation
OpenClaw On Truenas Scale Complete Setup Guide
Self-hosted AI agent framework with multi-provider LLM routing, homelab integration, and cybersecurity workflows
Part of the ULTIMATE CYBERSECURITY MASTER GUIDE
Version context: This is a tested deployment snapshot using OpenClaw 2026.4.15 and TrueNAS SCALE 25.04, not a current-version recommendation. Provider names, model IDs, app menus, and commands can change. Check current OpenClaw releases and vendor documentation before applying the steps.
Complete installation and configuration guide for deploying OpenClaw (a self-hosted, multi-provider AI agent framework) on TrueNAS SCALE, including known TrueNAS-Community-app-specific bugs and their workarounds. First of three companion OpenClaw guides - see use_cases.md for prompt examples and agent_skill_config.md for ready-to-apply agent personas once this install is complete.
Eight parts covering app-catalog installation, the provider onboarding wizard (Anthropic/Gemini/Groq/Ollama), manual config fixes for wizard bugs (Groq model registration, Ollama API key), security hardening, NPMplus HTTPS reverse-proxy setup with local DNS override, and device pairing - followed by a troubleshooting section documenting specific failure modes and their exact fixes.
Get OpenClaw running on TrueNAS SCALE with all four LLM providers verified working, HTTPS access configured via NPMplus, and a paired device connected to the dashboard.
- First-time OpenClaw deployment on TrueNAS SCALE
- Diagnosing a specific OpenClaw/TrueNAS app failure (config service exit 1, WebSocket disconnects, provider not showing in
models list) - check Troubleshooting first
OpenClaw is a free, open-source AI agent framework that runs on your own hardware. Think of it as a personal AI assistant - like having a local version of ChatGPT that you control completely, connected to your messaging apps, files, and services.
What it can do:
- Chat via Telegram, Discord, WhatsApp, Slack, Signal, and 50+ other platforms from a single agent
- Read and write files, run shell commands, browse the web, and manage your calendar
- Connect to multiple AI providers simultaneously (Anthropic, Google, Groq, local Ollama models) and route tasks to the best/cheapest model automatically
- Remember context across sessions and schedule automated tasks with cron jobs
- Extend functionality with community-built skills (ClawHub) for homelab management, GitHub, Notion, media servers, and more
- Run 100% locally with Ollama - no data leaves your network
Why self-host it?
- Your conversations stay on your hardware
- Use free tiers of Groq and Gemini for most tasks, reserving paid APIs (like Claude) for complex work
- Integrate with your existing homelab infrastructure
- Full control over models, tools, and data
This repository includes three guides. Start here, then refer to the others once setup is complete:
| File | Description |
|---|---|
| README.md (this file) | Full installation and configuration guide for TrueNAS SCALE |
| use_cases.md | Real-world example prompts organized by workflow - personal, IT support, blue team, red team, purple team, OSINT, and more |
| agent_skill_config.md | Pre-built agent personas, skill configurations, cron jobs, and automation setups ready to apply to your instance |
- Prerequisites
- Part 1: Install OpenClaw from App Catalog
- Part 2: Run the Setup Wizard
- Part 3: Configure AI Providers
- Part 4: Verify All Providers
- Part 5: Set Default Model and Tools Profile
- Part 6: Security Hardening
- Part 7: NPMplus Reverse Proxy with HTTPS
- Part 8: Device Pairing
- Local Access Without HTTPS
- Troubleshooting
- Reference: Key Commands
- TrueNAS SCALE 25.04+
- NPMplus installed and running (for HTTPS reverse proxy)
- OPNsense or similar router
- A DuckDNS (or other DDNS) domain pointed at your public IP
- Ollama running somewhere on your network (optional, for local inference)
- API keys for: Anthropic, Groq, Google Gemini (all have free tiers)
Go to Apps โ Discover in the TrueNAS UI and search for OpenClaw (Community train).
Before installing, generate a strong random token:
openssl rand -hex 32Save this token - you'll need it throughout setup and to connect to the dashboard.
Fill in the app installer form as follows:
OpenClaw Configuration:
| Field | Value |
|---|---|
| Authentication Mode | Shared bearer token (recommended) |
| Gateway Token | (your generated token) |
| Proxy Trusted Proxies | Your TrueNAS/NPMplus IP (e.g. 10.0.1.149) |
Network Configuration:
| Field | Value |
|---|---|
| Port Bind Mode | Publish port on the host for access through a trusted LAN or HTTPS reverse proxy only; do not forward this port directly to the public internet |
| Port Number | 30262 |
| Host Network | Unchecked |
User and Group Configuration:
| Field | Value |
|---|---|
| User ID | 568 |
| Group ID | 568 |
Storage Configuration:
โ ๏ธ CRITICAL: Leave storage type asixVolume- do NOT change to Host Path.There is a known bug in OpenClaw 2026.3.2+ where the config init container fails when using Host Path storage. The ixVolume option (TrueNAS managed storage) is the only storage type that works reliably with the TrueNAS Community app.
Resources Configuration:
| Field | Value |
|---|---|
| CPUs | 4 |
| Memory (MB) | 6144 |
In the Additional Environment Variables section, add all provider API keys before installing:
| Name | Value |
|---|---|
ANTHROPIC_API_KEY |
sk-ant-... |
GROQ_API_KEY |
gsk_... |
GEMINI_API_KEY |
AIza... |
OLLAMA_API_KEY |
ollama-local |
OLLAMA_BASE_URL |
http://YOUR_OLLAMA_IP:11434 |
Note: Use
OLLAMA_BASE_URL- notOLLAMA_HOST. TheOLLAMA_HOSTvariable is ignored by this version of OpenClaw.
Click Install and wait for the app to show as Running (green) in Apps โ Installed.
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs onboard --auth-choice anthropicAt each prompt:
- Security disclaimer โ Yes
- Setup mode โ QuickStart
- Config handling โ Use existing values
- Channel setup โ Skip for now
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs onboard --auth-choice googleAt each prompt:
- Security disclaimer โ Yes
- Setup mode โ QuickStart
- Config handling โ Use existing values
- Use existing
GEMINI_API_KEYโ Yes - Web search provider โ Gemini (Google Search)
- Channel setup โ Skip for now
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs onboard --auth-choice groqAt each prompt:
- Security disclaimer โ Yes
- Setup mode โ QuickStart
- Config handling โ Use existing values
- Channel setup โ Skip for now
Note: The Groq wizard often completes without actually registering Groq models. If
models listdoesn't show Groq afterward, the manual fix in Part 3 is required.
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs onboard --auth-choice ollamaAt each prompt:
- Security disclaimer โ Yes
- Setup mode โ QuickStart
- Config handling โ Use existing values
- Ollama mode โ Local only
- Ollama base URL โ
http://YOUR_OLLAMA_IP:11434(no/v1suffix) - Select a model from the discovered list
- Channel setup โ Skip for now
The Groq wizard often completes without registering models. Fix this by editing the config file directly on the TrueNAS host:
sudo python3 -c "
import json
path = '/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json'
with open(path) as f:
config = json.load(f)
config['auth']['profiles']['groq:default'] = {'provider': 'groq', 'mode': 'api_key'}
config['plugins']['entries']['groq'] = {'enabled': True}
config['agents']['defaults']['models']['groq/llama-3.3-70b-versatile'] = {}
with open(path, 'w') as f:
json.dump(config, f, indent=2)
print('Done')
"Validate the JSON:
sudo python3 -c "import json; json.load(open('/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json')); print('Valid')"
โ ๏ธ Important: Never useconfig setto add nested provider objects likemodels.providers.groq. OpenClaw's schema validator rejects partial provider entries written one field at a time. Always use the Python direct-edit method above for provider configuration.
The Ollama wizard sets the API key to the literal string "OLLAMA_API_KEY" instead of resolving the value. Fix it:
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set models.providers.ollama.apiKey "ollama-local"Check what models you have available:
curl -s http://YOUR_OLLAMA_IP:11434/api/tagsThen add your models to the agents allowlist:
sudo python3 -c "
import json
path = '/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json'
with open(path) as f:
config = json.load(f)
# Replace with your actual model name from the api/tags output
config['agents']['defaults']['models']['ollama/YOUR_MODEL_NAME:latest'] = {}
with open(path, 'w') as f:
json.dump(config, f, indent=2)
print('Done')
"Restart the app from the TrueNAS UI (Stop โ Start), then verify:
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs models listExpected output:
Model Input Ctx Local Auth Tags
google/gemini-3.1-pro-preview text+image 1024k no yes default,configured
anthropic/claude-opus-4-7 text+image 977k no yes configured
anthropic/claude-haiku-4-5 text+image 195k no yes configured
ollama/YOUR_MODEL:latest text 8k no yes configured
groq/llama-3.3-70b-versatile text 128k no yes configured
All four providers should be listed. If any are missing, revisit the relevant section in Part 3.
Set Groq as the default model to minimize API costs:
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set agents.defaults.model.primary "groq/llama-3.3-70b-versatile"Set the tools profile. Valid values are minimal, coding, messaging, or full:
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set tools.profile minimal
# Keep the minimal profile unless a specific task requires additional tools; enable only the narrow capabilities needed.Run the built-in security audit:
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs security auditFix the flagged issues:
# Add rate limiting against brute force attacks
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set gateway.auth.rateLimit '{"maxAttempts":10,"windowMs":60000,"lockoutMs":300000}'
# Lock down allowed origins to your HTTPS domain and local IP
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set gateway.controlUi.allowedOrigins '["https://openclaw.yourdomain.duckdns.org"]'Restart the app from the TrueNAS UI to apply changes.
In the NPMplus UI go to Hosts โ Proxy Hosts โ Add Proxy Host.
Details tab:
| Field | Value |
|---|---|
| Domain Name | openclaw.yourdomain.duckdns.org |
| Scheme | http |
| Forward Hostname/IP | Your TrueNAS IP |
| Forward Port | 30262 |
Keep this backend port blocked from direct public internet access; allow access only from the trusted reverse proxy or an explicitly trusted LAN.
Click the gear icon โ๏ธ next to Forward Port and paste this into the advanced config box:
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
more_clear_headers Alt-Svc;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_connect_timeout 60s;
โ ๏ธ Theproxy_http_version 1.1line is critical. WebSockets require HTTP/1.1 and will fail silently with HTTP/2 or HTTP/3.
TLS tab:
| Field | Value |
|---|---|
| TLS Certificate | Request a new Certificate |
| Force HTTPS | โ Enabled |
| HTTP/2 Support | โ Disabled |
| HTTP/3 Support | โ Disabled |
| Use DNS Challenge | โ Enabled (required for DuckDNS) |
Enable Use DNS Challenge and enter your DuckDNS token from https://www.duckdns.org.
To access the HTTPS domain locally without hairpin NAT issues, add a host override in OPNsense:
Go to Services โ Unbound DNS โ Host Overrides โ + and add:
| Field | Value |
|---|---|
| Host | openclaw |
| Domain | yourdomain.duckdns.org |
| Type | A (IPv4 address) |
| IP address | Your TrueNAS IP (e.g. 10.0.1.149) |
Save and apply Unbound. Verify:
nslookup openclaw.yourdomain.duckdns.org YOUR_OPNSENSE_IPShould return your TrueNAS LAN IP, not your public WAN IP. Add overrides for all your other NPMplus proxy hosts using the same pattern.
Forward external ports 80 and 443 from your router WAN to NPMplus on your TrueNAS. Confirm NPMplus port mappings:
sudo docker ps | grep npmplusOpen https://openclaw.yourdomain.duckdns.org in your browser.
On the Gateway Dashboard enter:
-
WebSocket URL:
wss://openclaw.yourdomain.duckdns.org - Gateway Token: (your token from Part 1)
Click Connect. The dashboard will show "pairing required".
# List pending pairing requests
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs devices list
# Approve using the Request UUID from the output
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs devices approve YOUR-REQUEST-UUIDYou are now connected to the OpenClaw dashboard.
Keep the dashboard bound to loopback or a trusted LAN while configuring HTTPS. Do not enable Chromeโs insecure-origin override or place the gateway token in an HTTP URL. Use the HTTPS reverse proxy after certificate and origin checks are configured; if HTTPS is unavailable, access only through a trusted local tunnel and keep the token in the appโs supported secure configuration.
This is a known bug in OpenClaw 2026.3.2+ triggered by Host Path storage.
Fix: Delete the app and reinstall using ixVolume storage (the default). Do not change the storage type to Host Path.
The config file has invalid JSON or failed schema validation.
Fix: Restore from the automatic backup OpenClaw creates before every edit:
# Find the config file
sudo find /mnt/.ix-apps -name "openclaw.json" 2>/dev/null
# Restore from backup
sudo cp /mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json.bak \
/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json
# Validate
sudo python3 -c "import json; json.load(open('/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json')); print('Valid')"Then start the app from the TrueNAS UI.
OpenClaw requires all fields of a provider entry to be present simultaneously. Setting nested provider objects one field at a time always fails validation.
Fix: Use the Python direct-edit method from Part 3.
The OLLAMA_HOST environment variable is not supported by this version.
Fix: In the TrueNAS app environment variables, use OLLAMA_BASE_URL instead of OLLAMA_HOST.
HTTP/2 or HTTP/3 is being negotiated, which breaks WebSocket upgrades.
Fix: Ensure proxy_http_version 1.1 is in the NPMplus advanced config, and that HTTP/2 and HTTP/3 are disabled in the TLS tab. Also ensure your Unbound DNS override is resolving the domain to your local TrueNAS IP - if the domain resolves to your WAN IP, traffic hairpins through NAT and the connection fails.
Port 80 is not accessible from the internet for the HTTP-01 ACME challenge.
Fix: Use the DNS Challenge option in NPMplus TLS settings with your DuckDNS token.
The gateway process isn't running inside the container.
Fix:
sudo docker exec -d ix-openclaw-openclaw-1 node /app/openclaw.mjs gateway runWait a few seconds then retry devices list.
# Check running containers
sudo docker ps | grep openclaw
# View all configured models
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs models list
# Get a config value
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config get gateway.port
# Set a simple config value
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set KEY VALUE
# Run security audit
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs security audit
# List paired devices
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs devices list
# Approve a device pairing
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs devices approve UUID
# View raw config file
sudo cat /mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json
# Validate config JSON
sudo python3 -c "import json; json.load(open('/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json')); print('Valid')"
# Restore config from backup
sudo cp /mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json.bak \
/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json
# View app lifecycle logs
sudo grep openclaw /var/log/app_lifecycle.log | tail -n 20
# Check environment variables in container
sudo docker exec -it ix-openclaw-openclaw-1 env | grep -E "GROQ|GEMINI|OLLAMA|ANTHROPIC"
# View container logs
sudo docker logs ix-openclaw-openclaw-1 2>&1 | tail -n 30| Provider | Cost | Best For |
|---|---|---|
| Groq | Free tier (generous) | Default for most tasks - fast Llama 3.3 70B |
| Google Gemini | Free tier | Long context tasks (1M token window) |
| Ollama (local) | Free forever | Sensitive tasks, offline use |
| Anthropic (Claude) | Paid | Complex reasoning, long documents |
The Adaptive model mode in the dashboard automatically routes to a stronger model only when the task requires it, keeping costs minimal.
After basic installation, treat this Gateway as a tool-using production application, not only a chat interface. Use these independent procedures before connecting sensitive accounts or enabling automatic actions:
| Next Capability | Practical Guide | Gate Before Enabling |
|---|---|---|
| Durable notes and session recovery | Context Engineering ยท Notes & Hooks | Approved project records load correctly; stale context is detected |
| Tool/MCP integrations | MCP & Permissions | Server identity, scopes, tenant ACLs and denied-call tests |
| Agent workflows | Orchestration ยท Reliability | One owner for each write, idempotency, bounded retries and rollback |
| Model/provider routing | Model Routing & Cost | Privacy-compliant fallback and measured quality/cost |
| Alert or ticket automation | Security Operations | Synthetic events, authenticated ingress and human review |
| Security hardening | Agent Threat Model | Least privilege, secrets isolation and prompt-injection tests |
| Operations & evaluation | Observability ยท Evaluations | Sanitized traces, real test results, release approval |
The OpenClaw guides contain historical, environment-specific commands. Inspect your installed version and official CLI/configuration schema before applying them; a successful JSON parse alone cannot prove a configuration is supported. Neither OpenClaw nor a local Ollama backend automatically ensures that every tool, logger or fallback is offline.
-
Set up Telegram for mobile access from anywhere:
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs onboard --auth-choice telegram - Install the TrueNAS skill from ClawHub to manage your homelab via OpenClaw
- Rotate your API keys - Groq and Gemini keys were visible in shell history during initial setup
-
Run periodic health checks:
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs security audit
Tested deployment snapshot: TrueNAS SCALE 25.04 ยท Dell R630 ยท OPNsense ยท NPMplus ยท Ollama ยท OpenClaw 2026.4.15
- ../README.md - AI section index
- use_cases.md - 50+ ready-to-use OpenClaw prompts for security workflows
- agent_skill_config.md - Pre-built agent personas and skill configs
- ../offline-llm.md - Setting up the Ollama backend that OpenClaw routes to
- ../../Homelab/HomeLab_Setup.md - TrueNAS SCALE homelab context where OpenClaw runs
๐ Source: AI/OpenClaw/README.md | โ๏ธ Suggest an edit | โฌ
๏ธ Back to Artificial Intelligence
- ๐บ๏ธ Browse by Topic
- ๐ All Repository Files
- ๐งญ Learning Paths
- ๐ Master Guide
- ๐ค Glossary
- โ๏ธ Legal & Disclaimer
๐ Foundations & Learning
๐ก๏ธ Defense & Investigations
- Incident Response
- Open Source Intelligence (OSINT)
- Reverse Engineering
- Operations Security (OPSEC)
- Compliance
โ๏ธ Platforms & Infrastructure
๐ก Hardware, Wireless & Field Projects
- PNWC Cyberdeck
- Hardware Testing
- Hardware Hacking
- Software-Defined Radio
- Wardriving
- uConsole
- Space Security
๐งฐ Assessment & Field Reference
๐ฆ Downloads & Project Resources
๐๏ธ Additional Topics