Skip to content

configuration.md

Latest commit

 

History

History
146 lines (103 loc) · 9.65 KB

configuration.md

File metadata and controls

146 lines (103 loc) · 9.65 KB
Raw

English | 中文

Configuration Reference

Dr. Claw is configured through environment variables in a .env file at the project root. This guide documents every variable the application reads.

How .env Loading Works

  1. Backend — server/load-env.js reads .env line-by-line on startup and sets any key not already present in process.env. System environment variables always take precedence.
  2. Frontend — Vite loads .env automatically. Only variables prefixed with VITE_ are exposed to browser code.
  3. Precedence — System env > .env file values.

Quick start: cp .env.example .env gives you sensible defaults. See the Quickstart guide for a step-by-step walkthrough.

Configuration Reference

Server

Variable Required Default Description
PORT No 3001 Express API + WebSocket server port.
VITE_PORT No 5173 Vite dev server port (development only).
CLAUDE_CLI_PATH No claude Absolute or relative path to the Claude Code binary. Override if claude is not on your PATH.
CURSOR_CLI_PATH No Auto-detect (cursor-agent then agent) Override Cursor CLI command/binary. Useful when your environment only provides one alias.
GEMINI_CLI_PATH No gemini Override Gemini CLI command/binary. Useful when your shell resolves Gemini through a custom alias or path.
CODEX_CLI_PATH No codex Override Codex CLI command/binary. Useful when Codex is installed outside your default PATH.

Database

Variable Required Default Description
DATABASE_PATH No server/database/auth.db Absolute path to the SQLite database file. The directory is created automatically if it does not exist.

Authentication

These variables are security-sensitive. See the Security Checklist below.

Variable Required Default Description
JWT_SECRET No (auto-generated, see below) Secret used to sign and verify JWT tokens. When unset, Dr. Claw generates a random 256-bit secret on first start and stores it in a jwt-secret file next to the database (DATABASE_PATH, mode 0600). Set it explicitly when several instances must accept each other's tokens or when you manage secrets externally. Generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))". The former public default claude-ui-dev-secret-change-in-production is rejected at startup.
JWT_SECRET_FILE No <database dir>/jwt-secret Path to a file containing the JWT secret. Used only when JWT_SECRET is unset. Created with a random value if it does not exist. Handy for Docker/Kubernetes secrets, e.g. /run/secrets/jwt-secret.
API_KEY No (none — validation skipped) When set, every HTTP request must include an X-Api-Key header with this value. Useful for restricting access in hosted setups.

Context Window

Variable Required Default Description
CONTEXT_WINDOW No 160000 Maximum token context window sent to the backend CLI process.
VITE_CONTEXT_WINDOW No 160000 Same value exposed to the frontend (must match CONTEXT_WINDOW).

Platform Mode

Platform mode is an advanced deployment option. Most users should leave these commented out.

Variable Required Default Description
VITE_IS_PLATFORM No false Set to true to enable Platform mode. In this mode JWT authentication is bypassed and the first database user is used for all requests.
WORKSPACES_ROOT No User home directory (os.homedir()) Root directory where Dr. Claw looks for and creates project workspaces. Only meaningful when VITE_IS_PLATFORM=true.

Integrations

Variable Required Default Description
OPENAI_API_KEY No (none) OpenAI API key for Codex integration. Required only if you use the Codex CLI backend.

Advanced

Variable Required Default Description
CLAUDE_TOOL_APPROVAL_TIMEOUT_MS No 55000 Timeout in milliseconds for Claude tool-approval prompts before auto-declining.

Model Discovery

Dr. Claw asks each harness which models it actually supports rather than relying only on the list compiled into the app, so a CLI that ships a new model shows up without waiting for a Dr. Claw release.

