Configuration Reference

Overview

OrcBot uses a hierarchical configuration system that reads settings from multiple sources in priority order:

Environment variables (highest priority)
Local config (./orcbot.config.yaml)
Home config (~/orcbot.config.yaml)
Global config (~/.orcbot/orcbot.config.yaml)

Configuration File Location

OrcBot searches for configuration files in this order:

./orcbot.config.yaml

Environment variables always override configuration file values for API keys and credentials.

Core Settings

Agent Identity

agentName

string

default:"OrcBot"

The display name for your agent instance.

agentIdentityPath

string

default:"~/.orcbot/.AI.md"

Path to the agent’s self-updating identity file containing personality and operating instructions.

LLM Configuration

modelName

string

default:"gpt-4o"

Primary LLM model to use. Examples: gpt-4o, gpt-4-turbo, claude-3-5-sonnet-20241022, gemini-2.0-flash-exp.Policy: SAFE - Agent can modify autonomously to optimize for different tasks.

llmProvider

enum

default:"openai"

Explicit LLM provider selection. Supported values:

openai - OpenAI (GPT-4, GPT-3.5, o1)
google - Google Gemini
bedrock - AWS Bedrock
openrouter - OpenRouter (200+ models)
nvidia - NVIDIA NIM
anthropic - Anthropic Claude
ollama - Local Ollama models

Policy: SAFE - Agent can switch providers based on availability.

providerModelNames

object

Per-provider model preferences. Automatically persists the last model used for each provider.

providerModelNames:
  openai: gpt-4o
  google: gemini-2.0-flash-exp
  anthropic: claude-3-5-sonnet-20241022

fallbackModelNames

object

Fallback models to use when primary provider is unavailable.

fallbackModelNames:
  openai: gpt-4o-mini
  google: gemini-1.5-flash

fastModelName

string

Fast model for lightweight operations (e.g., gpt-4o-mini, gemini-1.5-flash).

Ollama (Local Models)

ollamaEnabled

boolean

default:false

Enable local Ollama integration for running models locally.

ollamaApiUrl

string

default:"http://localhost:11434"

Ollama API endpoint URL.Policy: SAFE - Non-sensitive endpoint configuration.

Task Execution Limits

maxStepsPerAction

number

default:30

Maximum reasoning steps per action. Dynamically adjusted based on task complexity.Policy: SAFE - Agent can adjust complexity limits based on task needs.

maxMessagesPerAction

number

default:10

Maximum user-facing messages per action to prevent spam.Policy: SAFE - Agent can adjust delivery budget for long-running tasks.

maxActionRunMinutes

number

default:10

Maximum execution time for a single action in minutes.

maxStaleActionMinutes

number

default:30

Maximum time before an action is considered stale and terminated.

messageDedupWindow

number

default:10

Window (in messages) for deduplicating similar user messages.

Memory System

Memory Limits

memoryContextLimit

number

default:20

Number of recent short-term memories to include in context.Policy: SAFE - Agent can adjust to optimize performance (1-100).

memoryEpisodicLimit

number

default:5

Number of episodic summaries to include in context.Policy: SAFE - Agent can adjust for better context (1-20).

memoryExtendedContextLimit

number

default:2000

Character limit for extended memory context.

memoryContentMaxLength

number

default:500

Maximum length for individual memory entries (characters).

Memory File Paths

memoryPath

string

default:"~/.orcbot/memory.json"

Path to short-term memory storage (JSON).

journalPath

string

default:"~/.orcbot/JOURNAL.md"

Path to daily journal file for long-term event logging.

learningPath

string

default:"~/.orcbot/LEARNING.md"

Path to learning file where agent stores research findings.

userProfilePath

string

default:"~/.orcbot/USER.md"

Path to user profile containing preferences and facts.

worldPath

string

default:"~/.orcbot/world.md"

Path to world events log (GDELT, USGS earthquake data).

Memory Consolidation

memoryConsolidationThreshold

number

default:30

Number of short-term memories before triggering consolidation to episodic.

memoryConsolidationBatch

number

default:20

Batch size for memory consolidation operations.

memoryFlushSoftThreshold

number

default:25

Soft threshold for flushing memories to disk.

memoryFlushCooldownMinutes

number

default:30

Cooldown period between memory flush operations.

memoryInteractionBatchSize

