Configuration

Configuration File Structure

OrcBot uses a hierarchical YAML-based configuration system that supports multiple config file locations, environment variable overrides, and hot-reload capabilities.

Configuration Priority

OrcBot reads configuration in this order (highest priority first):

Environment Variables

Environment variables like OPENAI_API_KEY, TELEGRAM_TOKEN take precedence

Local Config

./orcbot.config.yaml in your current working directory

Home Config

~/orcbot.config.yaml in your home directory

Global Config

~/.orcbot/orcbot.config.yaml (default location)

Basic Configuration File

Create your configuration file at ~/.orcbot/orcbot.config.yaml:

# ~/.orcbot/orcbot.config.yaml

# LLM Provider Configuration
llmProvider: openai
modelName: gpt-4o-mini
openaiApiKey: sk-your-key-here

# Alternative providers
# googleApiKey: your-google-api-key
# openrouterApiKey: your-openrouter-key
# anthropicApiKey: your-anthropic-key

# Agent Identity
agentName: OrcBot

# Channel Tokens
telegramToken: your-telegram-bot-token
discordToken: your-discord-bot-token

# Autonomy Settings
autonomyEnabled: true
autonomyInterval: 300000  # 5 minutes in milliseconds
autonomyBacklogLimit: 10
autonomyAllowedChannels:
  - telegram
  - discord

# Task Execution Limits
maxStepsPerAction: 20
maxMessagesPerAction: 5
messageDedupWindow: 15

# Safety & Security
safeMode: false
sudoMode: false
adminUsers:
  telegram:
    - "123456789"  # Your Telegram user ID
  discord:
    - "987654321"  # Your Discord user ID

# Memory & Context
memoryContextLimit: 15
journalContextLimit: 1000
learningContextLimit: 1000
userContextLimit: 1500

# Web Gateway
gatewayPort: 3100
gatewayHost: 0.0.0.0
gatewayApiKey: your-secret-api-key

# Browser Settings
browserHeadless: true
browserMaxConcurrent: 2

Environment Variables

API Keys

export OPENAI_API_KEY="sk-your-key-here"
export TELEGRAM_TOKEN="your-telegram-bot-token"
export GOOGLE_API_KEY="your-google-api-key"
export SERPER_API_KEY="your-serper-api-key"

Supported Environment Variables

Variable	Purpose
`OPENAI_API_KEY`	OpenAI API authentication
`GOOGLE_API_KEY`	Google Gemini API authentication
`ANTHROPIC_API_KEY`	Anthropic Claude API authentication
`OPENROUTER_API_KEY`	OpenRouter API authentication
`NVIDIA_API_KEY`	NVIDIA NIM API authentication
`SERPER_API_KEY`	Serper search API
`BRAVE_SEARCH_API_KEY`	Brave search API
`TELEGRAM_TOKEN`	Telegram bot token from @BotFather
`DISCORD_TOKEN`	Discord bot token
`SLACK_BOT_TOKEN`	Slack bot token
`CAPTCHA_API_KEY`	2Captcha API key for solving CAPTCHAs
`ORCBOT_DATA_DIR`	Override data directory (default: `~/.orcbot`)
`ORCBOT_CONFIG_PATH`	Override config file path

Environment variables only override config values if the config file doesn’t already define them. Config files take precedence.

Hot-Reload Configuration

OrcBot automatically watches the configuration file for changes and reloads settings without restarting.

How It Works

// ConfigManager watches the file and emits events
fs.watch(this.configPath, (eventType) => {
  if (eventType === 'change') {
    const oldConfig = { ...this.config };
    this.config = this.loadConfig(customPath, true);
    eventBus.emit('config:changed', { oldConfig, newConfig: this.config });
  }
});

Live Update Example

Edit Config

Open ~/.orcbot/orcbot.config.yaml in your editor

Change Settings

modelName: gpt-4o  # Change from gpt-4o-mini to gpt-4o
autonomyInterval: 600000  # Change interval to 10 minutes

Save File

Save the file. OrcBot will log:

ConfigManager: Config file changed on disk, reloading...
ConfigManager: Config reloaded and config:changed event emitted

Changes Applied

New settings take effect immediately for the next action

Hot-reload does not restart channel connections (Telegram, Discord, WhatsApp). To apply channel token changes, restart OrcBot.

Agent-Driven Config Management

OrcBot v2.0+ includes intelligent configuration where the agent can optimize settings based on task requirements.

Policy-Based Security

Config keys are classified into three policy levels:

SAFE
APPROVAL
LOCKED

The agent can modify these autonomously without approval:

