Configuration Reference

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

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.

Top-Level Sections

{
  "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:

{
  "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:

{
  "models": {
    "providers": {
      "anthropic": { "apiKey": "env:ANTHROPIC_API_KEY" },
      "openai": { "apiKey": "env:OPENAI_API_KEY" }
    }
  }
}

auth Section

Authentication profiles for multi-provider failover:

{
  "auth": {
    "profiles": {
      "anthropic:main": {
        "provider": "anthropic",
        "mode": "api_key",
        "email": "[email protected]"
      }
    },
    "order": {
      "anthropic": ["anthropic:main", "anthropic:backup"]
    },
    "cooldowns": {
      "billingBackoffHours": 1,
      "failureWindowHours": 0.5
    }
  }
}

channels Section

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

{
  "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:

{
  "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:

{
  "session": {
    "dmScope": "main",
    "store": "~/.argentos/sessions"
  }
}

cron Section

Cron service configuration:

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

memory Section

Memory backend configuration:

{
  "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

{
  "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:

{
  "approvals": {
    "security": "allowlist",
    "ask": "on-miss",
    "askFallback": "deny"
  }
}

intent Section

Intent governance hierarchy:

{
  "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:

{
  "hooks": {
    "enabled": true,
    "path": "/hooks",
    "token": "webhook-secret",
    "presets": ["gmail"]
  }
}

web Section

WebSocket client configuration (for dashboard connections):

{
  "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

Use config.schema gateway method to retrieve the full schema for programmatic validation.

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

Getting Started

Installation

Channels

Agents

Connectors

Tools

Concepts

Memory

Model Router

Overview

Configuration File Location

Top-Level Sections

agents Section

Key Agent Fields

Heartbeat Configuration

Contemplation Configuration

Execution Worker Configuration

Kernel Configuration

models Section

auth Section

channels Section

gateway Section

session Section

cron Section

memory Section

logging Section

approvals Section

intent Section

hooks Section

web Section

Environment Variable Overrides

Validation

Key Files

​Overview

​Configuration File Location

​Top-Level Sections

​agents Section

​Key Agent Fields

​Heartbeat Configuration

​Contemplation Configuration

​Execution Worker Configuration

​Kernel Configuration

​models Section

​auth Section

​channels Section

​gateway Section

​session Section

​cron Section

​memory Section

​logging Section

​approvals Section

​intent Section

​hooks Section

​web Section

​Environment Variable Overrides

​Validation

​Key Files

Overview

Configuration File Location

Top-Level Sections

agents Section

Key Agent Fields

Heartbeat Configuration

Contemplation Configuration

Execution Worker Configuration

Kernel Configuration

models Section

auth Section

channels Section

gateway Section

session Section

cron Section

memory Section

logging Section

approvals Section

intent Section

hooks Section

web Section

Environment Variable Overrides

Validation

Key Files