OpenClaw Operations & Model Configuration

This doc covers the runtime operations of Claw — how models are selected, how fallback works, what the cron jobs actually do, and how to troubleshoot when things break. For deployment architecture, see the Deployment Guide and vault projects/openclaw/DEPLOYMENT-GUIDE.md.

Config repo: git.Arcturus-Prime.com/Arcturus-Prime/openclaw-config (private) Version: OpenClaw v2026.2.18 Host: Altair-Link (10.42.0.199), port 18789

---

Model Fallback Chain

Claw uses a multi-provider fallback chain. When the primary model rate-limits or errors, OpenClaw automatically tries the next provider in order. All providers are free tier.

Priority	Provider	Model ID	API Type	Limit	Notes
Primary	Groq	groq/meta-llama/llama-4-scout-17b-16e-instruct	OpenAI-compat	30K TPM	Fast (~1s), rate-limits under sustained load
Fallback 1	Cerebras	cerebras/llama-3.3-70b	OpenAI-compat	Free	Fast inference, generous limits
Fallback 2	SambaNova	sambanova/Meta-Llama-3.3-70B-Instruct	OpenAI-compat	Free	Generous limits, reliable
Fallback 3	OpenRouter	openrouter/google/gemini-2.5-flash	OpenAI-compat	varies	Pay-per-use, reliable with tools
Fallback 4	OpenRouter	openrouter/qwen/qwen3-235b-a22b-2507	OpenAI-compat	varies	Good reasoning, large context
Fallback 5	NVIDIA NIM	nvidia-nim/meta/llama-3.3-70b-instruct	OpenAI-compat	12K TPM	Last resort (can’t handle full agent mode)

Note: Native gemini/gemini-2.5-flash was removed from the fallback chain. While it works for direct chat completions, OpenClaw v2026.2.18’s agent failover silently skips it (the gemini/ prefix resolves through the built-in Google SDK path which doesn’t function in agent mode with tool definitions). The provider is still configured for direct API access.

The deep agent overrides the chain with openrouter/anthropic/claude-sonnet-4-5-20250929 for complex reasoning tasks.

How Model Resolution Works

OpenClaw resolves models in this order:

1. Built-in registry — known models shipped with OpenClaw
2. Inline models — models registered in models.providers.*.models[] in config
3. Forward compatibility — pattern matching for newer model IDs
4. Generic provider fallback — if a provider exists in config, try it anyway
5. Error — “Unknown model”

Gemini 2.5 Flash isn’t in v2026.2.18’s built-in registry, so it’s registered as an inline model in the config’s models.providers.gemini section.

Provider Auth: Two Systems

Providers need auth configured in two places:

1. Environment variables — GROQ_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, NVIDIA_NIM_API_KEY in the .env file
2. Auth profiles — per-agent API key store at config/agents/main/agent/auth-profiles.json

The profile name must match the provider name in config. If you define a provider called gemini in models.providers, you need a gemini entry in auth-profiles (not google).

Gemini Configuration Details

The native Gemini provider requires three things in openclaw.json:

"models": {
  "providers": {
    "gemini": {
      "api": "google-generative-ai",
      "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
      "models": [{
        "id": "gemini-2.5-flash",
        "name": "Gemini 2.5 Flash",
        "reasoning": true,
        "input": ["text", "image"],
        "contextWindow": 1048576,
        "maxTokens": 65536,
        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
      }]
    }
  }
}

Key points:

• api: "google-generative-ai" = native Google SDK (not OpenAI-compat)
• baseUrl is required by the config schema even though the SDK has a default
• The gemini/ prefix in model IDs auto-maps to the google-generative-ai API type via OpenClaw’s resolveOpencodeZenModelApi()

---

Cron Jobs (11 Active)

All times are Mountain Time (America/Denver). Configured in config/cron/jobs.json.

Daily Jobs

Time	Job ID	Description
00:30	cron-memory-consolidation	Cleans stale memory entries, dedupes, checks for expired reminders
02:00	cron-dev-pipeline	Checks Gitea for open PRs/issues, repo status, build health
06:30	cron-competitive-monitor	Scans for hardware deals, software updates, pricing changes
08:00	cron-morning-briefing	Full report: infrastructure health, news, weather, tasks
10:30	cron-content-scout	Trending topics from Reddit, HN, tech blogs for blog content
23:00	cron-security-audit	Checks exposed services, SSL certs, failed SSH, error spikes

Recurring Jobs

