Configuration
2 min read
nclaw reads configuration from environment variables, .env files, or YAML config files.
Environment Variables
All variables use the NCLAW_ prefix.
| Variable | Required | Default | Description |
|---|---|---|---|
NCLAW_TELEGRAM_BOT_TOKEN | Yes | — | Telegram bot token from @BotFather |
NCLAW_DATA_DIR | Yes | — | Base directory for session data and files |
NCLAW_TELEGRAM_WHITELIST_CHAT_IDS | No | — | Comma-separated list of allowed Telegram chat IDs. If unset, accepts all chats (with a security warning) |
NCLAW_DB_PATH | No | {data_dir}/nclaw.db | Path to the SQLite database |
NCLAW_TIMEZONE | No | system local | Timezone for the scheduler (e.g. Europe/Berlin) |
NCLAW_WEBHOOK_BASE_DOMAIN | No | — | Base domain for webhook URLs (required when using webhooks) |
NCLAW_WEBHOOK_PORT | No | :3000 | Webhook HTTP server listen address |
Security notice: If
NCLAW_TELEGRAM_WHITELIST_CHAT_IDSis not set, the assistant will accept messages from any Telegram chat. Since nclaw runs Claude Code with full tool access (file system, shell, network), this effectively gives anyone who discovers your bot unrestricted access to the host environment. Always set this variable in production.
Config File
nclaw looks for config.yaml in the current directory or $HOME/.nclaw/. Nested keys map to env vars with underscores (e.g. telegram.bot_token = NCLAW_TELEGRAM_BOT_TOKEN).
telegram:
bot_token: "your-telegram-bot-token"
whitelist_chat_ids: "123456789,987654321"
data_dir: "/app/data"
db_path: "/app/data/nclaw.db"
timezone: "Europe/Berlin"
webhook:
base_domain: "example.com"
port: ":3000"
Example .env
NCLAW_TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=12345678,87654321
NCLAW_DATA_DIR=/data
Helm Values
When deploying with the Helm chart, configuration is passed via Helm values:
| Parameter | Default | Description |
|---|---|---|
image.repository | ghcr.io/nickalie/nclaw | Docker image |
image.tag | Chart appVersion | Image tag |
env.dataDir | /app/data | Data directory inside container |
env.telegramBotToken | "" | Telegram bot token |
env.whitelistChatIds | "" | Comma-separated allowed chat IDs |
env.webhookBaseDomain | "" | Base domain for webhook URLs |
existingSecret | "" | Use existing secret for bot token (key: telegram-bot-token) |
claudeCredentialsSecret | "" | Secret with Claude credentials (key: credentials.json) |
persistence.enabled | true | Enable persistent storage |
persistence.size | 1Gi | PVC size |
persistence.storageClass | "" | Storage class |
persistence.existingClaim | "" | Use existing PVC |
rbac.create | true | Create ServiceAccount and ClusterRoleBinding |
rbac.clusterRole | cluster-admin | ClusterRole to bind |
proxy.enabled | false | Enable HTTP proxy |
proxy.httpProxy | "" | HTTP_PROXY value |
proxy.httpsProxy | "" | HTTPS_PROXY value |
resources.requests.cpu | 100m | CPU request |
resources.requests.memory | 128Mi | Memory request |
resources.limits.cpu | 1000m | CPU limit |
resources.limits.memory | 2Gi | Memory limit |