Configuration Overview

Understanding NullClaw’s configuration structure and loading

NullClaw’s configuration system uses a JSON file located at ~/.nullclaw/config.json to control every aspect of the agent runtime.

Configuration Location

The config file is automatically created during onboarding at:

~/.nullclaw/config.json

If the file doesn’t exist, NullClaw will use sensible defaults and create the file when needed.

Configuration Structure

The configuration is organized into logical sections:

• Models: Provider credentials and model selection
• Channels: Communication interfaces (Telegram, Discord, CLI, etc.)
• Memory: Storage backends and vector search
• Security: Sandbox, audit, and resource limits
• Gateway: HTTP webhook server
• Autonomy: Action approval and workspace restrictions
• Agent: Behavior settings like context limits and tool iterations

Full Example Configuration

Here’s a complete example showing all major sections:

{
  "default_temperature": 0.7,

  "models": {
    "providers": {
      "openrouter": {
        "api_key": "YOUR_OPENROUTER_API_KEY"
      }
    }
  },

  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4"
      }
    }
  },

  "channels": {
    "cli": true,
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "YOUR_TELEGRAM_BOT_TOKEN",
          "allow_from": ["YOUR_TELEGRAM_USER_ID"]
        }
      }
    }
  },

  "memory": {
    "profile": "markdown_only",
    "backend": "markdown",
    "auto_save": true,
    "citations": "auto"
  },

  "autonomy": {
    "level": "supervised",
    "workspace_only": true,
    "max_actions_per_hour": 20
  },

  "gateway": {
    "port": 3000,
    "host": "127.0.0.1",
    "require_pairing": true
  },

  "security": {
    "sandbox": {
      "backend": "auto"
    },
    "audit": {
      "enabled": true
    }
  }
}

Configuration Loading Order

NullClaw loads configuration in this order (later sources override earlier ones):

1. Built-in defaults — Hardcoded fallback values in the source code
2. Config file — ~/.nullclaw/config.json if it exists
3. Environment variables — Specific overrides (e.g., NULLCLAW_API_KEY)
4. Profile presets — Memory profile defaults applied after parsing

This means you can:

• Start with an empty config file and add only what you need
• Override specific values without duplicating the entire structure
• Use environment variables for sensitive credentials

Editing the Configuration

To modify your configuration:

1. Open the file:

   nano ~/.nullclaw/config.json
   

2. Make your changes (ensure valid JSON syntax)

3. Restart NullClaw for changes to take effect:

   nullclaw listen
   

NullClaw validates the config at startup. If parsing fails, you’ll see a warning and the agent will fall back to defaults.

Next Steps

Explore detailed configuration for each section:

Model Configuration

Configure AI providers and model selection

Channels

Set up Telegram, Discord, and other messaging platforms

Memory

Choose memory backends and enable vector search

Security

Configure sandboxing and resource limits