CamelAGI Configuration System

This document covers the complete configuration system: file format, schema, environment variable overrides, runtime mechanics, hot-reload, and provider-specific examples.

Config File Location and Format

• Path: ~/.camelagi/config.yaml
• Format: YAML, parsed with the yaml npm package (parse / stringify)
• Source file: src/core/config.ts

The config directory (~/.camelagi/) and file are created automatically on first run or when saveConfig() is called. If the file does not exist at load time, all values fall back to schema defaults.

Complete Zod Schema Reference

Top-Level Fields

serve – Gateway Server

telegram – Telegram Channel

ChatOverride fields (all optional): name, model, systemPrompt, maxTurns, thinking ("off"|"low"|"medium"|"high"), effort ("low"|"medium"|"high"|"max").

compaction – Context Compaction

tools – Tool Policy

skills – Skill Loader

hooks – Lifecycle Hooks

approvals – Tool Approval System

voice – Voice Transcription

retry – Error Retry

lanes – Concurrency Lanes

agents – Multi-Agent Definitions

Type: Record<string, AgentDef> – Default: {}

Each agent entry has:

Agent telegram sub-object:

• botToken (string, required) – Separate bot token for this agent.
• allowedUsers (number[], default []) – Allowed user IDs.
• groups.mentionOnly (boolean, default true).

Agent discord sub-object:

• botToken (string, required) – Discord bot token.
• allowedChannels (string[], default []) – Channel IDs to respond in. Empty = all channels.
• allowedRoles (string[], default []) – Role names allowed. Empty = all users.
• mentionOnly (boolean, default true) – Only respond when @mentioned in servers.

cron – Scheduled Jobs

Type: CronJob[] – Default: []

Each cron entry:

Environment Variable Overrides

Seven environment variables are recognized. They override values from the YAML file:

The .env file is loaded automatically via dotenv/config.

Config Precedence

Values are resolved in this order (later wins):

1. Zod schema defaults
2. ~/.camelagi/config.yaml (file config)
3. Environment variables (CAMELAGI_*, ANTHROPIC_API_KEY, etc.)
4. Runtime overrides (passed to loadConfig(overrides))

In code, loadConfig() builds a merged object:

const merged = {
  ...fileConfig,          // from YAML
  ...envOverrides,        // from env vars
  ...overrides,           // from function argument
};
return schema.parse(merged);  // Zod fills in defaults for missing fields

Note: env vars for nested sections (CAMELAGI_TOKEN and TELEGRAM_BOT_TOKEN) are applied separately by merging into the existing serve / telegram sub-objects to avoid clobbering other nested fields.

loadConfig() Mechanics

export function loadConfig(overrides: Partial<Config> = {}): Config

1. If ~/.camelagi/config.yaml exists, read and parse it as YAML. Otherwise start with {}.
2. Spread env var overrides on top of the file config.
3. Spread runtime overrides argument on top.
4. For CAMELAGI_TOKEN: merge into the existing serve sub-object (preserving port, host, rateLimit).
5. For TELEGRAM_BOT_TOKEN: merge into the existing telegram sub-object (preserving allowedUsers, groups, chats).
6. Pass the merged object through schema.parse() – Zod validates and fills in all defaults.
7. Return the fully typed Config object.

saveConfig() Mechanics

export function saveConfig(values: Record<string, unknown>): void

1. Ensure ~/.camelagi/ exists (mkdirSync with recursive: true).
2. If config.yaml exists, read and parse the current contents.
3. Deep-merge the new values into the existing config (see deep merge behavior below).
4. Write the merged result back to config.yaml as YAML.
5. If an onConfigSaved callback is registered, call loadConfig() to produce a fresh Config (which re-applies env var overrides), then invoke the callback synchronously.

The onConfigSaved callback is used by serve.ts to immediately update the in-memory gateway state without waiting for the file-watcher debounce.

Deep Merge Behavior

The deepMerge(target, source) function follows these rules:

• Plain objects: recursively merged (keys from source overwrite or add to target).
• Arrays: replaced entirely, not concatenated. If source.tools.deny is ["exec"], it replaces whatever was in target.tools.deny.
• Scalars: source value overwrites target value.
• Null / undefined in source: overwrites the target value (no special handling).

This means if you call saveConfig({ tools: { deny: ["exec"] } }), only tools.deny is changed; tools.allow is preserved because the deep merge recurses into the tools object. But arrays like deny are replaced wholesale.

Hot-Reload (watchConfig)

Defined in src/serve.ts. The gateway watches for config changes at runtime.

function watchConfig(
  _initialConfig: Config,
  onChange: (config: Config) => void,
): fs.FSWatcher | null

Key details:

• Watches the directory (~/.camelagi/), not the file directly. This ensures detection even if config.yaml is deleted and recreated (e.g., after a reset + onboarding flow).
• Filters by filename: only reacts when the changed file is config.yaml.
• Debounced: uses a 500ms setTimeout debounce to coalesce rapid writes.
• On change: calls loadConfig() (re-applies env vars and defaults), then invokes the onChange callback.
• What onChange does in serve.ts:
  • Updates state.config and state.systemPrompt.
  • Reconfigures concurrency lanes (Lane.Main, Lane.Cron, Lane.Subagent).
  • Updates cron context.
  • Reconciles all channels (starts new agents, stops removed ones).
