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

# Configuration Reference

> Complete reference for argent.json — all configuration sections, fields, defaults, and environment variable overrides.

## Overview

ArgentOS is configured through `~/.argentos/argent.json`. This file controls agent behavior, model routing, channel integrations, gateway settings, storage backends, and more.

The configuration is validated against a Zod schema on load. Invalid fields produce clear error messages with paths to the problematic values.

## Configuration File Location

Primary: `~/.argentos/argent.json`

<Note>
  The state directory (`~/.argentos/`) can be overridden with the `ARGENT_STATE_DIR` environment variable. The config file is a symlink target — on systems migrating from OpenClaw, it may symlink to `~/.openclaw/openclaw.json`.
</Note>

## Top-Level Sections

```json theme={null}
{
  "meta": {},
  "env": {},
  "wizard": {},
  "diagnostics": {},
  "logging": {},
  "update": {},
  "browser": {},
  "ui": {},
  "distribution": {},
  "auth": {},
  "models": {},
  "agents": {},
  "tools": {},
  "bindings": {},
  "broadcast": {},
  "audio": {},
  "media": {},
  "messages": {},
  "commands": {},
  "approvals": {},
  "session": {},
  "cron": {},
  "hooks": {},
  "intent": {},
  "web": {},
  "channels": {},
  "discovery": {},
  "canvasHost": {},
  "talk": {},
  "gateway": {},
  "memory": {},
  "nodeHost": {}
}
```

## agents Section

