This page focuses on day-to-day commands, service mode, and troubleshooting.

Who this page is for

• Users running NullClaw day to day from the CLI or service mode
• Operators checking health, restarts, and post-change validation steps
• Troubleshooters narrowing down common startup, model, channel, or gateway issues

Read this next

• Open Commands if you need a fuller CLI reference beyond the common paths here
• Open Security before exposing the gateway or widening allowlists and autonomy
• Open Gateway API if your operational flow depends on pairing or webhook calls

If you came from ...

• Installation: this page picks up after the binary is installed and ready for first-run checks
• Configuration: come here to validate config changes with runtime commands and troubleshooting steps
• Commands: return here when you want the operational sequence, not just the raw command list

1. Initialize:

nullclaw onboard --interactive

2. Send a test message:

nullclaw agent -m "hello nullclaw"

3. Start long-running gateway:

nullclaw gateway

For long-running deployments:

• macOS uses launchctl.
• Linux uses systemd --user when available and falls back to OpenRC or SysVinit when the required runtime is present.
• Windows uses the Service Control Manager.
• If Linux has neither working systemd --user nor the required OpenRC/SysVinit support, service subcommands fail; use foreground nullclaw gateway or another supervisor instead.

nullclaw service install
nullclaw service start
nullclaw service status

After significant config changes, restart service:

nullclaw service stop
nullclaw service start

• Default gateway: 127.0.0.1:3000
• Recommended: keep gateway.require_pairing = true
• For public access, prefer tunnel/reverse proxy over direct public bind
• /pair is POST-only, uses X-Pairing-Code, and can be rate-limited or temporarily locked after repeated invalid attempts

Health check:

curl http://127.0.0.1:3000/health

Steps:

1. Run nullclaw doctor for exact error details.
2. Compare with config.example.json for key names and nesting.
3. Validate JSON syntax (commas, quotes, braces).

Common causes:

• API key invalid/expired.
• Provider mismatch (for example, wrong key for selected provider).
• Invalid model route format/string.

Checks:

nullclaw status

Then re-run onboarding:

nullclaw onboard --interactive

Check:

• channels.<name>.accounts.* token/webhook/account settings.
• Channel-specific allowlist or gating mismatch (allow_from, group_allow_from, require_mention, and similar settings). Empty allow_from is not a universal deny switch.
• nullclaw channel status health output.
• For DingTalk-specific stream and reply-target checks, open DingTalk Ops Readiness.

Common causes:

• Still bound to 127.0.0.1.
• Tunnel/reverse proxy not configured.
• Firewall port not opened.

Common causes:

• Low-quota coding plans may reject tool-heavy agent turns even when plain chat still works.
• Retry pressure is too aggressive for the current provider plan.
• There is no configured fallback when the primary provider hits quota/rate limits.

Checks:

• For foreground runs, start with nullclaw agent --verbose.
• For service mode, inspect ~/.nullclaw/logs/daemon.stdout.log and ~/.nullclaw/logs/daemon.stderr.log.
• Run nullclaw status to confirm the current provider/model pair.

If the plan is valid but fragile, tune reliability conservatively:

{
  "reliability": {
    "provider_retries": 1,
    "provider_backoff_ms": 3000,
    "fallback_providers": ["openrouter"]
  }
}

If you have multiple keys for the same provider, add reliability.api_keys so NullClaw can rotate them.

What this usually means:

• The canonical NullClaw tool name is schedule.
• Some local Ollama-served models emit scheduler_tool or schedule_tool instead.
• Current NullClaw builds normalize those Ollama aliases back to schedule before dispatch.

Checks:

• Confirm you are running a build that includes the Ollama tool-alias normalization fix.
• Re-run with nullclaw agent --verbose if you still see Unknown tool for a scheduler-related name.
• If you are pinned to an older binary, upgrade before changing your scheduler config. The problem is usually tool-name drift, not a disabled scheduler.

After config edits:

nullclaw doctor
nullclaw status
nullclaw channel status
nullclaw agent -m "self-check"

For gateway scenarios:

nullclaw gateway
curl http://127.0.0.1:3000/health

• Open Commands for less common CLI flows and a broader command catalog
• Review Security before moving from local-only operation to wider exposure
• Use Gateway API when your operational checks include pairing or webhook integrations

• Installation
• Configuration
• Commands
• Security