Interval	Job ID	Description
Every 2h	cron-watchdog	Provider availability, cron health, memory integrity, workspace check
Every 6h	cron-infra-health	Containers, disk, memory — auto-restarts unhealthy, prunes if full
Every 8h	cron-build-swarm	Drone status, build queue, failure tracking

Weekly Jobs

Schedule	Job ID	Description
Sunday 09:00	cron-weekly-report	Full infrastructure/content/security/dev summary
Wednesday 10:00	cron-voice-connectivity	Verifies all integrations (Twilio, Gitea, APIs, Tailscale)

Cron Job Structure

Each job uses payload.kind: "agentTurn" (not "systemEvent") to trigger a full agent turn:

{
  "id": "cron-infra-health",
  "enabled": true,
  "schedule": { "kind": "every", "interval": "6h" },
  "payload": {
    "text": "HEALTH CHECK — run checks, auto-fix, report...",
    "kind": "agentTurn"
  },
  "delivery": { "mode": "announce" }
}

---

Heartbeat System

Heartbeats run every 3 hours during active hours (08:00–22:00 MT). They’re separate from cron — heartbeats are built into the gateway and check infrastructure silently.

Auto-Remediation Rules

Condition	Action	Escalate?
Container unhealthy	docker restart <name>	Only if restart fails
Disk >85%	docker system prune -f	If still >85% after prune
Container restart loop (>3 in 10min)	docker stop <name>, report	Always
Service port not listening	Restart container	If public-facing
Build drone grounded	Report only	Always
Memory <500MB	Report only	Always
SSL cert <7 days	Report	Critical

Response Protocol

• Everything healthy → HEARTBEAT_OK (silent)
• Auto-fixed something → brief report
• Needs human attention → alert with severity level

Voice Escalation (Critical Only)

1. Report in webchat first
2. If no response in 15 minutes during waking hours (7AM–11PM MT) → phone call via Twilio
3. Never call for WARNING/INFO
4. Never call between 11PM–7AM unless total outage

---

Skills

Skills are Markdown files in workspace/skills/ that teach Claw how to use specific APIs and services.

Skill	Directory	Purpose
email	skills/email/	Read, send, search email via Arcturus-Prime admin API
rag	skills/rag/	Search 166K+ knowledge chunks (local BM25 + Colorado Legal + Arcturus-Prime API)
calendar	skills/calendar/	Google Calendar events (pending OAuth setup)
workbench	skills/workbench/	Dispatch coding tasks to AI Workbench (Claude Code, Codex, etc.)
applyr	skills/applyr/	Job search automation — discover, apply, track, follow up
cloudflare	skills/cloudflare/	DNS, cache, analytics, CF Pages deploy monitoring
network	skills/network/	Network discovery and device inventory

---

Bootstrap Files

Workspace .md files are injected into Claw’s system prompt at startup. Max 20K chars/file, 150K total.

File	Purpose
AGENTS.md / CLAUDE.md	Capabilities, cron schedule, code conventions, voice guide
SOUL.md	Personality, security boundaries, prompt injection defense
TOOLS.md	Infrastructure reference, API endpoints, network topology
USER.md	About daniel (preferences, background, communication style)
IDENTITY.md	Claw’s name, role, deployment info
CODEBASE.md	Arcturus-Prime website structure and patterns
HEARTBEAT.md	Health check procedures and auto-remediation rules

CLAUDE.md is a symlink to AGENTS.md (OpenClaw reads it as the primary bootstrap file).

---

Troubleshooting

”Unknown model: gemini/gemini-2.5-flash”

Model isn’t in the built-in catalog (v2026.2.18). Register it in models.providers.gemini.models[] in openclaw.json.

”No API key found for provider ‘gemini’”

Add a gemini profile to auth-profiles.json. The profile name must match the provider name.

”baseUrl: Invalid input: expected string, received undefined”

Add "baseUrl": "https://generativelanguage.googleapis.com/v1beta" to the gemini provider config.

Groq rate limiting frequently

Normal — 30K TPM free tier means a full agent conversation (13K+ token system prompt + tools + messages) can exhaust the limit in 1-2 turns. The fallback chain handles this automatically. If you need more, upgrade to Groq’s paid tier.

Provider works via curl but fails through agent

The full agent request includes tools, system prompt, and history (~13K+ tokens). Some free tier limits can’t handle the payload. NVIDIA NIM’s llama-3.3-70b (12K TPM) physically cannot fit the system prompt.

Config validation error on startup