Provider Source Notes
Claude Agent SDK supportedModels() control request The menu the bundled Claude Code CLI serves (e.g. default, opus[1m], sonnet), so it tracks the SDK version Dr. Claw ships. The model configured in ~/.claude/settings.json (or CLAUDE_CONFIG_DIR, or ANTHROPIC_MODEL) is added the way the CLI's own /model menu adds it. The CLI also accepts ids it does not list, so built-in entries are kept without a deprecated marker. No tokens are consumed and settings/hooks are not loaded during the probe.
Codex codex app-server → model/list JSON-RPC Same catalogue the Codex CLI's own picker reads, including each model's supported reasoning efforts, which drive the reasoning-effort selector. Honours CODEX_CLI_PATH.
Gemini GET https://generativelanguage.googleapis.com/v1beta/models The Gemini CLI has no model-listing command, so the catalogue comes from the Gemini API using the caller's API key (saved in Settings, else GEMINI_API_KEY / GOOGLE_API_KEY). Non-chat models (TTS, image, music, embeddings, …) are filtered out. Without a key the built-in list is used. Thinking-mode support for a model the table has not seen falls back to its family (Gemini 3: levels, Gemini 2.5: budgets). Note: since 2026-06-18 the Gemini CLI no longer serves individual Google (OAuth) accounts; an API key is required, and Dr. Claw selects API-key auth for the CLI whenever one is configured.
OpenRouter GET https://openrouter.ai/api/v1/models Public endpoint, no key needed.
Cursor, Nano Built-in list These CLIs expose no model-listing command today.
Local GPU Ollama /api/tags Existing behaviour, unchanged.

Discovery is strictly additive and never blocks the UI:

  • Results are cached for 10 minutes; a failed probe is re-tried after 1 minute so the picker recovers on its own once a CLI is installed or logged in.
  • Every probe has a 15-second hard timeout. If the harness is missing, old, logged out, or unresponsive, the built-in list is used instead.
  • Built-in entries the harness did not report are still returned by the API, flagged builtIn: true (and deprecated: true where the harness would reject them), so an existing saved model preference is never stranded. Once the harness has answered, the picker shows only what the harness reported (plus the currently selected value): the built-in table is a fallback for when discovery is unavailable, not a second list, so one model does not appear under two names (claude-fable-5 next to the CLI's claude-fable-5[1m]).

API

Endpoint Description
GET /api/models/:provider Model list for a provider. source is discovered or static. Add ?refresh=1 to bypass the cache.
POST /api/models/:provider/refresh Drop the cache and re-probe — useful right after upgrading or logging into a CLI.
GET /api/models/providers Providers this build can probe.

OSS Mode vs Platform Mode

Dr. Claw supports two authentication paths:

OSS Mode (default) Platform Mode
Who uses it Individual developers running Dr. Claw locally Hosted / multi-tenant deployments
Auth flow Register/login with username + password; JWT issued per session JWT auth bypassed; first DB user auto-selected
Enable Default — no extra config needed Set VITE_IS_PLATFORM=true
WORKSPACES_ROOT Ignored Defines the root directory for all project workspaces

In OSS mode the WORKSPACES_ROOT variable is ignored — Dr. Claw discovers projects from Claude Code / Cursor / Codex session directories under the user's home folder.

Security Checklist

Before deploying Dr. Claw on a network (not just localhost), review the following:

  1. JWT_SECRET — Either set a strong random string or rely on the auto-generated jwt-secret file. Back that file up with the database: losing it signs every user out; leaking it lets anyone forge tokens. The historical default is no longer accepted.
  2. API_KEY — Consider setting an API key to add an extra authentication layer.
  3. WORKSPACES_ROOT — In Platform mode, ensure this is scoped to a directory you trust. Dr. Claw serves file contents from this tree.
  4. .gitignore — Verify that .env is listed in .gitignore (it is by default) so secrets are never committed.
  5. HTTPS — When exposing Dr. Claw to the internet, place it behind a reverse proxy (e.g. Nginx, Caddy) with TLS termination.

Troubleshooting

  • Variable not taking effect? Check that there is no system environment variable with the same name overriding it.
  • Database errors? See FAQ — SQLITE_CANTOPEN.
  • Server refuses to start with Refusing to start: the JWT secret ... is the publicly known development default? Remove that value from .env (or from the secret file) and let Dr. Claw generate a new one, or set a fresh random JWT_SECRET. Existing logins will need to sign in again.