number

default:12

Batch size for scoped interaction consolidation.Policy: SAFE - Non-sensitive memory quality tuning (4-100).

memoryInteractionStaleMinutes

number

default:10

Max minutes before pending interaction batch is consolidated.Policy: SAFE - Non-sensitive memory durability tuning (1-180).

memoryDedupWindowMinutes

number

default:5

Deduplication window for duplicate inbound memory events.Policy: SAFE - Non-sensitive reliability tuning (1-120).

Thread Context

threadContextRecentN

number

default:8

Number of recent messages to include in thread context.

threadContextRelevantN

number

default:8

Number of relevant messages to include from semantic search.

threadContextMaxLineLen

number

default:420

Maximum line length for thread context entries.

threadContextOtherMemoriesN

number

default:5

Number of other memories to include in thread context.

Context Limits by Type

journalContextLimit

number

default:1500

Character limit for journal entries in context.

learningContextLimit

number

default:1500

Character limit for learning entries in context.

userContextLimit

number

default:2000

Character limit for user profile data in context.

userExchangeContextLimit

number

default:8

Scoped user exchange count injected into decisions.Policy: SAFE - Non-sensitive context sizing control (3-30).

Step Compaction

stepCompactionThreshold

number

default:10

Number of steps before compaction is triggered.

stepCompactionPreserveFirst

number

default:2

Number of first steps to preserve during compaction.

stepCompactionPreserveLast

number

default:5

Number of last steps to preserve during compaction.

stepCompactionExpandOnDemand

boolean

default:true

Expand compacted middle step history for continuity-heavy tasks.Policy: SAFE - Non-sensitive context shaping behavior.

stepCompactionExpansionMaxMiddleSteps

number

default:12

Maximum number of middle steps to expand on continuity intent.Policy: SAFE - Non-sensitive context sizing control (1-50).

stepCompactionExpansionMaxChars

number

default:2400

Maximum characters reserved for expanded middle-step context.Policy: SAFE - Non-sensitive context sizing control (400-20000).

Autonomy & Heartbeat

autonomyEnabled

boolean

default:true

Enable autonomous operation mode where the agent can initiate tasks independently.Policy: APPROVAL - Autonomy mode should be explicitly approved.

autonomyInterval

number

default:15

Autonomous operation interval in minutes. Uses exponential backoff when unproductive.Policy: APPROVAL - Autonomy settings affect system behavior significantly.

autonomyPostUserCooldownSeconds

number

default:90

Cooldown period after user interaction before autonomy resumes.

autonomyBacklogLimit

number

default:3

Maximum number of autonomous tasks in the queue.

autonomyAllowedChannels

array

default:[]

List of channels where the agent can send proactive messages.

autonomyAllowedChannels:
  - telegram
  - discord

Empty array means silent mode - agent will not send unsolicited messages. Direct responses are always allowed.

workerPoolAllowAutonomyDuringUserWork

boolean

default:false

Allow autonomy lane to continue running while user lane is busy.Policy: APPROVAL - Parallel autonomy can increase throughput but may compete for resources.

Action Queue

actionQueuePath

string

default:"~/.orcbot/actions.json"

Path to the durable action queue file.

actionQueueCompletedTTL

number

default:86400000

Time-to-live for completed actions in milliseconds (default: 24 hours).

actionQueueFailedTTL

number

default:259200000

Time-to-live for failed actions in milliseconds (default: 72 hours).

actionQueueFlushIntervalMs

number

default:5000

Interval for flushing action queue to disk in milliseconds.

actionQueueMaintenanceIntervalMs

number

default:60000

Interval for action queue maintenance (cleanup) in milliseconds.

Command Execution

commandTimeoutMs

number

default:120000

Timeout for shell command execution in milliseconds (default: 2 minutes).

commandRetries

number

default:1

Number of retries for failed commands.

commandWorkingDir

string

Working directory for command execution (defaults to current directory).

commandAllowList

array

List of allowed commands. Default includes common development tools:

commandAllowList:
  - npm
  - node
  - git
  - python
  - curl
  - wget

commandDenyList

array

List of denied commands for security. Includes destructive operations:

commandDenyList:
  - rm
  - rmdir
  - del
  - format
  - shutdown

Policy: LOCKED - Security-critical configuration.

autoExecuteCommands

boolean