• Error handling: if loadConfig() throws (e.g., invalid YAML), the error is logged and the old config remains in effect.

ensureDirs() – Created Directories

Called at startup to guarantee the directory tree exists:

All directories are created with recursive: true, so parent directories are created as needed.

Provider-Specific Config Examples

Anthropic (default)

provider: anthropic
model: claude-sonnet-4-20250514
apiKey: sk-ant-...

Or via environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

No baseUrl needed – the OpenAI SDK compatibility layer routes to api.anthropic.com/v1/.

OpenAI

provider: openai
model: gpt-4o
apiKey: sk-...

Or:

export CAMELAGI_PROVIDER=openai
export OPENAI_API_KEY=sk-...
export CAMELAGI_MODEL=gpt-4o

OpenRouter

provider: openai
model: anthropic/claude-sonnet-4-20250514
apiKey: sk-or-...
baseUrl: https://openrouter.ai/api/v1

Ollama (local)

provider: openai
model: llama3
baseUrl: http://localhost:11434/v1

No apiKey needed for local Ollama.

Custom OpenAI-Compatible Endpoint

provider: openai
model: my-custom-model
apiKey: my-key
baseUrl: https://my-llm-proxy.example.com/v1

Full Annotated Config Example

# ── Provider ──────────────────────────────────────────────
provider: anthropic                     # "anthropic" | "openai"
model: claude-sonnet-4-20250514         # Model name
apiKey: sk-ant-...                      # API key (prefer env var instead)
# baseUrl: https://custom.api/v1       # Custom endpoint (optional)

# ── Prompt & Behavior ────────────────────────────────────
systemPrompt: "You are CamelAGI, a helpful AI assistant."
thinking: "off"                         # "off" | "low" | "medium" | "high"
effort: "high"                          # "low" | "medium" | "high" | "max"
# maxBudgetUsd: 5.0                    # Spending cap (optional)
maxTurns: 25                            # Max agent loop turns per run
timeoutSeconds: 300                     # Per-run timeout
boot: true                             # Run BOOT.md on server start

# ── Gateway Server ───────────────────────────────────────
serve:
  port: 18789
  host: "127.0.0.1"
  # token: "my-secret-token"           # Bearer auth (optional)
  rateLimit:
    windowMs: 60000                     # 1 minute window
    max: 60                             # 60 requests per window

# ── Telegram ─────────────────────────────────────────────
telegram:
  botToken: "123456:ABC..."             # Legacy top-level bot
  allowedUsers: [12345678]              # Allowed Telegram user IDs
  groups:
    mentionOnly: true                   # Only respond when @mentioned
  chats:                                # Per-chat overrides
    "-100123456789":
      name: "Dev Chat"
      model: claude-sonnet-4-20250514
      maxTurns: 10

# ── Compaction ───────────────────────────────────────────
compaction:
  enabled: true
  maxTokens: 80000                      # Triggers at 80% (~64K tokens)
  keepTurns: 6                          # Keep last 6 turns after compaction

# ── Tools ────────────────────────────────────────────────
tools:
  allow: []                             # Empty = allow all
  deny: []                              # e.g. ["exec"] to block shell

# ── Skills ───────────────────────────────────────────────
skills:
  enabled: true
  deny: []                              # e.g. ["risky-skill"]

# ── Hooks ────────────────────────────────────────────────
hooks:
  enabled: false

# ── Approvals ────────────────────────────────────────────
approvals:
  mode: "off"                           # "off" | "smart" | "always"
  allowlist: []                         # Tools that skip approval
  timeoutSeconds: 120
  fallback: "deny"                      # "deny" | "allow"
  # forwardTo: 12345678                 # Telegram chat for headless approvals

# ── Retry ────────────────────────────────────────────────
retry:
  maxRetries: 3
  backoffMs: 1000                       # Base delay, multiplied per attempt

# ── Concurrency Lanes ───────────────────────────────────
lanes:
  main: 3                              # Max concurrent main runs
  cron: 1                              # Max concurrent cron runs
  subagent: 5                          # Max concurrent sub-agent runs

# ── Agents (multi-bot) ──────────────────────────────────
agents:
  researcher:
    name: "Research Bot"
    admin: false
    model: claude-sonnet-4-20250514
    systemPrompt: "You are a research assistant."
    thinking: "medium"
    effort: "high"
    maxTurns: 15
    telegram:
      botToken: "654321:XYZ..."
      allowedUsers: [12345678]
      groups:
        mentionOnly: true

# ── Cron Jobs ────────────────────────────────────────────
cron:
  - id: daily-summary
    name: "Daily Summary"
    schedule: "1d"                       # every 24 hours (see extensions docs for cron limitations)
    prompt: "Summarize yesterday's activity."
    # session: "summary-session"        # Optional session for continuity
    enabled: true