modelName - Switch between models
memoryContextLimit - Adjust context window
maxStepsPerAction - Increase/decrease step budget
maxMessagesPerAction - Control response verbosity
reasoningExposeChecklist - Show/hide planning steps

The agent can request changes, but requires human approval:

API keys (openaiApiKey, googleApiKey, etc.)
llmProvider - Switch LLM provider
autonomyEnabled - Enable/disable autonomy
autonomyInterval - Change heartbeat frequency

The agent cannot modify these:

safeMode - Prevents command execution
sudoMode - Elevated permissions
adminUsers - Admin access control
pluginAllowList / pluginDenyList - Plugin security

Autonomous Optimization

The agent intelligently adjusts configuration when:

Code tasks need more capable models → auto-switch to GPT-4
Complex tasks require more memory context → increase memoryContextLimit
Multi-step workflows need higher step budgets → increase maxStepsPerAction
LLM provider is unavailable → auto-fallback to alternatives

Using manage_config Skill

// Agent autonomously optimizes for code tasks
manage_config({
  action: "set",
  key: "modelName",
  value: "gpt-4o",
  reason: "Code refactoring task benefits from GPT-4's superior reasoning"
})

// Agent requests approval for sensitive changes
manage_config({
  action: "set",
  key: "openaiApiKey",
  value: "sk-new-key",
  reason: "API key rotation for security"
})

// View pending approvals
manage_config({ action: "pending" })

// Approve a requested change
manage_config({ action: "approve", key: "openaiApiKey" })

Server Mode Defaults

When serverMode: true is set, OrcBot applies conservative defaults optimized for headless deployments:

serverMode: true

# Automatically applies:
actionQueueCompletedTTL: 7200000  # 2 hours
actionQueueFailedTTL: 43200000    # 12 hours
vectorMemoryMaxEntries: 1500
processedMessagesCacheSize: 300
memoryConsolidationThreshold: 20
journalContextLimit: 800
learningContextLimit: 800
skipSimulationForSimpleTasks: true
compactSkillsPrompt: true

Configuration Syncing

OrcBot automatically syncs config changes across multiple config file locations while protecting secrets:

private syncConfigAcrossPaths() {
  const targets = [globalPath, homePath, localPath]
    .filter(p => p !== this.configPath);

  const protectedKeys = [
    'telegramToken', 'discordToken', 'openaiApiKey',
    'googleApiKey', 'smtpPassword', 'imapPassword'
  ];

  // Merge current config with existing values
  const merged = { ...this.config };
  for (const key of protectedKeys) {
    if (!merged[key] && targetConfig[key]) {
      merged[key] = targetConfig[key];  // Preserve existing secrets
    }
  }

  fs.writeFileSync(target, yaml.stringify(merged));
}

Config syncing is disabled for worker processes to prevent corruption. Worker configs are isolated to their instance directories.

Advanced Settings

Task Complexity Classifier

# Dynamic step budgets based on LLM-classified complexity
skipSimulationForSimpleTasks: true  # Skip planning for trivial tasks

# Complexity-based budgets:
# - trivial: 5 steps, 1 message
# - simple: 10 steps, 2 messages
# - standard: 20 steps, 5 messages
# - complex: 35 steps, 8 messages

Skill Routing Rules

Configure intent-based skill selection:

skillRoutingRules:
  - intent: "search"
    preferSkills:
      - web_search
      - browser_navigate
  - intent: "code"
    preferSkills:
      - run_command
      - execute_typescript
  - intent: "communication"
    preferSkills:
      - send_message
      - telegram_send_buttons

Autonomy Channel Policy

Control where the agent can send proactive updates:

autonomyAllowedChannels:
  - telegram  # Agent can message Telegram proactively
  - discord   # Agent can message Discord proactively
  # WhatsApp omitted - agent won't send unprompted messages there

Direct Responses: Always allowed on any channel where the user messages the botProactive Updates: Only allowed on channels listed in autonomyAllowedChannelsDefault: Empty [] means silent in background

Memory & Consolidation

# Memory consolidation thresholds
memoryConsolidationThreshold: 25  # Trigger at 25 short memories
memoryConsolidationBatch: 20      # Consolidate 20 at a time
memoryFlushSoftThreshold: 22      # Soft limit before flushing
memoryFlushCooldownMinutes: 30    # Wait 30min between flushes

# Vector memory
vectorMemoryMaxEntries: 2000      # Max semantic search entries
vectorMemoryEnabled: true

# Context limits
memoryContextLimit: 15            # Recent step memories
threadContextRecentN: 8           # Recent thread messages
threadContextRelevantN: 6         # Relevant thread messages
memoryExtendedContextLimit: 1200  # Extended context chars