default:false

Automatically execute commands without confirmation (use with caution).

File Paths

projectRoot

string

default:"."

Root directory for source code operations. Auto-detected from package.json location.

buildWorkspacePath

string

default:"~/.orcbot/workspace"

Workspace directory for building and compiling code.

skillsPath

string

default:"~/.orcbot/SKILLS.md"

Path to skills documentation file.

pluginsPath

string

default:"~/.orcbot/plugins"

Directory for hot-loadable TypeScript plugins.

toolsPath

string

default:"~/.orcbot/tools"

Directory for custom tool scripts.

Plugins

pluginAllowList

array

default:[]

Whitelist of allowed plugins. Empty means all plugins are allowed.

pluginDenyList

array

default:[]

Blacklist of denied plugins. Takes precedence over allow list.

pluginHealthCheckIntervalMinutes

number

default:15

Interval for checking plugin health and auto-repair.

Decision Pipeline

Skill Routing

skillRoutingRules

array

default:[]

Intent-based skill selection rules for better tool matching.

skillRoutingRules:
  - match: "search"
    prefer:
      - web_search
      - browser_navigate
  - match: "code"
    prefer:
      - run_command
      - execute_typescript
    avoid:
      - browser_navigate

Policy: APPROVAL - Routing rules can affect which tools are used.

Tool Loop Protection

maxToolRepeats

number

default:5

Maximum times a tool can be repeated in sequence.

maxResearchToolRepeats

number

default:15

Higher repeat limit for research tools (web_search, browser_navigate).

maxToolLoops

number

default:3

Maximum number of tool usage loops before intervention.

Autopilot Mode

autopilotNoQuestions

boolean

default:false

Suppress clarification requests to keep agent moving autonomously.

autopilotNoQuestionsAllow

array

default:[]

Skills allowed to ask questions even in autopilot mode.

autopilotNoQuestionsDeny

array

default:[]

Skills explicitly denied from asking questions.

Reasoning & Simulation

robustReasoningMode

boolean

default:false

Enable enhanced reasoning with deeper analysis.

reasoningExposeChecklist

boolean

default:false

Send the agent’s internal step-by-step checklist to the user before starting complex tasks.

reasoningChecklistMaxItems

number

default:5

Maximum number of checklist items to expose.

skipSimulationForSimpleTasks

boolean

default:true

Skip pre-task simulation for simple/trivial tasks to reduce latency.

compactSkillsPrompt

boolean

default:false

Use compact skill descriptions in prompts to reduce token usage.

Progress Feedback

progressFeedbackEnabled

boolean

default:true

Enable progress feedback messages during long-running tasks.Policy: SAFE - Agent can adjust feedback verbosity.

progressFeedbackStepInterval

number

default:4

Send progress update every N steps.

progressFeedbackForceInitial

boolean

default:true

Always send initial “working on it” message.

progressFeedbackTypingOnly

boolean

default:true

Use typing indicators instead of sending progress messages (reduces noise).Policy: SAFE - Agent can reduce channel noise while preserving feedback.

User Experience

sessionScope

enum

default:"per-channel-peer"

Conversation session scope:

main - Single global session
per-peer - Separate session per user
per-channel-peer - Separate session per channel-user combination

onboardingQuestionnaireEnabled

boolean

default:true

Prompt new users with onboarding questionnaire.

reconnectBriefingEnabled

boolean

default:true

Send briefing to users who reconnect after inactivity.

reconnectBriefingThresholdDays

number

default:3

Days of inactivity before triggering reconnect briefing.

reconnectBriefingMaxCompletions

number

default:5

Maximum completed tasks to include in briefing.

reconnectBriefingMaxPending

number

default:3

Maximum pending tasks to include in briefing.

enforceExplicitFileRequestForSendFile

boolean

default:false

Require explicit user request before send_file is allowed.Policy: SAFE - Agent can tune delivery strictness for file attachments.

Storage

vectorMemoryMaxEntries

number

default:5000

Maximum entries in vector memory index.

processedMessagesCacheSize

number

default:1000

Size of processed messages cache for deduplication.

tokenUsagePath

string

default:"~/.orcbot/token-usage-summary.json"

Path to token usage summary file.

tokenLogPath

string

default:"~/.orcbot/token-usage.log"

Path to detailed token usage log.

Server Mode