Gateway logs Config invalid but continues with “best-effort config.” Fix the error in openclaw.json, push, restart: docker compose restart openclaw-gateway. Check logs with docker compose logs --tail=20 openclaw-gateway.

Checking which provider actually handled a request

Read the JSON logs inside the container:

docker exec openclaw-openclaw-gateway-1 tail -50 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

Look for embedded run start: entries — they show provider= and model=. Look for isError=true/false in embedded run agent end: entries to see if it succeeded.

Testing providers directly

# Test specific provider via chat completions API
curl -s -X POST http://localhost:18789/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $GATEWAY_TOKEN' \
  -d '{"model": "gemini/gemini-2.5-flash", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 50}' | jq

Replace gemini/gemini-2.5-flash with any provider/model in the chain to test individually.

---

Channels

Telegram (@argobox_oc_bot)

Claw is accessible via Telegram DM through the @argobox_oc_bot bot. This enables mobile interaction — send commands, get alerts, and chat with Claw from anywhere.

Configuration in openclaw.json:

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "TELEGRAM_BOT_TOKEN",
    "dmPolicy": "pairing",
    "reactionLevel": "minimal",
    "groups": {
      "*": { "requireMention": true }
    }
  }
}

Key settings:

Setting	Value	Description
dmPolicy	pairing	First DM pairs that Telegram user as owner
reactionLevel	minimal	Light emoji reactions on messages
groups.*.requireMention	true	Must @mention bot in group chats

Pairing: The first user to DM the bot gets paired as the owner. To approve additional users, run inside the container:

npx openclaw pairing approve telegram <PAIRING_CODE>

Paired user ID: 7892071384

Web UI

The primary interface at https://oc.Arcturus-Prime.com and embedded in Arcturus-Prime admin at /admin/openclaw.

Voice (Twilio)

Phone call interface via Twilio. See the voice-call plugin config for details.

---

Integrations

Service	Purpose	Auth	Status
Groq	Primary LLM	GROQ_API_KEY	Active
Cerebras	Fallback 1 LLM	CEREBRAS_API_KEY + auth-profile	Active
SambaNova	Fallback 2 LLM	SAMBANOVA_API_KEY + auth-profile	Active
Google Gemini	Direct API LLM	GEMINI_API_KEY + auth-profile	Active
OpenRouter	Fallback router	OPENROUTER_API_KEY + auth-profile	Active
NVIDIA NIM	Last-resort LLM	NVIDIA_NIM_API_KEY + auth-profile	Active
Gitea	Git operations	OPENCLAW_GITEA_TOKEN	Active
Telegram	Mobile chat	channels.telegram.botToken	Active
Twilio	Voice calls	Plugin config + env	Active
ElevenLabs	TTS	ELEVENLABS_API_KEY	Active
Brave Search	Web search	BRAVE_API_KEY	Active
Perplexity	Deep research	PERPLEXITY_API_KEY	Active
Docker	Container management	Socket mount + group 999	Active
Cloudflare	DNS, cache, analytics	CF_API_TOKEN	Active
Pentest Daemon	Security scanning	PENTEST_API_KEY	Active
Resend	Email notifications	RESEND_API_KEY	Active
Build Swarm	Distributed builds	SWARM_ADMIN_KEY	Active
Meridian-Host Admin	NAS management	MM_ARGOBOX_TOKEN	Active
Applyr	Job monitoring	AUTOAPPLY_API_KEY	Active

Docker Access

Claw has read-only Docker socket access for container health checks, restarts, pruning, and deployment. Configured via docker-compose.override.yml:

• /var/run/docker.sock mounted read-only
• /usr/bin/docker CLI binary bind-mounted from host
• group_add: ["999"] — Docker group GID on Altair-Link

This enables the heartbeat system’s auto-remediation (restart unhealthy containers, prune disk when >85%) and the infrastructure health cron job.

---

Related Docs

• OpenClaw Gateway — architecture, admin pages, skills system
• OpenClaw Admin Pages — config, cron, and skills UI reference
• Email System — CF Email Routing + Resend inbound/outbound email
• Vault: projects/openclaw/DEPLOYMENT-REFERENCE.md — full deployment walkthrough
• Vault: projects/openclaw/VISION-AND-ROADMAP.md — phased rollout plan
• Vault: projects/openclaw/SECURITY-MODEL.md — auth, sandboxing, audit logging
• Vault: ~/Vaults/Arcturus-Prime/projects/openclaw/STATUS.md — comprehensive project status
• Config repo: git.Arcturus-Prime.com/Arcturus-Prime/openclaw-config