Skip to main content
NanoClaw configuration is managed through environment variables and the config.ts module.

​
Environment variables

Configuration is read from .env file or process.env.
​
ASSISTANT_NAME
string
default:"Andy"
Name of the assistant. Used in trigger pattern and message routing.
​
ASSISTANT_HAS_OWN_NUMBER
boolean
default:"false"
Whether the assistant has its own phone number or dedicated account. Set to "true" to enable.
​
CONTAINER_IMAGE
string
default:"nanoclaw-agent:latest"
Docker image to use for agent containers.
​
CONTAINER_TIMEOUT
number
default:"1800000"
Container timeout in milliseconds (default: 30 minutes).
​
CONTAINER_MAX_OUTPUT_SIZE
number
default:"10485760"
Maximum container output size in bytes (default: 10MB).
​
IDLE_TIMEOUT
number
default:"1800000"
How long to keep container alive after last result in milliseconds (default: 30 minutes).
​
ONECLI_URL
string
default:"http://localhost:10254"
URL for the OneCLI gateway that handles credential injection for containers.
​
MAX_CONCURRENT_CONTAINERS
number
default:"5"
Maximum number of concurrent agent containers.
​
TZ
string
default:"system timezone"
Timezone for scheduled tasks (cron expressions). Uses Intl.DateTimeFormat().resolvedOptions().timeZone by default.

​
Configuration constants

Defined in src/config.ts: 
export const POLL_INTERVAL = 2000; // Message loop interval (ms)
export const SCHEDULER_POLL_INTERVAL = 60000; // Task scheduler interval (ms)
export const IPC_POLL_INTERVAL = 1000; // IPC watcher interval (ms)

​
Directory paths

All paths are absolute and resolved from the project root:
​
STORE_DIR
string
{PROJECT_ROOT}/store - Database and persistent storage
​
GROUPS_DIR
string
{PROJECT_ROOT}/groups - Group folders and memory files
​
DATA_DIR
string
{PROJECT_ROOT}/data - Runtime data directory (sessions, IPC namespaces, remote-control state)
​
MOUNT_ALLOWLIST_PATH
string
~/.config/nanoclaw/mount-allowlist.json - Mount security allowlist (never mounted into containers)
​
SENDER_ALLOWLIST_PATH
string
~/.config/nanoclaw/sender-allowlist.json - Sender-based access control. JSON file with a default entry and optional per-chat overrides in chats. Each entry specifies allow ("*" or array of sender JIDs) and mode ("trigger" to store but block activation, or "drop" to discard silently). Reloaded on every message cycle. See security overview.

​
Trigger pattern

The trigger pattern is generated from ASSISTANT_NAME: 
export const TRIGGER_PATTERN = new RegExp(
  `^@${escapeRegex(ASSISTANT_NAME)}\\b`,
  'i',
);
Matches messages starting with @{ASSISTANT_NAME} (case-insensitive).

​
Timezone configuration

Scheduled tasks use the configured timezone: 
export const TIMEZONE =
  process.env.TZ || Intl.DateTimeFormat().resolvedOptions().timeZone;
This affects cron expression evaluation for scheduled tasks.

​
Example .env file

ASSISTANT_NAME=Andy
ASSISTANT_HAS_OWN_NUMBER=false
CONTAINER_TIMEOUT=1800000
MAX_CONCURRENT_CONTAINERS=5
TZ=America/Los_Angeles
ONECLI_URL=http://127.0.0.1:10254
With the OneCLI gateway, API keys and OAuth tokens are no longer stored in .env. Secrets are managed via onecli secrets create and injected by the gateway at request time. The only credential-related variable is ONECLI_URL.

​
Credential environment variables

Credentials are managed externally via OneCLI — no credential environment variables are needed in .env.Register secrets with OneCLI using the CLI or dashboard:
onecli secrets create --name Anthropic --type anthropic --value YOUR_KEY --host-pattern api.anthropic.com
See onecli secrets list to verify registered secrets. Run onecli --help for the full list of available commands.
​
OLLAMA_HOST
string
default:"http://host.docker.internal:11434"
Ollama API endpoint. Only used when the /add-ollama-tool skill is installed. The MCP server inside the container uses this to reach the host’s Ollama instance. Falls back to localhost if host.docker.internal fails.

​
Security notes

  • Secrets are never read by NanoClaw — OneCLI manages them externally
  • The OneCLI gateway injects credentials into container API traffic at request time
  • Containers cannot extract real credentials from the gateway
  • Mount allowlist is stored OUTSIDE project root and never mounted into containers
Last modified on March 24, 2026