Configuration Reference
Relevant source files
The following files were used as context for generating this wiki page:
The Configuration Reference provides a comprehensive guide to the Clawdbot settings architecture, covering environment variables, JSON schema definitions, and the UI-driven configuration management system. Clawdbot utilizes a centralized configuration file, typically clawdbot.json, which is validated against a strict Zod-derived JSON schema to ensure operational integrity.
This system manages everything from messaging channel credentials (Telegram, Discord, Slack) to agent workspace paths and automated update channels. The configuration can be modified via direct file editing, CLI commands, or the built-in Control UI.
Sources: src/config/schema.ts:1-15, src/cli/gateway-cli/dev.ts:75-85, ui/src/ui/views/config.ts:1-20
Configuration Architecture
Clawdbot's configuration logic is split between schema definition, environment-based overrides, and a reactive UI for management. The core schema is generated from Zod definitions and augmented with UI hints to provide a user-friendly experience in the Control UI.
Data Flow and Validation
The following diagram illustrates how configuration is loaded, validated, and rendered.
The configuration lifecycle from initial loading to UI-driven modification.
Sources: src/config/schema.ts:410-440, ui/src/ui/views/config.ts:114-130, src/config/config.nix-integration-u3-u5-u9.test.ts:40-60
Environment Variables
Clawdbot supports several environment variables that override file-based settings. These are particularly critical for Nix integrations and containerized environments.
| Variable | Description | Default / behavior |
|---|---|---|
CLAWDBOT_STATE_DIR | Base directory for logs, credentials, and state. | ~/.clawdbot |
CLAWDBOT_CONFIG_PATH | Explicit path to the clawdbot.json configuration file. | $STATE_DIR/clawdbot.json |
CLAWDBOT_NIX_MODE | If set to 1, enables Nix-specific pathing and read-only behaviors. | 0 |
CLAWDBOT_GATEWAY_PORT | Port the gateway server listens on. | Config-defined or default |
CLAWDBOT_PROFILE | Application profile (e.g., dev). | default |
Sources: src/config/config.nix-integration-u3-u5-u9.test.ts:5-45, src/cli/gateway-cli/dev.ts:38-42
Core Configuration Sections
The configuration is organized into logical groups for modular management. These groups are used to categorize settings in the UI and organize the JSON schema.
Section Definitions and Order
| Group Key | UI Label | Order | Description |
|---|---|---|---|
wizard | Setup Wizard | 20 | Initial setup state and onboarding history. |
gateway | Gateway | 30 | Server settings including bind address, port, and auth. |
agents | Agents | 40 | Agent identities, models, and workspace paths. |
tools | Tools | 50 | Search, browser, and media understanding settings. |
channels | Messaging Channels | 150 | Integration for Telegram, Discord, Slack, etc. |
logging | Logging | 900 | Log levels and diagnostic flags. |
Sources: src/config/schema.ts:37-75, ui/src/ui/views/config-form.render.ts:32-60
Agent Workspace Configuration
The agent workspace is a critical configuration component, defining the procedural knowledge and identity of the bot. It is managed via AGENTS.md, SOUL.md, and IDENTITY.md files located within the workspace directory.
Relationship between the workspace filesystem and internal agent configuration structures.
Workspace File Mapping
| File | Purpose | Config Equivalent |
|---|---|---|
AGENTS.md | Primary workspace documentation. | agents.defaults.workspace |
SOUL.md | Persona and tone guidelines. | extraSystemPrompt |
IDENTITY.md | Bot name, creature type, and emoji. | agents.list[].identity |
USER.md | User profile and preferences. | userTimezone / ownerNumbers |
Sources: apps/macos/Sources/Clawdbot/AgentWorkspace.swift:10-35, src/cli/gateway-cli/dev.ts:50-70
Tool and Channel Policies
Clawdbot employs granular policies for tool execution and messaging channel behavior. These are defined in the tools and channels branches of the configuration.
Tool Execution (Exec) Settings
tools.exec.host: Specifies where commands are executed (gateway vs. sandbox).tools.exec.safeBins: Allowlist of binaries that can run without explicit approval.tools.exec.applyPatch.enabled: Experimental feature for multi-file code modifications.
Messaging Channel Credentials
Each channel requires specific authentication fields:
- Telegram:
botTokenortokenFile(for Nix/Secret management). - Discord:
token. - Slack:
botToken,appToken, anduserToken. - Mattermost:
botTokenandbaseUrl.
Sources: src/config/schema.ts:135-165, src/config/schema.ts:210-245, src/config/config.nix-integration-u3-u5-u9.test.ts:150-170
UI Configuration Management
The Control UI provides two modes for managing configuration: a schema-aware Form Mode and a Raw JSON5 Mode.
Configuration UI Flow
When a user modifies a setting in the UI, the following sequence occurs:
- Paging: The UI identifies the specific JSON path (e.g.,
gateway.port). - Patching:
onFormPatchis triggered, updating the local reactive state. - Validation: The UI calculates a diff against the
originalValue. - Persistence: The
onSaveaction sends the updated JSON back to the gateway. - Reload: The gateway applies the new configuration, potentially triggering a service restart (e.g., if port or bind address changed).
Sources: ui/src/ui/views/config.ts:150-185, ui/src/ui/views/config-form.render.ts:150-180
Summary
The Configuration Reference defines the backbone of the Clawdbot environment, utilizing a hybrid approach of environment variables and schema-validated JSON files. By centralizing settings for agents, tools, and messaging channels, the system ensures that changes can be safely applied through CLI, file-system, or UI interfaces while maintaining strict validation via the Zod-derived schema.