Configuration

Configuration Reference

Every config field, its type, and default value.

Configuration Reference

This is the complete field-by-field reference for BabyClaw's config file (~/.config/babyclaw/config.json).


Type	`number`
Required	Yes
Value	Must be `1`

`telegram`


Type	`object`
Required	No

Legacy alternative to channels.telegram. Has the same botToken field. You can use either location -- channels.telegram.botToken is preferred.

`ai`

`ai.providers`


Type	`object` (map of provider name to config)
Required	Yes

At least one provider must be configured. Each provider has:

Field	Type	Required	Description
`apiKey`	`string`	Yes	API key for the provider
`baseUrl`	`string` (URL)	No	Custom endpoint URL (for proxies, self-hosted, or OpenRouter)

`ai.models`


Type	`object`
Required	Yes

Field	Type	Required	Default	Description
`chat`	`string`	Yes	--	Main conversation model (`provider:modelId`)
`vision`	`string`	No	--	Model for image processing

`ai.aliases`


Type	`object` (map of alias to model reference)
Required	No
Default	`{}`

Short names for models. Alias names must match ^[a-z0-9_-]+$.

`database`

`database.url`


Type	`string`
Default	`"file:../data/babyclaw.db"`

SQLite connection string. The default stores the database alongside the gateway.

`scheduler`

`scheduler.timezone`


Type	`string` (IANA timezone)
Default	`"UTC"`

Timezone used for scheduled tasks and heartbeat active hours. Must be a valid IANA timezone like "America/New_York" or "Europe/London".

`workspace`

`workspace.root`


Type	`string`
Default	`"."`

Path to the agent's workspace directory. This is where personality files, memory, and skills live.

`session`

`session.maxMessagesPerSession`


Type	`integer`
Default	`120`

Maximum number of messages stored per session. Older messages are pruned when this limit is reached.

`session.historyLimit`


Type	`integer`
Default	`40`

Number of recent messages included in the agent's context for each turn. Lower values reduce token usage; higher values give the agent more context.

`session.replyChainMode`


Type	`string`
Default	`"default"`
Options	`"default"`, `"reply-chain"`

In "default" mode, sessions are determined by chat and thread. In "reply-chain" mode, replying to a specific message continues that session's context.

`session.titleGeneration`


Type	`object`
Default	`{}`

Field	Type	Required	Description
`model`	`string`	No	Model to use for generating session titles (defaults to the chat model)
`prompt`	`string`	No	Custom prompt for title generation

`tools`

`tools.enableGenericTools`


Type	`boolean`
Default	`true`

When true, the agent has access to workspace, shell, state, web search, messaging, media, and working memory tools. Set to false to restrict the agent to only scheduler and self-management tools.

`tools.shell`


Type	`object`

`tools.shell.mode`


Type	`string`
Default	`"allowlist"`
Options	`"allowlist"`, `"full-access"`

In "allowlist" mode, the agent can only run commands from the allowedCommands list. In "full-access" mode, it can run any command (a warning is logged at startup).

`tools.shell.allowedCommands`


Type	`array` of `string`
Default	See below

Commands the agent is allowed to run in allowlist mode. The default list includes common file operations, text processing, git, Node.js/Python package managers, and network tools:

ls, cat, head, tail, wc, grep, rg, find, file, du, df, date, echo, env, pwd, sort, uniq, cut, awk, sed, tr, xargs, tee, diff, which, basename, dirname, realpath, mkdir, cp, mv, rm, touch, chmod, git, node, npm, npx, pnpm, yarn, python, python3, pip, pip3, curl, wget, jq, tar, zip, unzip, remindctl

`tools.webSearch`


Type	`object`

`tools.webSearch.braveApiKey`


Type	`string` or `null`
Default	`null`

API key for the Brave Search API. When set, the agent gets a web_search tool. When null, web search is disabled.

`skills`

`skills.entries`


Type	`object` (map of skill name to config)
Default	`{}`

Per-skill configuration. Each entry can have:

Field	Type	Default	Description
`enabled`	`boolean`	`true`	Enable or disable this skill
`apiKey`	`string`	--	API key for the skill (if it needs one)
`env`	`object`	--	Environment variables to inject for this skill

Example:

{
  "skills": {
    "entries": {
      "web-scraper": { "enabled": true },
      "image-gen": {
        "enabled": true,
        "apiKey": "key-here",
        "env": { "IMAGE_MODEL": "dall-e-3" }
      }
    }
  }
}

`logging`

`logging.level`


Type	`string`
Default	`"info"`
Options	`"debug"`, `"info"`, `"warn"`, `"error"`

`logging.format`


Type	`string`
Default	`"pretty"` (development) / `"json"` (production)
Options	`"json"`, `"pretty"`

`logging.output`


Type	`string`
Default	`"stdout"`

Where to write logs. Defaults to standard output.

`logging.redact`


Type	`array` of `string`
Default	`[]`

List of field names to redact from log output.

`logging.includeTimestamps`


Type	`boolean`
Default	`true`

`logging.includeHostname`


Type	`boolean`
Default	`false`

`heartbeat`

`heartbeat.enabled`


Type	`boolean`
Default	`false`

Enable periodic heartbeat check-ins. See Heartbeat.

`heartbeat.intervalMinutes`


Type	`integer`
Default	`30`
Minimum	`5`

Minutes between heartbeat runs.

`heartbeat.activeHours`


Type	`object`

`heartbeat.activeHours.start`


Type	`string` (`HH:MM`) or `null`
Default	`null`

Start of the active window. When null, heartbeats can run at any time.

`heartbeat.activeHours.end`


Type	`string` (`HH:MM`) or `null`
Default	`null`

End of the active window.

`heartbeat.prompt`


Type	`string`
Default	`"Read HEARTBEAT.md if it exists. Follow its instructions. Do not infer or repeat old tasks from prior chats. If nothing needs attention, say so."`

The prompt sent to the agent on each heartbeat run. You can customize this, but the default works well with the standard HEARTBEAT.md workflow.

AI Providers

How to configure AI providers and models in BabyClaw.

How the Telegram integration works -- setting up a bot, conversations, and supported features.