> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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:
   ```bash theme={null}
   nano ~/.nullclaw/config.json
   ```

2. Make your changes (ensure valid JSON syntax)

3. Restart NullClaw for changes to take effect:
   ```bash theme={null}
   nullclaw listen
   ```

<Note>
  NullClaw validates the config at startup. If parsing fails, you'll see a warning and the agent will fall back to defaults.
</Note>

## Next Steps

Explore detailed configuration for each section:

<CardGroup cols={2}>
  <Card title="Model Configuration" icon="brain" href="/configuration/models">
    Configure AI providers and model selection
  </Card>

  <Card title="Channels" icon="message" href="/configuration/channels">
    Set up Telegram, Discord, and other messaging platforms
  </Card>

  <Card title="Memory" icon="database" href="/configuration/memory">
    Choose memory backends and enable vector search
  </Card>

  <Card title="Security" icon="shield" href="/configuration/security">
    Configure sandboxing and resource limits
  </Card>
</CardGroup>