serverMode

boolean

default:false

Enable conservative defaults optimized for server/headless deployments.Applies reduced memory limits and more aggressive cleanup:

Reduced memory context limits
Shorter action TTLs
More frequent maintenance cycles
Compact skills prompt enabled

Web Gateway

gatewayPort

number

default:3100

HTTP port for the web gateway.

gatewayHost

string

default:"0.0.0.0"

Host address to bind the gateway server.

gatewayApiKey

string

API key for authenticating gateway requests.

curl -H "X-Api-Key: your-key" http://localhost:3100/api/status

gatewayCorsOrigins

array

default:["*"]

CORS allowed origins for gateway API.

Image Generation

imageGenProvider

enum

Image generation provider:

openai - DALL-E
google - Imagen

Policy: SAFE - Non-critical preference setting.

imageGenModel

string

Image generation model name.Policy: SAFE - Non-critical preference setting.

imageGenSize

string

default:"1024x1024"

Default image generation size (e.g., 1024x1024, 512x512).

imageGenQuality

string

default:"medium"

Image generation quality (low, medium, high).

Agentic User

agenticUserEnabled

boolean

default:false

Enable agentic user simulation for testing and validation.

agenticUserResponseDelay

number

default:120

Simulated user response delay in seconds.

agenticUserConfidenceThreshold

number

default:70

Confidence threshold (0-100) for agentic user interventions.

agenticUserProactiveGuidance

boolean

default:true

Enable proactive guidance from agentic user.

agenticUserProactiveStepThreshold

number

default:8

Steps before proactive guidance is triggered.

agenticUserCheckInterval

number

default:30

Interval for checking agentic user status in seconds.

agenticUserMaxInterventions

number

default:3

Maximum interventions per task from agentic user.

agenticUserNotifyUser

boolean

default:true

Notify real user about agentic user interventions.

World Events

worldEventsSources

array

default:["gdelt","usgs"]

Data sources for world events tracking:

gdelt - GDELT Project (global events)
usgs - USGS earthquake data

worldEventsRefreshSeconds

number

default:60

Interval for refreshing world events data.

worldEventsLookbackMinutes

number

default:60

Lookback window for fetching historical events.

worldEventsMaxRecords

number

default:250

Maximum number of event records to store.

worldEventsBatchMinutes

number

default:10

Batch interval for event aggregation.

worldEventsStoreEnabled

boolean

default:true

Store world events to memory.

worldEventsHeartbeatEnabled

boolean

default:true

Include world events in autonomy heartbeat.

worldEventsGdeltQuery

string

default:"global"

GDELT query filter.

worldEventsGlobeRenderer

enum

default:"mapscii"

Globe visualization renderer:

ascii - ASCII art
external - External command
map - Simple map
mapscii - MapSCII terminal viewer

worldEventsGlobeCommand

string

default:"mapscii"

Command for external globe renderer.

worldEventsGlobeArgs

array

default:[]

Arguments for globe renderer command.

Guidance & Guardrails

guidanceMode

enum

default:"balanced"

Completion guidance strictness:

strict - Enforce all delivery rules strictly
balanced - Moderate enforcement
fluid - Flexible completion criteria

guidanceAckPatterns

array

Regular expressions for detecting acknowledgement-only messages.

guidanceLowValuePatterns

array

Regular expressions for detecting low-value status updates.

guidanceClarificationKeywords

array

Keywords for detecting clarification questions.

guidanceQuestionStopWords

array

Stop words to ignore when analyzing questions.

guidanceRepeatQuestionThreshold

number

Similarity threshold for detecting repeated questions.

guidanceShortReplyMaxWords

number

default:7

Maximum word count for short replies.

guidanceShortReplyMaxChars

number

default:48

Maximum character count for short replies.

Time Signals

timeSignalHighRiskNoMessageSeconds

number

default:25

Seconds without message before triggering high-risk time signal.

timeSignalMediumRiskSilentSteps

number

default:4

Silent steps before medium-risk time signal.

timeSignalMediumRiskSinceDeliverySeconds

number

default:45

Seconds since last delivery before medium-risk time signal.

Session Anchoring

sessionAnchorEnabled

boolean

default:true

Enable session anchoring for conversation continuity.

sessionAnchorMaxHints

number

default:4

Maximum session anchor hints to include in context.