The `agents` section contains agent-level defaults and per-agent overrides:

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-20250514",
        "fallbacks": ["minimax/MiniMax-M2.5"]
      },
      "workspace": "~/argent",
      "thinkingDefault": "low",
      "timeoutSeconds": 300,
      "maxConcurrent": 1,
      "heartbeat": {
        "every": "30m",
        "model": "anthropic/claude-haiku-3-5",
        "activeHours": {
          "start": "07:00",
          "end": "22:00",
          "timezone": "user"
        }
      },
      "contemplation": {
        "enabled": true,
        "every": "30m",
        "maxCyclesPerHour": 12,
        "model": "ollama/qwen3:1.7b"
      },
      "executionWorker": {
        "enabled": true,
        "every": "20m",
        "maxRunMinutes": 12,
        "maxTasksPerCycle": 24,
        "requireEvidence": true,
        "maxNoProgressAttempts": 2
      },
      "modelRouter": {
        "enabled": true,
        "tiers": {
          "local": { "model": "ollama/qwen3:1.7b" },
          "fast": { "model": "anthropic/claude-haiku-3-5" },
          "balanced": { "model": "anthropic/claude-sonnet-4-20250514" },
          "powerful": { "model": "anthropic/claude-opus-4-20250514" }
        }
      },
      "kernel": {
        "enabled": false,
        "mode": "off",
        "localModel": "qwen3:1.7b",
        "tickMs": 30000
      }
    }
  }
}
```

### Key Agent Fields

| Field             | Type       | Default               | Description                                                    |
| ----------------- | ---------- | --------------------- | -------------------------------------------------------------- |
| `model.primary`   | `string`   | —                     | Primary model (provider/model format)                          |
| `model.fallbacks` | `string[]` | `[]`                  | Fallback models tried in order                                 |
| `workspace`       | `string`   | `~/.argent/workspace` | Agent working directory                                        |
| `thinkingDefault` | `string`   | `"off"`               | Default thinking level: off, minimal, low, medium, high, xhigh |
| `timeoutSeconds`  | `number`   | `300`                 | Max seconds per agent turn                                     |
| `maxConcurrent`   | `number`   | `1`                   | Max concurrent agent runs                                      |
| `mediaMaxMb`      | `number`   | —                     | Max inbound media size in MB                                   |
| `userTimezone`    | `string`   | host TZ               | IANA timezone for the user                                     |
| `timeFormat`      | `string`   | `"auto"`              | Time format: auto, 12, 24                                      |
| `skipBootstrap`   | `boolean`  | `false`               | Skip workspace bootstrap                                       |

### Heartbeat Configuration

| Field               | Type     | Default | Description                                |
| ------------------- | -------- | ------- | ------------------------------------------ |
| `every`             | `string` | `"30m"` | Heartbeat interval (duration string)       |
| `model`             | `string` | —       | Model override for heartbeat runs          |
| `activeHours.start` | `string` | —       | Start time (HH:MM, 24h)                    |
| `activeHours.end`   | `string` | —       | End time (HH:MM, 24h)                      |
| `target`            | `string` | —       | Delivery target: last, none, or channel ID |
| `to`                | `string` | —       | Delivery address (phone, chat ID)          |

### Contemplation Configuration

| Field              | Type      | Default | Description                      |
| ------------------ | --------- | ------- | -------------------------------- |
| `enabled`          | `boolean` | `true`  | Enable contemplation cycles      |
| `every`            | `string`  | `"30m"` | Interval between cycles          |
| `familyEvery`      | `string`  | `"24h"` | Interval for family agents       |
| `maxCyclesPerHour` | `number`  | `12`    | Rate limit                       |
| `model`            | `string`  | —       | Model override (typically local) |

### Execution Worker Configuration

| Field                   | Type      | Default | Description                   |
| ----------------------- | --------- | ------- | ----------------------------- |
| `enabled`               | `boolean` | `false` | Enable task execution loop    |
| `every`                 | `string`  | `"20m"` | Cycle interval                |
| `maxRunMinutes`         | `number`  | `12`    | Max minutes per cycle         |
| `maxTasksPerCycle`      | `number`  | `24`    | Safety cap on tasks           |
| `requireEvidence`       | `boolean` | `true`  | Require concrete evidence     |
| `maxNoProgressAttempts` | `number`  | `2`     | Attempts before auto-blocking |

### Kernel Configuration

| Field        | Type      | Default        | Description                      |
| ------------ | --------- | -------------- | -------------------------------- |
| `enabled`    | `boolean` | `false`        | Enable consciousness kernel      |
| `mode`       | `string`  | `"off"`        | Mode: off, shadow, soft, full    |
| `localModel` | `string`  | `"qwen3:1.7b"` | Local model for kernel reasoning |
| `tickMs`     | `number`  | `30000`        | Minimum tick interval            |

## models Section

Provider and model configuration:

```json theme={null}
{
  "models": {
    "providers": {
      "anthropic": { "apiKey": "env:ANTHROPIC_API_KEY" },
      "openai": { "apiKey": "env:OPENAI_API_KEY" }
    }
  }
}
```

## auth Section

Authentication profiles for multi-provider failover:

```json theme={null}
{
  "auth": {
    "profiles": {
      "anthropic:main": {
        "provider": "anthropic",
        "mode": "api_key",
        "email": "user@example.com"
      }
    },
    "order": {
      "anthropic": ["anthropic:main", "anthropic:backup"]
    },
    "cooldowns": {
      "billingBackoffHours": 1,
      "failureWindowHours": 0.5
    }
  }
}
```

## channels Section

Channel integrations (Telegram, Discord, Slack, WhatsApp, etc.):

```json theme={null}
{
  "channels": {
    "telegram": {
      "botToken": "123456:ABC...",
      "enabled": true
    },
    "discord": {
      "botToken": "MTE...",
      "enabled": true
    },
    "slack": {
      "accounts": {
        "default": {
          "botToken": "xoxb-...",
          "appToken": "xapp-..."
        }
      }
    },
    "whatsapp": {
      "enabled": true
    }
  }
}
```

Each channel has its own configuration schema. See the channel-specific documentation for details.

## gateway Section

Gateway server configuration:

```json theme={null}
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "127.0.0.1",
    "token": "auto-generated",
    "cors": {
      "origins": ["http://localhost:5173"]
    }
  }
}
```

| Field   | Type     | Default       | Description           |
| ------- | -------- | ------------- | --------------------- |
| `port`  | `number` | `18789`       | WebSocket server port |
| `mode`  | `string` | `"local"`     | `local` or `remote`   |
| `bind`  | `string` | `"127.0.0.1"` | Bind address          |
| `token` | `string` | auto          | Authentication token  |

## session Section

Session management configuration:

```json theme={null}
{
  "session": {
    "dmScope": "main",
    "store": "~/.argentos/sessions"
  }
}
```

## cron Section

Cron service configuration:

```json theme={null}
{
  "cron": {
    "enabled": true,
    "store": "~/.argentos/cron-jobs.json",
    "maxConcurrentRuns": 2
  }
}
```

## memory Section

Memory backend configuration:

```json theme={null}
{
  "memory": {
    "backend": "builtin",
    "citations": "auto",
    "memu": {
      "llm": {
        "provider": "ollama",
        "model": "qwen3:1.7b"
      }
    }
  }
}
```

| Field       | Type     | Default     | Description                    |
| ----------- | -------- | ----------- | ------------------------------ |
| `backend`   | `string` | `"builtin"` | Memory backend: builtin or qmd |
| `citations` | `string` | `"auto"`    | Citation mode: auto, on, off   |

## logging Section

```json theme={null}
{
  "logging": {
    "level": "info",
    "file": "~/.argentos/logs/argent.log",
    "consoleLevel": "warn",
    "consoleStyle": "pretty",
    "redactSensitive": "tools"
  }
}
```

| Field             | Type     | Default    | Description                           |
| ----------------- | -------- | ---------- | ------------------------------------- |
| `level`           | `string` | `"info"`   | File log level                        |
| `consoleLevel`    | `string` | —          | Console log level                     |
| `consoleStyle`    | `string` | `"pretty"` | Console format: pretty, compact, json |
| `redactSensitive` | `string` | —          | Redaction mode: off, tools            |

## approvals Section

Default exec approval settings:

```json theme={null}
{
  "approvals": {
    "security": "allowlist",
    "ask": "on-miss",
    "askFallback": "deny"
  }
}
```

## intent Section

Intent governance hierarchy:

```json theme={null}
{
  "intent": {
    "validationMode": "enforce",
    "runtimeMode": "enforce",
    "global": {
      "objective": "Serve the operator's interests safely",
      "neverDo": ["Access unauthorized systems"],
      "requiresHumanApproval": ["financial_transactions"]
    }
  }
}
```

## hooks Section

Webhook and event hook configuration:

```json theme={null}
{
  "hooks": {
    "enabled": true,
    "path": "/hooks",
    "token": "webhook-secret",
    "presets": ["gmail"]
  }
}
```

## web Section

WebSocket client configuration (for dashboard connections):

```json theme={null}
{
  "web": {
    "enabled": true,
    "heartbeatSeconds": 30,
    "reconnect": {
      "initialMs": 1000,
      "maxMs": 30000,
      "factor": 2,
      "jitter": 0.1,
      "maxAttempts": 0
    }
  }
}
```

## Environment Variable Overrides

Several settings can be overridden via environment variables:

| Variable               | Override                               |
| ---------------------- | -------------------------------------- |
| `ARGENT_STATE_DIR`     | State directory path                   |
| `ARGENT_PROFILE`       | Active profile name                    |
| `ARGENT_GATEWAY_PORT`  | Gateway port                           |
| `ARGENT_GATEWAY_TOKEN` | Gateway auth token                     |
| `ARGENT_RUNTIME`       | Enable argent runtime (`true`/`false`) |
| `ANTHROPIC_API_KEY`    | Anthropic API key                      |
| `OPENAI_API_KEY`       | OpenAI API key                         |
| `OLLAMA_API_KEY`       | Ollama API key (usually not needed)    |

## Validation

The configuration is validated on load using Zod schemas. Invalid fields produce errors like:

```
Config validation error at agents.defaults.heartbeat.every:
  Expected string, received number
```

<Tip>
  Use `config.schema` gateway method to retrieve the full schema for programmatic validation.
</Tip>

## Key Files

| File                                      | Description                       |
| ----------------------------------------- | --------------------------------- |
| `src/config/zod-schema.ts`                | Main Zod schema (ArgentSchema)    |
| `src/config/zod-schema.agents.ts`         | Agent configuration schemas       |
| `src/config/zod-schema.agent-defaults.ts` | Agent defaults schema             |
| `src/config/types.agent-defaults.ts`      | TypeScript types for agent config |
| `src/config/types.argent.ts`              | Root config type definitions      |
| `src/config/config.ts`                    | Config loading and validation     |