{"id":45736352,"url":"https://github.com/nickalie/nclaw","last_synced_at":"2026-02-27T14:23:57.200Z","repository":{"id":340532970,"uuid":"1160841485","full_name":"nickalie/nclaw","owner":"nickalie","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-25T10:48:50.000Z","size":224,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T13:49:10.813Z","etag":null,"topics":["ai-assistant","claude","claude-code","docker","golang","kubernetes","telegram"],"latest_commit_sha":null,"homepage":"https://nclaw.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickalie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-18T12:41:45.000Z","updated_at":"2026-02-25T10:43:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nickalie/nclaw","commit_stats":null,"previous_names":["nickalie/nclaw"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/nickalie/nclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickalie%2Fnclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickalie%2Fnclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickalie%2Fnclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickalie%2Fnclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickalie","download_url":"https://codeload.github.com/nickalie/nclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickalie%2Fnclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29899650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T12:09:13.686Z","status":"ssl_error","status_checked_at":"2026-02-27T12:09:13.282Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","claude","claude-code","docker","golang","kubernetes","telegram"],"created_at":"2026-02-25T11:16:39.698Z","updated_at":"2026-02-27T14:23:57.188Z","avatar_url":"https://github.com/nickalie.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nclaw\n\n**N**Claw — a**N**other Claw. A lightweight, container-first AI coding assistant accessible through Telegram. Supports Claude Code (default), 580+ models via multi-model backend (OpenRouter, Gemini, OpenAI, Ollama, and more), OpenAI Codex, GitHub Copilot, and Google Gemini CLI as CLI agents. Written in Go.\n\n## Table of Contents\n\n- [Why NClaw](#why-nclaw)\n- [How It Works](#how-it-works)\n- [Features](#features)\n- [Quickstart](#quickstart)\n  - [Step 1: Create a Telegram Bot](#step-1-create-a-telegram-bot)\n  - [Step 2: Find Your Chat ID](#step-2-find-your-chat-id)\n  - [Step 3: Run NClaw](#step-3-run-nclaw)\n- [Docker](#docker)\n- [Multi-Model](#multi-model-1)\n- [Kubernetes (Helm)](#kubernetes-helm)\n- [Running without Docker](#running-without-docker)\n  - [Installation](#installation)\n  - [Usage](#usage)\n- [Configuration](#configuration)\n  - [Environment variables](#environment-variables)\n  - [Config file](#config-file)\n- [Scheduling](#scheduling)\n- [Webhooks](#webhooks)\n- [Skills](#skills)\n- [GitOps Deployment](#gitops-deployment)\n  - [FluxCD](#fluxcd)\n  - [ArgoCD](#argocd)\n- [Development](#development)\n- [License](#license)\n\n## Why NClaw\n\nThere are many AI assistants already — [OpenClaw](https://openclaw.ai/), [NanoClaw](https://github.com/qwibitai/nanoclaw), [ClaudeClaw](https://github.com/moazbuilds/claudeclaw), and others. NClaw exists because none of them satisfied three requirements at once:\n\n**Container-first.** NClaw is built to run in Docker and Kubernetes from day one. The repo ships a multi-stage Dockerfile and a Helm chart. No manual setup, no runtime dependency resolution — `docker run` or `helm install` and you're done.\n\n**Lightweight.** A single Go binary. Idles at ~10 MB of RAM. No runtime interpreter, no package manager overhead, no garbage collection pauses that matter.\n\n**Telegram topics as projects.** NClaw treats each Telegram topic (thread) as a separate session with its own working directory. One group chat with topics becomes a multi-project workspace — each topic gets isolated context, history, and files.\n\n## How It Works\n\nYou message the assistant through Telegram. It invokes the configured CLI agent (Claude Code by default), preserving conversation history per chat/topic, and sends back the response.\n\n```\nTelegram  -\\\nScheduler --\u003e  CLI Backend  --\u003e  Telegram\nWebhook   -/\n```\n\nThe recommended way to run NClaw is inside Docker — the container serves as a security sandbox, and the image ships with all the tools the assistant might need. However, NClaw is a regular executable and can run directly on any machine with the chosen CLI agent installed.\n\n## Features\n\n- **Session persistence** — Each chat/topic maintains its own session. Pick up where you left off.\n- **Telegram topics** — Each topic in a group chat is a separate project with isolated context and files.\n- **File attachments** — Send photos, documents, audio, video to the assistant.\n- **File delivery** — The assistant can send files back to you (generated reports, exports, code).\n- **Scheduled tasks** — Create recurring or one-time jobs using natural language.\n- **Webhooks** — Register HTTP endpoints that forward incoming requests to the assistant in your chat.\n- **Rich runtime** — Docker image includes git, gh CLI, Chromium, Go, Node.js, Python/uv. The assistant can install additional packages on the fly as needed — for example, `apk add ffmpeg` to process video, `npm install -g prettier` to format code, or `pip install pandas` to analyze data.\n- **Multiple CLI agents** — Supports Claude Code (default), multi-model (580+ models via OpenRouter, Gemini, OpenAI, Ollama, etc.), OpenAI Codex, GitHub Copilot, and Google Gemini CLI. Switch agents via the `NCLAW_CLI` environment variable.\n- **HTML-formatted replies** — Responses render using Telegram's HTML formatting with plain-text fallback.\n\n## Quickstart\n\nGet NClaw running in under 5 minutes using Docker.\n\n### Step 1: Create a Telegram Bot\n\n1. Open Telegram and search for **@BotFather** (or open [t.me/BotFather](https://t.me/BotFather)).\n2. Send `/newbot`.\n3. Choose a **display name** for your bot (e.g. \"My Coding Assistant\").\n4. Choose a **username** — must end in `bot` (e.g. `my_coding_assistant_bot`).\n5. BotFather replies with your **bot token** — a string like `123456789:ABCdefGhIjKlMnOpQrStUvWxYz`. Save it.\n\n\u003e **Tip:** You can customize the bot later — send `/mybots` to BotFather to change the name, description, profile picture, and more.\n\nIf you want the bot in a **group with topics** (one topic per project), also configure these via BotFather:\n\n6. Send `/mybots` → select your bot → **Bot Settings** → **Group Privacy** → **Turn off**. This lets the bot read all messages in group chats, not just commands.\n7. Send `/setjoingroups` → select your bot → **Enable**. This allows adding the bot to groups.\n\n### Step 2: Find Your Chat ID\n\nNClaw uses `NCLAW_TELEGRAM_WHITELIST_CHAT_IDS` to restrict which chats the bot responds in. This setting is optional, but **strongly recommended** — without it, anyone who discovers your bot can send it commands with full access to the container's file system, shell, and network. You need the numeric chat ID.\n\n**For a private chat (1-on-1 with the bot):**\n\n1. Message your bot (send anything — it won't reply yet).\n2. Open this URL in a browser, replacing `\u003cTOKEN\u003e` with your bot token:\n   ```\n   https://api.telegram.org/bot\u003cTOKEN\u003e/getUpdates\n   ```\n3. Find `\"chat\":{\"id\":123456789}` in the JSON response. That number is your chat ID.\n\n**For a group chat:**\n\n1. Add the bot to the group.\n2. Send a message in the group.\n3. Use the same `getUpdates` URL above. The group chat ID is a **negative number** (e.g. `-1001234567890`).\n\n\u003e **Tip:** You can whitelist multiple chat IDs by separating them with commas: `123456789,-1001234567890`.\n\n### Step 3: Run NClaw\n\nThe fastest way to get started is with the **multi-model** image using a free Gemini API key:\n\n1. Get a free API key from [Google AI Studio](https://aistudio.google.com/apikey).\n\n2. Run:\n   ```bash\n   docker run -d --name nclaw \\\n     -e NCLAW_TELEGRAM_BOT_TOKEN=your-bot-token \\\n     -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n     -e NCLAW_DATA_DIR=/app/data \\\n     -e NCLAW_MODEL=g@gemini-2.5-pro \\\n     -e GEMINI_API_KEY=your-gemini-key \\\n     -v ./data:/app/data \\\n     ghcr.io/nickalie/nclaw:multi-model\n   ```\n\n3. Message your bot in Telegram — it should reply.\n\nTo use **Claude Code** instead (requires an Anthropic account with Claude Code access):\n\n1. Install Claude Code and authenticate:\n   ```bash\n   curl -fsSL https://claude.ai/install.sh | bash\n   claude login\n   ```\n\n2. Run:\n   ```bash\n   docker run -d --name nclaw \\\n     -e NCLAW_TELEGRAM_BOT_TOKEN=your-bot-token \\\n     -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n     -e NCLAW_DATA_DIR=/app/data \\\n     -v ./data:/app/data \\\n     -v ~/.claude/.credentials.json:/root/.claude/.credentials.json:ro \\\n     ghcr.io/nickalie/nclaw:claude\n   ```\n\nSee [Docker](#docker) for all image variants and [Configuration](#configuration) for the full list of options.\n\n## Docker\n\nNClaw provides six Docker images, all based on `node:24-alpine` with shared tools (git, gh CLI, Chromium, Go, Node.js, Python/uv, skills). They differ only in which CLI agent is pre-installed:\n\n| Image | Tag | CLI Backends | Size |\n|---|---|---|---|\n| **All-in-one** | `latest` | Claude Code + Multi-Model + Codex + Copilot + Gemini | Largest |\n| **Claude** | `claude` | Claude Code | Medium |\n| **Multi-Model** | `multi-model` | Claude Code + Multi-Model | Medium |\n| **Codex** | `codex` | OpenAI Codex | Medium |\n| **Copilot** | `copilot` | GitHub Copilot | Medium |\n| **Gemini** | `gemini` | Google Gemini CLI | Medium |\n\nAll images are published to `ghcr.io/nickalie/nclaw` and built for **linux/amd64** and **linux/arm64**. Docker automatically pulls the correct architecture — no extra flags needed. This means you can run NClaw on:\n\n- **Raspberry Pi** (4/5 or any arm64 board) — a dedicated AI coding assistant on a $35 device\n- **AWS Graviton** instances — lower cost and better price-performance than x86\n- **Apple Silicon** Macs — native arm64 without Rosetta emulation\n- **Oracle Cloud Ampere** or any other arm64 cloud VM\n\nThe assistant can install additional packages at runtime (e.g. `apk add ffmpeg`, `pip install pandas`, `npm install -g typescript`).\n\n### Claude (default)\n\n```bash\ndocker run -d --name nclaw \\\n  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \\\n  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n  -e NCLAW_DATA_DIR=/app/data \\\n  -v ./data:/app/data \\\n  -v ~/.claude/.credentials.json:/root/.claude/.credentials.json:ro \\\n  ghcr.io/nickalie/nclaw:claude\n```\n\nClaude Code uses OAuth authentication. Mount your credentials file from `~/.claude/.credentials.json`. To obtain credentials, install Claude Code locally and run `claude login`.\n\n### Multi-Model\n\n```bash\ndocker run -d --name nclaw \\\n  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \\\n  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n  -e NCLAW_DATA_DIR=/app/data \\\n  -e NCLAW_MODEL=g@gemini-2.5-pro \\\n  -e GEMINI_API_KEY=your-gemini-key \\\n  -v ./data:/app/data \\\n  ghcr.io/nickalie/nclaw:multi-model\n```\n\n```bash\ndocker run -d --name nclaw \\\n  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \\\n  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n  -e NCLAW_DATA_DIR=/app/data \\\n  -e NCLAW_MODEL=zai@glm-4 \\\n  -e ZAI_API_KEY=your-zai-key \\\n  -v ./data:/app/data \\\n  ghcr.io/nickalie/nclaw:multi-model\n```\n\nSetting `NCLAW_MODEL` automatically selects the multi-model backend. No Anthropic credentials are needed — only an API key from your chosen provider. See [Multi-Model](#multi-model-1) for full configuration details.\n\n### Codex\n\n```bash\ndocker run -d --name nclaw \\\n  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \\\n  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n  -e NCLAW_DATA_DIR=/app/data \\\n  -e NCLAW_CLI=codex \\\n  -v ./data:/app/data \\\n  -v ~/.codex/auth.json:/root/.codex/auth.json:ro \\\n  ghcr.io/nickalie/nclaw:codex\n```\n\nCodex uses ChatGPT OAuth authentication. Mount your auth file from `~/.codex/auth.json`. To obtain credentials, install Codex locally (`npm install -g @openai/codex`) and sign in on first run.\n\n### Copilot\n\n```bash\ndocker run -d --name nclaw \\\n  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \\\n  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n  -e NCLAW_DATA_DIR=/app/data \\\n  -e NCLAW_CLI=copilot \\\n  -v ./data:/app/data \\\n  -v ~/.copilot/config.json:/root/.copilot/config.json:ro \\\n  ghcr.io/nickalie/nclaw:copilot\n```\n\nCopilot uses GitHub OAuth authentication. Mount your config file from `~/.copilot/config.json`. To obtain credentials, install Copilot CLI locally (`npm install -g @githubnext/github-copilot-cli`) and run `/login`.\n\n### Gemini\n\n```bash\ndocker run -d --name nclaw \\\n  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \\\n  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n  -e NCLAW_DATA_DIR=/app/data \\\n  -e NCLAW_CLI=gemini \\\n  -v ./data:/app/data \\\n  -v ~/.gemini/oauth_creds.json:/root/.gemini/oauth_creds.json:ro \\\n  ghcr.io/nickalie/nclaw:gemini\n```\n\nGemini CLI uses Google account OAuth authentication. Mount your credentials file from `~/.gemini/oauth_creds.json`. To obtain credentials, install Gemini CLI locally (`npm install -g @google/gemini-cli`) and sign in on first run.\n\n### All-in-one\n\n```bash\ndocker run -d --name nclaw \\\n  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \\\n  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n  -e NCLAW_DATA_DIR=/app/data \\\n  -v ./data:/app/data \\\n  -v ~/.claude/.credentials.json:/root/.claude/.credentials.json:ro \\\n  ghcr.io/nickalie/nclaw:latest\n```\n\nThe all-in-one image includes all five CLI agents. Set `NCLAW_CLI` to `claude` (default), `claudish` (multi-model), `codex`, `copilot`, or `gemini` to choose the agent. Mount the appropriate credentials for your chosen agent.\n\n### Webhooks\n\nTo enable [webhooks](#webhooks), add the webhook base domain and expose the port:\n\n```bash\ndocker run -d --name nclaw \\\n  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \\\n  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n  -e NCLAW_DATA_DIR=/app/data \\\n  -e NCLAW_WEBHOOK_BASE_DOMAIN=example.com \\\n  -e NCLAW_WEBHOOK_PORT=:3000 \\\n  -p 3000:3000 \\\n  -v ./data:/app/data \\\n  -v ~/.claude/.credentials.json:/root/.claude/.credentials.json:ro \\\n  ghcr.io/nickalie/nclaw:latest\n```\n\n## Multi-Model\n\nNClaw's multi-model backend (powered by [claudish](https://github.com/MadAppGang/claudish)) lets you use 580+ models from OpenRouter, Google Gemini, OpenAI, Vertex AI, Ollama, LM Studio, and more — while retaining full agentic capabilities (tool use, file editing, scheduled tasks, webhooks, file delivery).\n\n### Supported Providers\n\n| Provider | Prefix | Example | Auth |\n|---|---|---|---|\n| **OpenRouter** | `or@` | `or@deepseek/deepseek-r1` | `OPENROUTER_API_KEY` |\n| **Google Gemini** | `g@` | `g@gemini-2.0-flash` | `GEMINI_API_KEY` |\n| **OpenAI** | `oai@` | `oai@o3-mini` | `OPENAI_API_KEY` |\n| **Vertex AI** | `v@` | `v@gemini-2.5-flash` | `VERTEX_API_KEY` |\n| **OllamaCloud** | `oc@` | `oc@llama-3.1-70b` | `OLLAMA_API_KEY` |\n| **Kimi** | `kimi@` | `kimi@kimi-k2` | `MOONSHOT_API_KEY` |\n| **GLM (Zhipu)** | `glm@` | `glm@glm-4` | `ZHIPU_API_KEY` |\n| **Z.AI** | `zai@` | `zai@glm-4` | `ZAI_API_KEY` |\n| **MiniMax** | `mm@` | `mm@MiniMax-M2.1` | `MINIMAX_API_KEY` |\n| **Poe** | `poe@` | `poe@GPT-4o` | `POE_API_KEY` |\n| **OpenCode Zen** | `zen@` | `zen@grok-code` | Free (no key) |\n| **Gemini CodeAssist** | `go@` | `go@gemini-2.5-flash` | OAuth |\n| **Ollama** | `ollama@` | `ollama@llama3.2` | Local (no key) |\n| **LM Studio** | `lms@` | `lms@qwen2.5-coder` | Local (no key) |\n| **vLLM** | `vllm@` | `vllm@mistral-7b` | Local (no key) |\n| **MLX** | `mlx@` | `mlx@llama-3.2-3b` | Local (no key) |\n\nWell-known model names (e.g. `gemini-2.0-flash`, `llama-3.1-70b`) are auto-detected without a provider prefix.\n\n### Model Selection\n\nSet `NCLAW_MODEL` to choose the default model. This automatically selects the multi-model backend — no need to set `NCLAW_CLI` explicitly:\n\n```bash\n# Use Gemini via direct API\ndocker run -d --name nclaw \\\n  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \\\n  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n  -e NCLAW_DATA_DIR=/app/data \\\n  -e NCLAW_MODEL=g@gemini-2.5-pro \\\n  -e GEMINI_API_KEY=your-key \\\n  -v ./data:/app/data \\\n  ghcr.io/nickalie/nclaw:multi-model\n\n# Use GLM-4 via Z.AI\ndocker run -d --name nclaw \\\n  -e NCLAW_MODEL=zai@glm-4 \\\n  -e ZAI_API_KEY=your-key \\\n  ...\n\n# Use any model via OpenRouter\ndocker run -d --name nclaw \\\n  -e NCLAW_MODEL=or@mistralai/mistral-large \\\n  -e OPENROUTER_API_KEY=your-key \\\n  ...\n\n# Use a local model via Ollama\ndocker run -d --name nclaw \\\n  -e NCLAW_MODEL=ollama@llama3.2 \\\n  ...\n```\n\n### Local Models\n\nFor fully offline operation, use Ollama or LM Studio. Your code never leaves your machine:\n\n```bash\n# Start Ollama and pull a model\nollama pull llama3.2\n\n# Run nclaw with a local model\ndocker run -d --name nclaw \\\n  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \\\n  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \\\n  -e NCLAW_DATA_DIR=/app/data \\\n  -e NCLAW_MODEL=ollama@llama3.2 \\\n  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \\\n  -v ./data:/app/data \\\n  ghcr.io/nickalie/nclaw:multi-model\n```\n\nSet `OLLAMA_BASE_URL`, `LMSTUDIO_BASE_URL`, `VLLM_BASE_URL`, or `MLX_BASE_URL` to connect to custom endpoints.\n\n## Kubernetes (Helm)\n\nThe Helm chart is published as an OCI artifact to GHCR. Since all Docker images are multi-arch (amd64/arm64), the chart works on mixed-architecture clusters — including AWS Graviton node pools, Raspberry Pi k3s clusters, and Apple Silicon dev machines.\n\n```bash\nhelm install nclaw oci://ghcr.io/nickalie/charts/nclaw \\\n  --set env.telegramBotToken=your-token \\\n  --set env.whitelistChatIds=your-chat-id \\\n  --set claudeCredentialsSecret=my-claude-secret\n```\n\nCreate the credentials secret for your chosen agent:\n\n```bash\n# Claude\nkubectl create secret generic my-claude-secret \\\n  --from-file=credentials.json=$HOME/.claude/.credentials.json\n\n# Codex\nkubectl create secret generic my-codex-secret \\\n  --from-file=auth.json=$HOME/.codex/auth.json\n\n# Copilot\nkubectl create secret generic my-copilot-secret \\\n  --from-file=config.json=$HOME/.copilot/config.json\n\n# Gemini\nkubectl create secret generic my-gemini-secret \\\n  --from-file=oauth_creds.json=$HOME/.gemini/oauth_creds.json\n```\n\n### Helm values\n\n| Parameter | Default | Description |\n|---|---|---|\n| `image.repository` | `ghcr.io/nickalie/nclaw` | Docker image |\n| `image.tag` | Chart appVersion | Image tag |\n| `env.dataDir` | `/app/data` | Data directory inside container |\n| `env.telegramBotToken` | `\"\"` | Telegram bot token |\n| `env.whitelistChatIds` | `\"\"` | Comma-separated allowed chat IDs |\n| `env.webhookBaseDomain` | `\"\"` | Base domain for webhook URLs |\n| `env.cli` | `\"\"` | CLI agent: `claude`, `claudish` (multi-model), `codex`, `copilot`, or `gemini` (empty = image default) |\n| `env.model` | `\"\"` | Model for multi-model backend (e.g. `g@gemini-2.5-pro`). Setting this auto-selects multi-model |\n| `existingSecret` | `\"\"` | Use existing secret for bot token (key: `telegram-bot-token`) |\n| `claudeCredentialsSecret` | `\"\"` | Secret with Claude credentials (key: `credentials.json`) |\n| `codexCredentialsSecret` | `\"\"` | Secret with Codex credentials (key: `auth.json`) |\n| `copilotCredentialsSecret` | `\"\"` | Secret with Copilot credentials (key: `config.json`) |\n| `geminiCredentialsSecret` | `\"\"` | Secret with Gemini credentials (key: `oauth_creds.json`) |\n| `persistence.enabled` | `true` | Enable persistent storage |\n| `persistence.size` | `1Gi` | PVC size |\n| `persistence.storageClass` | `\"\"` | Storage class |\n| `persistence.existingClaim` | `\"\"` | Use existing PVC |\n| `rbac.create` | `true` | Create ServiceAccount and ClusterRoleBinding |\n| `rbac.clusterRole` | `cluster-admin` | ClusterRole to bind |\n| `proxy.enabled` | `false` | Enable HTTP proxy |\n| `proxy.httpProxy` | `\"\"` | HTTP_PROXY value |\n| `proxy.httpsProxy` | `\"\"` | HTTPS_PROXY value |\n| `resources.requests.cpu` | `100m` | CPU request |\n| `resources.requests.memory` | `128Mi` | Memory request |\n| `resources.limits.cpu` | `1000m` | CPU limit |\n| `resources.limits.memory` | `2Gi` | Memory limit |\n\n## Running without Docker\n\nNClaw is a regular executable and can run directly on any machine. The only runtime dependency is the CLI for your chosen agent — [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (default), [claudish](https://github.com/MadAppGang/claudish) (multi-model), [OpenAI Codex](https://github.com/openai/codex), [GitHub Copilot](https://docs.github.com/en/copilot/github-copilot-in-the-cli), or [Gemini CLI](https://github.com/google-gemini/gemini-cli) — it must be installed and available in `PATH`.\n\n\u003e **Security notice:** Without Docker, the CLI agent runs directly on the host with the same permissions as the nclaw process. It has full access to the file system, network, and any credentials available to the user. Run under a dedicated unprivileged user and avoid running as root. For production use, Docker or Kubernetes deployment is strongly recommended.\n\n### Installation\n\n#### Homebrew (macOS/Linux)\n\n```bash\nbrew install --cask nickalie/apps/nclaw\n```\n\n#### Scoop (Windows)\n\n```powershell\nscoop bucket add nickalie https://github.com/nickalie/scoop-bucket\nscoop install nclaw\n```\n\n#### Chocolatey (Windows)\n\n```powershell\nchoco install nclaw\n```\n\n#### Winget (Windows)\n\n```powershell\nwinget install nickalie.nclaw\n```\n\n#### AUR (Arch Linux)\n\n```bash\nyay -S nclaw-bin\n```\n\n#### DEB / RPM / APK\n\nDownload the appropriate package from the [Releases](https://github.com/nickalie/nclaw/releases) page:\n\n```bash\n# Debian/Ubuntu\nsudo dpkg -i nclaw_*.deb\n\n# Fedora/RHEL\nsudo rpm -i nclaw_*.rpm\n\n# Alpine\nsudo apk add --allow-untrusted nclaw_*.apk\n```\n\n#### Binary download\n\nPre-built binaries for Linux, macOS, and Windows (amd64/arm64) are available on the [Releases](https://github.com/nickalie/nclaw/releases) page.\n\n#### Go install\n\n```bash\nCGO_ENABLED=1 go install github.com/nickalie/nclaw/cmd/nclaw@latest\n```\n\nRequires Go 1.25+ and a C compiler (CGO is needed for SQLite).\n\n### Usage\n\n1. Install Claude Code CLI and authenticate:\n   ```bash\n   curl -fsSL https://claude.ai/install.sh | bash\n   claude login\n   ```\n2. Create a `.env` file or export environment variables:\n   ```bash\n   export NCLAW_TELEGRAM_BOT_TOKEN=your-token\n   export NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id\n   export NCLAW_DATA_DIR=./data\n   ```\n3. Run:\n   ```bash\n   nclaw\n   ```\n\nAny tools you want the assistant to use (git, gh, python, etc.) should be installed on the host. The assistant will use whatever is available in the system `PATH`.\n\n## Configuration\n\nNClaw reads configuration from environment variables, `.env` files, or YAML config files.\n\n### Environment variables\n\nNClaw variables use the `NCLAW_` prefix. Provider API keys use the provider's native env var name (no prefix) — they pass through to the multi-model backend automatically.\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `NCLAW_TELEGRAM_BOT_TOKEN` | Yes | — | Telegram bot token from [@BotFather](https://t.me/BotFather) |\n| `NCLAW_DATA_DIR` | Yes | — | Base directory for session data and files |\n| `NCLAW_CLI` | No | `claude` | CLI agent: `claude`, `claudish` (multi-model), `codex`, `copilot`, or `gemini`. Auto-selects `claudish` when `NCLAW_MODEL` is set |\n| `NCLAW_MODEL` | No | — | Model for multi-model backend (e.g. `g@gemini-2.5-pro`). Setting this auto-selects multi-model |\n| `NCLAW_TELEGRAM_WHITELIST_CHAT_IDS` | No | — | Comma-separated list of allowed Telegram chat IDs. If unset, accepts all chats (with a security warning) |\n| `NCLAW_DB_PATH` | No | `{data_dir}/nclaw.db` | Path to the SQLite database |\n| `NCLAW_TIMEZONE` | No | system local | Timezone for the scheduler (e.g. `Europe/Berlin`) |\n| `NCLAW_WEBHOOK_BASE_DOMAIN` | No | — | Base domain for webhook URLs (required when using webhooks) |\n| `NCLAW_WEBHOOK_PORT` | No | `:3000` | Webhook HTTP server listen address |\n\n\u003e **Security notice:** If `NCLAW_TELEGRAM_WHITELIST_CHAT_IDS` is not set, the assistant will accept messages from **any** Telegram chat. Since NClaw runs the CLI agent 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.\n\n### Config file\n\nNClaw 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`).\n\n```yaml\ntelegram:\n  bot_token: \"your-telegram-bot-token\"\n  whitelist_chat_ids: \"123456789,987654321\"\n\ncli: \"claude\"  # Options: claude, claudish, codex, copilot, gemini\ndata_dir: \"/app/data\"\ndb_path: \"/app/data/nclaw.db\"\ntimezone: \"Europe/Berlin\"\n\n# Multi-model settings (setting model auto-selects multi-model backend)\nmodel: \"\"                  # e.g. \"g@gemini-2.5-pro\", \"or@mistralai/mistral-large\"\n# Provider API keys are set as regular env vars (not in this file):\n# OPENROUTER_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, etc.\n\nwebhook:\n  base_domain: \"example.com\"\n  port: \":3000\"\n```\n\n## Scheduling\n\nTalk naturally to create scheduled tasks:\n\n```\nRemind me to take a break every 2 hours\nEvery morning at 8am, give me a weather summary and top news headlines\nAt 3pm today, generate a summary of today's git commits\n```\n\nTasks persist across restarts. Each task can either continue the existing chat session or run in a fresh isolated context.\n\n## Webhooks\n\nRegister HTTP endpoints that forward incoming requests to the assistant:\n\n```\nCreate a webhook that receives GitHub push events and summarizes the changes\nSet up a webhook for my package tracking updates\nListen for smart home alerts and notify me about unusual activity\n```\n\nWhen an external service calls the webhook URL, the request (method, headers, query params, body) is forwarded to the assistant in the originating chat. The HTTP endpoint returns 200 immediately; the assistant processes the request asynchronously. Webhooks persist across restarts.\n\nRequires `NCLAW_WEBHOOK_BASE_DOMAIN` to be set. Webhook URLs follow the pattern `https://{BASE_DOMAIN}/webhooks/{UUID}`.\n\n## Skills\n\nSix skills ship with nclaw:\n\n| Skill | Source | Purpose |\n|---|---|---|\n| `schedule` | Custom | Create and manage scheduled tasks via natural language |\n| `send-file` | Custom | Send generated files back to the user via Telegram |\n| `webhook` | Custom | Register HTTP endpoints that forward requests to the assistant |\n| `find-skills` | [vercel-labs/skills](https://github.com/vercel-labs/skills) | Discover and install additional agent skills |\n| `skill-creator` | [anthropics/skills](https://github.com/anthropics/skills) | Guide for creating new custom skills |\n| `agent-browser` | [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) | Browse the web using system Chromium |\n\nThe assistant can also create its own skills on the fly when a task requires specialized or repeatable behavior that isn't covered by the built-in set. It can even [learn to produce music](https://nclaw.io/music/).\n\n## GitOps Deployment\n\n### FluxCD\n\n```yaml\napiVersion: source.toolkit.fluxcd.io/v1\nkind: HelmRepository\nmetadata:\n  name: nclaw\n  namespace: flux-system\nspec:\n  type: oci\n  interval: 10m\n  url: oci://ghcr.io/nickalie/charts\n---\napiVersion: helm.toolkit.fluxcd.io/v2\nkind: HelmRelease\nmetadata:\n  name: nclaw\n  namespace: nclaw\nspec:\n  interval: 10m\n  chart:\n    spec:\n      chart: nclaw\n      sourceRef:\n        kind: HelmRepository\n        name: nclaw\n        namespace: flux-system\n  values:\n    env:\n      whitelistChatIds: \"123456789\"\n      webhookBaseDomain: \"example.com\"\n    existingSecret: nclaw-secrets\n    claudeCredentialsSecret: claude-credentials\n    persistence:\n      size: 5Gi\n```\n\n### ArgoCD\n\n```yaml\napiVersion: argoproj.io/v1alpha1\nkind: Application\nmetadata:\n  name: nclaw\n  namespace: argocd\nspec:\n  project: default\n  source:\n    chart: nclaw\n    repoURL: ghcr.io/nickalie/charts\n    targetRevision: \"*\"\n    helm:\n      valuesObject:\n        env:\n          whitelistChatIds: \"123456789\"\n          webhookBaseDomain: \"example.com\"\n        existingSecret: nclaw-secrets\n        claudeCredentialsSecret: claude-credentials\n        persistence:\n          size: 5Gi\n  destination:\n    server: https://kubernetes.default.svc\n    namespace: nclaw\n  syncPolicy:\n    automated:\n      prune: true\n      selfHeal: true\n    syncOptions:\n      - CreateNamespace=true\n```\n\n## Development\n\n```bash\nmake run     # Run locally\nmake lint    # Lint with golangci-lint\nmake test    # Run tests (requires CGO)\nmake docker  # Build and run in Docker\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickalie%2Fnclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickalie%2Fnclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickalie%2Fnclaw/lists"}