Task Deduplication

taskDedupWindowMs

number

default:60000

Window for deduplicating similar tasks in milliseconds (default: 1 minute).

messageSimilarityThreshold

number

Similarity threshold (0-1) for detecting duplicate messages.

recoveryDedupWindowHours

number

default:6

Deduplication window for recovery tasks in hours.

Time Capsule

timeCapsuleMaxSteps

number

default:500

Maximum steps to preserve in time capsule.

timeCapsuleMaxMessages

number

default:100

Maximum messages to preserve in time capsule.

OrcBot CLI Control

orcbotControlEnabled

boolean

default:true

Allow agent to run orcbot CLI commands.

orcbotControlCliAllowList

array

Allowed orcbot CLI commands:

orcbotControlCliAllowList:
  - config get
  - config set
  - models
  - security

orcbotControlCliDenyList

array

Denied orcbot CLI commands:

orcbotControlCliDenyList:
  - reset
  - daemon stop

orcbotControlTimeoutMs

number

default:45000

Timeout for orcbot CLI commands in milliseconds.

Termination Force (TForce)

tforceEnabled

boolean

default:true

Enable Termination Force incident tracking and prevention.

tforceMaxIncidentsPerAction

number

default:30

Maximum incidents tracked per action.

Usage Telemetry

usagePingEnabled

boolean

default:true

Enable anonymous usage telemetry.

usagePingUrl

string

default:""

Telemetry endpoint URL.

usagePingTimeoutMs

number

default:4000

Timeout for telemetry requests in milliseconds.

usagePingToken

string

default:""

Authentication token for telemetry.

Pi AI Integration

usePiAI

boolean

default:true

Enable Pi AI integration for enhanced reasoning.

Identity Links

identityLinks

object

Map user identities across channels:

identityLinks:
  telegram:123456789: whatsapp:1234567890@s.whatsapp.net
  discord:987654321: telegram:123456789

Example Configuration

orcbot.config.yaml

# Basic Setup
agentName: MyOrcBot
modelName: gpt-4o
llmProvider: openai

# Autonomy
autonomyEnabled: true
autonomyInterval: 15
autonomyAllowedChannels:
  - telegram

# Memory
memoryContextLimit: 30
memoryEpisodicLimit: 10

# Task Execution
maxStepsPerAction: 40
maxMessagesPerAction: 15

# Security
safeMode: false
commandDenyList:
  - rm
  - rmdir
  - shutdown

# Progress
progressFeedbackEnabled: true
progressFeedbackTypingOnly: true

CLI Commands

Core Skills

Configuration

​Overview

​Configuration File Location

​Core Settings

​Agent Identity

​LLM Configuration

​Ollama (Local Models)

​Task Execution Limits

​Memory System

​Memory Limits

​Memory File Paths

​Memory Consolidation

​Thread Context

​Context Limits by Type

​Step Compaction

​Autonomy & Heartbeat

​Action Queue

​Command Execution

​File Paths

​Plugins

​Decision Pipeline

​Skill Routing

​Tool Loop Protection

​Autopilot Mode

​Reasoning & Simulation

​Progress Feedback

​User Experience

​Storage

​Server Mode

​Web Gateway

​Image Generation

​Agentic User

​World Events

​Guidance & Guardrails

​Time Signals

​Session Anchoring

​Task Deduplication

​Time Capsule

​OrcBot CLI Control

​Termination Force (TForce)

​Usage Telemetry

​Pi AI Integration

​Identity Links

​Example Configuration

Overview

Configuration File Location

Core Settings

Agent Identity

LLM Configuration

Ollama (Local Models)

Task Execution Limits

Memory System

Memory Limits

Memory File Paths

Memory Consolidation

Thread Context

Context Limits by Type

Step Compaction

Autonomy & Heartbeat

Action Queue

Command Execution

File Paths

Plugins

Decision Pipeline

Skill Routing

Tool Loop Protection

Autopilot Mode

Reasoning & Simulation

Progress Feedback

User Experience

Storage

Server Mode

Web Gateway

Image Generation

Agentic User

World Events

Guidance & Guardrails

Time Signals

Session Anchoring

Task Deduplication

Time Capsule

OrcBot CLI Control

Termination Force (TForce)

Usage Telemetry

Pi AI Integration

Identity Links

Example Configuration