Platform-Specific Paths

OrcBot automatically normalizes file paths for cross-platform compatibility:

private normalizePlatformPaths(config: AgentConfig): AgentConfig {
  // On Windows, POSIX paths from CI/Linux are remapped
  if (process.platform === 'win32') {
    const remapIfCiOrPosix = (value: string): string => {
      // /home/runner/.orcbot/memory.json → C:\Users\You\.orcbot\memory.json
      const idx = normalized.indexOf('/.orcbot/');
      if (idx >= 0) {
        const suffix = normalized.slice(idx + '/.orcbot/'.length);
        return path.join(this.dataHome, ...suffix.split('/'));
      }
      return value;
    };
  }
}

Accessing Config in Code

From Agent Instance

// Get single value
const modelName = this.agent.config.get('modelName');
const apiKey = this.agent.config.get('openaiApiKey');

// Set value (triggers hot-reload)
this.agent.config.set('modelName', 'gpt-4o');

// Get all config
const allConfig = this.agent.config.getAll();

// Get data directory
const dataHome = this.agent.config.getDataHome();

Listen for Config Changes

import { eventBus } from './core/EventBus';

eventBus.on('config:changed', ({ oldConfig, newConfig }) => {
  if (oldConfig.modelName !== newConfig.modelName) {
    logger.info(`Model changed: ${oldConfig.modelName} → ${newConfig.modelName}`);
  }
});

Troubleshooting

Config Not Loading

# Check which config file is being used
node dist/cli/index.js run
# Look for: "ConfigManager: Config path set to ..."

# Verify config syntax
npx js-yaml ~/.orcbot/orcbot.config.yaml

Environment Variables Not Working

Environment variables are fallback only. If the config file already defines a value, the env var is ignored.To force env var usage, remove the key from your config file.

Hot-Reload Not Working

# Check file watcher is active
# OrcBot logs: "ConfigManager: Config file changed on disk, reloading..."

# If not working:
# 1. Check file permissions (must be readable)
# 2. Some editors use atomic writes that break watchers
# 3. Restart OrcBot to re-establish watch

Worker Corruption Repair

If you see paths like orchestrator/instances/agent-xxx in your config:

# OrcBot auto-repairs on next load:
ConfigManager: Repairing worker-corrupted path for memoryPath: ...
ConfigManager: Worker-corruption repair complete. Saving corrected config.

This happens automatically. No action needed.

Get Started

Core Concepts

Guides

Advanced

Configuration File Structure

Configuration Priority

Basic Configuration File

Environment Variables

API Keys

Supported Environment Variables

Hot-Reload Configuration

How It Works

Live Update Example

Agent-Driven Config Management

Policy-Based Security

Autonomous Optimization

Using manage_config Skill

Server Mode Defaults

Configuration Syncing

Advanced Settings

Task Complexity Classifier

Skill Routing Rules

Autonomy Channel Policy

Memory & Consolidation

Platform-Specific Paths

Accessing Config in Code

From Agent Instance

Listen for Config Changes

Troubleshooting

Config Not Loading

Environment Variables Not Working

Hot-Reload Not Working

Worker Corruption Repair

Get Started

Core Concepts

Guides

Advanced

​Configuration File Structure

​Configuration Priority

​Basic Configuration File

​Environment Variables

​API Keys

​Supported Environment Variables

​Hot-Reload Configuration

​How It Works

​Live Update Example

​Agent-Driven Config Management

​Policy-Based Security

​Autonomous Optimization

​Using manage_config Skill

​Server Mode Defaults

​Configuration Syncing

​Advanced Settings

​Task Complexity Classifier

​Skill Routing Rules

​Autonomy Channel Policy

​Memory & Consolidation

​Platform-Specific Paths

​Accessing Config in Code

​From Agent Instance

​Listen for Config Changes

​Troubleshooting

​Config Not Loading

​Environment Variables Not Working

​Hot-Reload Not Working

​Worker Corruption Repair

Configuration File Structure

Configuration Priority

Basic Configuration File

Environment Variables

API Keys

Supported Environment Variables

Hot-Reload Configuration

How It Works

Live Update Example

Agent-Driven Config Management

Policy-Based Security

Autonomous Optimization

Using manage_config Skill

Server Mode Defaults

Configuration Syncing

Advanced Settings

Task Complexity Classifier

Skill Routing Rules

Autonomy Channel Policy

Memory & Consolidation

Platform-Specific Paths

Accessing Config in Code

From Agent Instance

Listen for Config Changes

Troubleshooting

Config Not Loading

Environment Variables Not Working

Hot-Reload Not Working

Worker Corruption Repair