Configuration

Runtime config model and precedence rules.

This page explains where Clapilot configuration lives, which layer wins when the same value exists in several places, and which env flags matter at deploy time. It is written for operators and developers setting up or debugging an instance; the admin-facing settings UI is described further down.

Configuration is layered across Compose env vars, persisted app_settings, persisted native-agent tables (agent_provider_configs, agent_channel_configs, agent_channel_approvals), and native runtime state under /app/workspace/.clapilotaicore. As a rule of thumb: database-backed settings are authoritative at runtime, env vars act as bootstrap values and fallbacks, and the .clapilotaicore snapshot mirrors the resolved runtime config.

Deployment files

main stack: docker-compose.yml
app image/runtime: Dockerfile
bootstrap orchestration: entrypoint.sh

Apple Shared Web Credentials

The native iOS/macOS login screen can offer saved credentials for the selected Clapilot instance, such as app.clapilot.com, through Apple's Shared Web Credentials flow.

The Apple app entitlements include exact entries for known instances (app.clapilot.com, dev.clapilot.com, development.clapilot.com, yes.clapilot.com, and kanzleideutsch.clapilot.com) plus webcredentials:clapilot.com and the wildcard fallback webcredentials:*.clapilot.com.
Clapilot serves the required Apple app-site association payload at /.well-known/apple-app-site-association and /apple-app-site-association.
Those paths must remain publicly reachable without an app login redirect and with application/json content so Apple can verify the website-to-app association.
The association payload lists the native app identifiers 97NL7NZ9K6.com.clapilot.apple and 97NL7NZ9K6.com.clapilot.github.

Apple Universal Links

Clapilot web URLs on associated domains open directly in the native iOS/macOS app when it is installed (for example https://app.clapilot.com/aufgaben/<id> opens the task detail screen).

The same app-site association payload (src/lib/apple-app-site-association.ts) carries an applinks section listing the claimed paths. Only paths the native app can route are claimed: /aufgaben (including /aufgaben/<id> task details), /dokumente, /calendar, /chat, /team-chat, /emails, /geplante-aufgaben, /issue-reporter, and the supported /modules/<slug> module pages. Unclaimed paths (login, settings, admin, docs, share links) keep opening in the browser.
The Apple app entitlements mirror the Shared Web Credentials entries with applinks: variants, including the applinks:*.clapilot.com wildcard so every instance subdomain deep-links into the app.
In the app, UniversalLinkRouter (clients/apple/ClapilotApple/Sources/Clapilot/App/UniversalLinkRouter.swift) maps the link path to a native section; the claimed path list there must stay in sync with the applinks components in src/lib/apple-app-site-association.ts.
Links are matched against the signed-in instance accounts by origin. A link for a non-active account switches to that account first; links for unknown instances are ignored.
Links arriving during cold start are parked until bootstrap and session restore complete, then routed.
Apple's CDN fetches and caches the association file per domain, so newly claimed paths can take up to a day (or an app reinstall) to become active on a device.

Precedence map

Clapilot runtime execution is native-only and uses clapilot-agent.
Native runtime base URL prefers app_settings.native_agent_base_url, then CLAPILOT_AGENT_BASE_URL. All app → runtime calls share one transport with failure classification, retry/backoff and an admin-readable monitor (/api/agent-runtime/transport-status, runtime console agent-transport-check); tune it with CLAPILOT_AGENT_TRANSPORT_RETRIES, CLAPILOT_AGENT_TRANSPORT_RETRY_BASE_MS, and CLAPILOT_AGENT_TRANSPORT_HEADERS_TIMEOUT_MS (see Operations → Agent runtime transport diagnostics).
Native runtime state persists under /app/workspace/.clapilotaicore; no OpenClaw package or gateway config is generated in the image anymore.
Agent mailbox defaults come from app_settings with env overrides.
GitHub repo access now prefers named integrations in app_github_integrations, referenced by name from app_settings for Website Canvas plus the Agent Orchestrator issue observer, PR review, and mention observer flows. Legacy github_token / github_pr_review_token values remain compatibility fallbacks.
User mailboxes come from user_email_accounts (multiple IMAP/POP3 accounts per user). company accounts resolve the admin default IMAP/SMTP server from app_settings; custom accounts carry their own host/port. Accounts are managed in Einstellungen → App Verbindungen; the legacy user_profiles.kanzlei_email* columns are frozen and were backfilled into the new table by migration 290.
App settings API updates DB settings and selected runtime mirrors.
Native runtime provider/channel config is read from agent_provider_configs and agent_channel_configs; provider secrets and token-based channel secrets are stored encrypted and managed through /api/agent-runtime/config.
Cross-provider native model priority is persisted in app_settings.native_model_routing; this list defines the default model and global fallback chain across providers. The same JSON also stores the active non-specialized agent-core selection (native vs embedded_pi) used by sessions.executeRun() for providers that do not already require a specialized Codex or Claude subscription runtime, plus the global default provider/model selections for TTS, STT, and generated images. The Memory Dreaming panel stores its optional exact model as memory_dreaming_model in this same JSON configuration. Dreaming resolves an explicit manual model first, then this persisted value, then CLAPILOT_AGENT_MEMORY_MAINTENANCE_MODEL, and finally the automatic global model default. Dreaming and other maintenance completions execute as direct provider completions, so OpenAI Codex subscription (Codex OAuth) providers are excluded from this resolution and from the Dreaming model picker; Claude subscription models remain valid because the runtime has a direct Claude CLI completion path.
Native channel security approvals are persisted per channel in agent_channel_approvals; unknown DMs/groups stay blocked until an admin approves them in ClapilotAICore settings unless the channel's allow_without_approval setting is enabled. DM approvals now also bind the external thread to a specific Clapilot user main-chat session, while approved groups bind the external thread to a selected team-chat room such as clapilot-members.
Specialized agent channel links are stored on specialized_agents: Telegram bot tokens are encrypted with the native config secret and polled by clapilot-agent, while WhatsApp links use specialist-scoped WhatsApp Web/Baileys auth directories under .clapilotaicore/channels/whatsapp/specialized-agents/{agentId}. The linked WhatsApp number is derived after QR login and persisted for display/routing metadata. Matching inbound messages run inside the linked specialist's scoped prompt/tool/auth envelope, use specialist-only approval rows, do not require user mapping, and can independently enable telegram_allow_without_approval / whatsapp_allow_without_approval.
Approved native channel messages default to Clapilot's internal channel-response bridge for Slack and WhatsApp. Telegram uses the native runtime agent path directly when streaming replies are enabled; Telegram photo/document attachments bypass the plain text bridge and are injected into the native multimodal runtime as input_image / input_file parts.
Native WhatsApp no longer uses a stored access token in ClapilotAICore. The runtime owns a backend-side WhatsApp Web/Baileys session, linked via QR from the Channels settings page, and persists its auth state under .clapilotaicore.
Native runtime bootstrap files are read directly from the shared workspace at /app/workspace (or the legacy CLAPILOT_WORKSPACE_DIR / OPENCLAW_WORKSPACE_DIR env aliases), so AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, and TOOLS.md stay file-based instead of moving into the database. MEMORY.md remains editable and searchable but, by default, is not injected as a prompt file.
The managed Google Meet Chromium profiles are stored under ${CLAPILOT_GOOGLE_MEET_STATE_DIR} when explicitly configured, otherwise under <ClapilotAICore state>/google-meet (normally /app/workspace/.clapilotaicore/google-meet). This path must remain on persistent workspace storage so the dedicated Agent Google login survives container and image replacement. When a dedicated account profile is first created, an existing persistent legacy browser-profile is copied into it without deleting the source. Because Google OAuth API tokens do not create a Google website session, admins complete the one-time instance-browser sign-in through Settings -> App Verbindungen -> Agent Google Workspace -> Details -> Meet-Browser anmelden; no browser cookies are exposed through the UI or API.
Additional long-term memory files under memory/**/*.md are synchronized into the native recall layer through /api/agent-runtime/memory; entries are stored in agent_memories / agent_memory_chunks and refreshed idempotently from the shared workspace.
The same memory admin flow can migrate historical legacy transcript memory from the compatibility state directory (CLAPILOT_AGENT_COMPATIBILITY_STATE_DIR, legacy alias OPENCLAW_STATE_DIR) into the native recall layer when those files still exist under the native state root.
Native chat runs add a runtime-owned system prompt and may use internal agent tools (context_search, context_get, memory_search, memory_get, memory_grep, memory_describe, memory_expand, knowledge_search, knowledge_get_entity, knowledge_neighbors, knowledge_explain_claim, learning_search, learning_get_object, session_status) before returning the final answer. The shell tools exec_command and package_install remain advertised and executable by default, and normal instances retain the existing full-capability Claude/Codex subscription bridge behavior. A Hub administrator can disable Shell tools on one selected Fleet instance's detail page; this persists the exact value false for that instance's CLAPILOT_SHELL_TOOLS_ENABLED capability only after the redeploy succeeds and affects only that instance. Stopped instances remain stopped during the policy update. Fleet-wide environment defaults do not apply the opt-out globally. The web/native proxy, deterministic job and direct package-install paths, Agent Orchestrator job/session creation and continuation (including direct module endpoints, webhooks, supervisor, and polling), Website Canvas shell-backed session/apply/sync/commit/push paths, and Live Voice catalogs then omit or reject shell-capable entry points. Claude/Codex subscription bridges use their safe/read-only permission envelope on that opted-out instance, and later redeploys preserve the selected instance policy.
Before the final provider call, the native session layer estimates the prompt budget against the selected model context window, writes a durable memory flush when needed, and then runs a native safeguard compaction pass: older turns are merged into a persisted structured session summary, only the recent preserved turn tail stays verbatim, and the replayed tail is trimmed further if the model budget still requires it. Approved learned context and retrieved memory are still dropped before recent tail turns when necessary.
For OpenAI-compatible providers, admins can now store per-model context window and output cap values directly in the provider settings UI. Those limits are used for history replay trimming and output token caps when the backend does not expose limits automatically.
ClapilotAICore's canonical runtime config snapshot lives at /app/workspace/.clapilotaicore/clapilotaicore.json.
The active chat/tool runtime stays inside the native clapilot-agent provider loop; the Docker image no longer installs the OpenClaw package or CLI.

Settings categories (UI)

The left app sidebar now opens menu customization from the header icon instead of duplicating that action as a normal navigation entry.
The customize dialog is shared between the app sidebar and the settings sidebar, and stored per user through the same menu-preferences API.
The sidebar has a dedicated Developer group below Module: it holds Coding Agents (/modules/agent-orchestrator) plus the bundled Benchmark and Terminal modules when they are active. Like every group, it is hidden while it has no visible items (for example when developer mode is off and none of these modules are available).
Settings categories with subpages expand into an indented submenu in the left settings sidebar; the active category expands automatically, and settings search also matches submenu labels.
Profil: account, email, heartbeat, and password settings. The account page also contains the onboarding restart card and data portability: every user can export their own records, while admins can export the full workspace as open JSON, CSV, XLSX, ICS, VCF, and original document files (POST /api/data-export; see data-portability.md). Menü anpassen is the final profile submenu action. Portable exports require an explicit settings action and are intentionally not exposed as chat/agent tools.
App Verbindungen: user-facing connection hub for added integrations, rendered as a single-column list of full-width connection rows. Google Workspace and Microsoft 365 remain personal OAuth connections with per-service toggles; the personal Google Workspace connection and the dedicated Agent Google account are added separately through the Integration hinzufügen menu instead of appearing together, and a newly connected Google account starts with all standard services (Kalender, Drive, Docs, Sheets, Gmail, Kontakte) enabled by default while the Google consent screen remains the place where the user restricts actual access. Google Workspace can enable Gmail for the unified personal inbox and sender picker, Microsoft 365 can enable Outlook Mail for the unified personal inbox, and Microsoft OneDrive imports files into the virtual Microsoft 365 document folder when enabled. Apple iCloud is connected with Apple-ID plus app-specific password: calendars use CalDAV with write-back for ordinary non-recurring events, contacts use CardDAV, and iCloud Mail is loaded as an additional personal mailbox/sender through Apple's IMAP/SMTP servers without replacing the local IMAP accounts. Personal IMAP/POP3 mailboxes are added here as well through the Integration hinzufügen menu: Firmen-E-Mail (IMAP/POP3) (only offered when an admin has configured the company-wide default mail server; the user enters only email address and password) and Eigenes E-Mail-Konto (IMAP/POP3) (email, password, and own IMAP/SMTP server details). Multiple email accounts per user are supported; the former Kanzlei-E-Mail/E-Mail-Passwort fields under Profil → E-Mail were removed (that page now only manages the outgoing signature and filter rules). X is available as a personal OAuth connection, and admins can also manage named GitHub integrations and add multiple GitHub keys for different automation roles. Admins additionally see an Externe Integrationen tab for the global OAuth client credentials and non-provider app keys that back these connections; the tab is not rendered for non-admin users.
Module: expandable settings group for Kontakte, Kalender, Canvas, Agent Orchestrator, and News; module, developer-mode, and admin visibility rules are applied to the individual submenu entries.
Versionen: admin-only runtime inventory page for the current Clapilot web build, native agent build, and directly integrated CLI tools such as Codex CLI, Claude Code CLI, Python, tar, and Git. The page probes the live instance and is intentionally UI-only because it exposes host/container-specific executable paths and installation details.
Speicher: admin-only storage page (/admin/storage) showing live free/used space of the workspace volume with the ok/warning/critical level, the cleanup worker's usage-by-source report, the retention rules, and the last cleanup cycle. Backed by GET /api/admin/storage and mirrored by the read-only instance_storage_status agent tool; alert thresholds and retention windows are documented in operations.md. Storage alerts and hub customer monitoring alerts share the admin-configurable target channel under Hub -> Monitoring (app_settings.monitoring_alert_room_id; empty = main Team Chat, inactive rooms fall back to the main Team Chat with a log entry).
ClapilotAICore: native runtime base URL, provider/channel forms, a dedicated Search Providers subpage for the global web-search default plus Brave and Perplexity credentials, per-provider model selection, an explicit provider routing switch that preserves credentials/models while disabled, audited enable/disable transitions, per-provider configured/connected status badges, OpenAI/Codex write-preflight health with an unhealthy / missing scope repair hint, explicit API vs Subscription route badges for provider rows and global model priority entries, default-collapsed provider cards, per-model context/output caps including shipped fallback display for known OpenAI/Anthropic/xAI models, GPT-5.6 Sol/Terra/Luna plus pre-release GPT-6 Astra, GPT-5.5, GPT-5.4, GPT-5.4 Mini, and Codex-subscription-only GPT-5.3 Codex Spark, Codex-auth-specific OpenAI chat defaults, Codex app-server device-code sign-in with automatic completion polling instead of pasted localhost redirects, xAI Grok subscription OAuth for grok-4.3 / grok-build-0.1 through xAI Responses plus Grok Imagine image/video media routing, per-model Codex app-server service-tier selection with optional CLAPILOT_AGENT_CODEX_SERVICE_TIER fallback, and an opt-in per-model 1M context toggle for eligible Codex-auth OpenAI models, an automatically aggregated global cross-provider model priority/fallback list, per-channel DM/group approval queues, provider model discovery, deeper native memory diagnostics, workspace-memory synchronization controls, legacy transcript migration controls, a dedicated Learning subpage with candidate review/approval actions, a dedicated Bootstrap-Dateien subpage for the shared bootstrap files (AGENTS.md, IDENTITY.md, SOUL.md, USER.md, MEMORY.md, TOOLS.md), and a dedicated Sessions diagnostics subpage. Codex OAuth model discovery and device login are served by the installed Codex app-server, so Docker images must be rebuilt when the pinned Codex CLI version changes.
The profile account fields also include the user's chat activity selection. The compact animated three-dot bubble is the default in web, iOS, and macOS; selecting Clapilot, Pilot Rooster, or a custom Pet replaces it for assistant work indicators. Generic loading indicators remain unchanged. Signatures can be maintained as plaintext plus optional sanitized HTML with helper controls for website, email, phone, social links, and uploaded PNG/JPG/GIF/WebP logos. Uploaded signature images are stored in the HTML signature as data images for draft portability and converted to inline CID assets when mail is sent, so recipients do not need public image URLs. The signature is appended to new outgoing drafts, direct sends, and automatically prepared personal email replies; when possible Clapilot suggests a plaintext signature from recent sent mail after a mailbox is connected.
Admin: admin-only grouped section with subpages for General, Agent, Website, Feature Toggles, Emails, Demo Daten, Backup, Call & Fax Agent, Physische Post, Versionen, and Speicher. Backup exports/imports one ZIP containing database.sql and the full configured Clapilot workspace tree. Export uses pg_dump; import restores with psql --single-transaction and replaces the workspace tree after SQL restore succeeds. Older document-only backups still import by replacing just mandanten/. Host-local deployments can set PG_DUMP_BINARY and PSQL_BINARY when the default clients on PATH do not match the PostgreSQL server major version. This flow is intentionally not exposed as a chat/agent tool because it contains the full tenant data set.
Feature Toggles: central rollout page for admin-owned feature switches. It owns the Automatisches Onboarding nach erstem Login switch, a test-start button for launching the current user's onboarding flow immediately, the Kontakte Web-Profile-Crawl switch plus the associated contact enrichment status/backfill controls, the Developer mode switch that reveals the admin-only Developer settings area and developer-only modules such as Agent Orchestrator and Terminal, and the Clapilot Tab Layout switch (app_settings.tab_layout_enabled, default on since migration 283 — opt-out). The tab layout keeps the chat dock open by default for all users. Each user can opt into a collapsible dock under Profile → Chat. The preference is stored as user_profiles.chat_dock_collapsible (default false). When enabled, the existing browser-local clapilot-floating-chat-minimized value controls whether the still-mounted dock is visible; tab/session bindings therefore remain active while it is collapsed. This per-user preference does not change app_settings.tab_layout_enabled.
Clapilot Tab Layout: instance-wide desktop-web shell variant, enabled by default (admins can opt out under Admin -> Feature Toggles). The docked left sidebar is replaced by a burger button that opens the navigation as an overlay drawer, a browser-style tab strip sits above the content, and the right chat dock is always loaded and expanded by default. Menu links navigate in the current tab, so tabs stay optional: the + button in the strip opens a page-picker popover — an icon grid of all pages and modules rendered from the same workspace navigation model as the sidebar (localized names, active bundled modules, and per-user menu preferences included) — and the selected entry opens in the new tab. Clicking the already-active tab opens the same picker in navigate mode: the selected entry replaces the active tab's page (like following a menu link), keeping the tab count unchanged. Tabs share the available window width browser-style — they shrink and truncate instead of scrolling. Each tab shows its module's navigation icon as a favicon-style prefix; inactive tabs render as soft gray pills and the active tab as a white bordered pill. The three most recently used tab views are kept alive: they stay mounted but hidden, so switching back is instant and preserves the page's full client state (open editors, scroll positions, drafts). Hidden views run with frozen usePathname/useSearchParams/useParams values so they ignore the global route change, and pages that publish the shared agent page context skip publishing while hidden (isRouteVisible) and republish via useRouteVisibilityTick when shown again; the context they publish carries routePathname so the shell can drop a stale context after route changes. Tabs are route bookmarks: the active tab follows in-tab navigation, tab titles start as the page/menu label and gain an entity suffix (for example Video Studio – <storyboard>, Wiki – <page>, E-Mails – <subject>) from the same page-context signals pages and modules already publish for the agent (documentTitle, canvasTitle, activeWikiPageTitle, activeProjectTitle, opened_email_subject, or the explicit tabDetailTitle key for new modules). Chat tabs show the open session name the same way (Chat – <session>). Each non-chat tab also remembers the chat session last used in the right dock and restores it when the tab becomes active again, so parallel workstreams keep their own conversations. A running Live Voice conversation is independent of that per-tab session binding: it is hosted app-wide (LiveVoiceProvider), keeps running across tab switches and route changes, stays attached to the session it was started in, and can be muted or stopped from the floating live-voice status pill on any tab. Tabs persist per browser session (sessionStorage) and are soft-capped at 20 — opening more evicts the oldest inactive tab; inactive tabs are unmounted route bookmarks, so many tabs carry no runtime cost. Phones below the md breakpoint keep the classic shell, and the Apple clients are intentionally unaffected by this web-only experiment.
Developer: admin-only root-level settings entry (a sibling of Admin, Hub, and ClapilotAICore, not an Admin subpage) that is hidden until Developer mode is enabled under Admin -> Feature Toggles. It currently hosts in-instance E2E suites that run against the live Clapilot instance and are intended for manual verification of regressions that require configured runtime auth or subscription-backed model access. The webchat suite verifies the PR #682 stored-history replay regression by seeding stale completed runs and synthetic transcript wrappers, executing one current webchat turn, and checking that only the current request wins. The Canvas suite sends create/edit chat requests, checks that the generated Canvas file uses the global Canvas style colors, and verifies the edited file contains the requested taxpayer name and refund amount. A cleanup mode selector controls whether seeded runtime artifacts and generated Canvas files are deleted after the run or kept for diagnostics.
Terminal: developer-mode bundled module at /modules/terminal backed by @xterm/xterm in the browser and node-pty in the Next.js Node runtime. Runtime access is admin-only, starts an interactive Bash PTY in the Clapilot web container, scopes the shell to the mounted workspace directory when available, and records session lifecycle audit events in admin_terminal_audit_events. It is intentionally not exposed as a chat/live-agent tool because it provides direct container shell access.
Benutzer: user administration, role changes, expandable per-user account panels with last-login metadata, admin-side display-name/avatar/email/password updates, admin-triggered temporary password resets, and safe account deletion that clears older non-cascading owner references before removing the user.
Agent: admin-only page for den globalen Agent-Anzeigenamen, der in Chat und Delegation gezeigt wird.
General: admin-owned page for Public Base URL, die gemeinsame Basis fuer Redirects, Webhooks und externe Links.
Website: admin-owned page for Website Canvas defaults plus the selected named GitHub integration and repo default used by Website Canvas.
App Verbindungen -> Externe Integrationen: admin-only tab for non-provider app integrations, the global Google, Microsoft, and X OAuth client credentials used by user app connections, the LinkedIn OAuth client credentials used by the bundled Social Media module's LinkedIn platform, plus fallback Gemini and ElevenLabs API keys for legacy audio compatibility. Search-provider credentials live in ClapilotAICore -> Search Providers, audio defaults live in ClapilotAICore -> Audio, and generated media defaults live in ClapilotAICore -> AI Media; per-user Google/Microsoft service enablement and personal X connections stay in the normal Verbindungen tab.
Admin Hub: primary hub configuration page for disabled, local, or remote hub mode, shared secret management, auto-discovered or manually added monitored instances, and health checks.
Issue Reporter: root settings page for new issue reports plus the local Hub review queue. Available targets are GitHub, Task Board, plus the currently configured hub destination (Laufender Hub for local mode or Remote Hub for remote mode). Apps are configured once in the Agent Orchestrator repository matrix by mapping a GitHub repository to a Task Board; Issue Reporter callers address that mapping with the repository basename (without the owner prefix), while omitted app values continue to mean clapilot. The repository selector stays visible on remote-Hub spokes, loads the signed app catalog from the Hub, and opens the selected filtered report list on that Hub; local Hubs render the review queue directly. The review queue defaults to open reports and provides a status dropdown for inspecting all or completed/failed states. Admins can also choose the named GitHub integration whose token creates issues. The web and Apple report forms expose an optional affected-platform selector with Web + iOS / Mac, Web, iOS, Mac, and General.
codex_auth_json is still synced into the native Codex auth store. Standard native chat can route OpenAI-Codex rows through the Codex bridge, while direct OpenAI API chat/embedding calls still use OpenAI-API with a plain openai_api_key.
Anthropic-Claude subscription rows now use a Claude setup-token flow. The stored sk-ant-oat01-... token is persisted like a provider secret and then injected into the local Claude CLI bridge for runtime execution. That bridge removes higher-precedence Anthropic API-key, bearer-token, proxy, and cloud-provider environment variables from the spawned Claude CLI process so the setup-token provider cannot be overridden by other configured providers, and it removes copied whitespace inside setup-token values before launch. The Abo-Nutzung page uses Clapilot-owned credentials only: full Claude Code OAuth credentials (CLAPILOT_CLAUDE_OAUTH_TOKEN, the Claude Auth flow credential in .clapilotaicore/claude-cli/.claude/.credentials.json, an Anthropic provider OAuth row, app_settings.anthropic_oauth_token, or ~/.claude/.credentials.json) go through /api/oauth/usage and /api/oauth/profile, while setup-token provider rows first run the same Docker-local Claude CLI bridge with CLAUDE_CODE_OAUTH_TOKEN to request /usage. Claude web-session fallback supports a stored sessionKey and, when Claude's Cloudflare layer requires it, the matching full browser cookie header. The model picker for these rows is catalog-based, not live-validated. Direct Anthropic API-key rows still use the HTTP API path.
Claude subscription runs now support real Claude CLI streaming, built-in Claude CLI tools, and Clapilot-native app tools through the runtime MCP bridge. In the web chat UI these runs surface live clapilot.tool status lines with friendly labels while the turn is still in progress.
Every Clapilot-managed Claude CLI process disables the CLI's own background autoupdater. Image upgrades remain the authoritative CLI delivery path. On web-runtime startup, Clapilot removes abandoned Claude staging attempts older than 30 minutes, bounds aggregate staging data to 500 MB across the configured CLI state and container user homes, removes zero-byte version stubs, and logs a structured warning when the configured workspace filesystem reaches 85 percent usage. The disk watermark is checked again every five minutes.
Native web-search and Mandanten enrichment read the global app_settings.default_search_provider plus provider configuration under ClapilotAICore -> Search Providers. Supported paths are Brave, Perplexity, SearXNG, Ollama Search, key-free DuckDuckGo HTML search, and Browser Search. The web_search core agent tool is injected directly into compact native/embedded-PI runs for fresh public-web information, while Mandanten enrichment uses the same provider order for client website discovery. Users should not be told to run legacy openclaw configure --section web commands.
Native web search keeps a bounded in-process LRU cache per normalized query, provider, and result limit. Standard queries default to 20 minutes (CLAPILOT_WEB_SEARCH_CACHE_TTL_MS); news/live/current queries default to 2 minutes (CLAPILOT_WEB_SEARCH_TIME_SENSITIVE_CACHE_TTL_MS). CLAPILOT_WEB_SEARCH_CACHE_MAX_ENTRIES controls the default 500-entry bound. Stemmed query variants are opt-in with CLAPILOT_WEB_SEARCH_MULTI_QUERY_ENABLED=true and are skipped for time-sensitive or operator-bearing queries. Cache state is ephemeral and is invalidated on process restart or LRU/TTL eviction.
Legacy Compatibility: instance file/runtime admin tools for the shared workspace and compatibility state/config files, including the older plain-chat transport selection.

ClapilotAICore pages

ClapilotAICore exposes its top-level subpages through the expandable submenu in the left settings sidebar:

Runtime: native runtime base URL and health.
Provider & Modelle: explicit provider add/remove flow via Provider, per-provider credentials/base URLs, per-provider configured/connected state, per-provider model selection, one-token save/activation capability checks for OpenAI-compatible models with unavailable-model labels and routing exclusion, the global cross-provider model priority list, and an OpenAI-Compatible-only per-model Visionfähig flag for custom multimodal backends.
Audio: global text-to-speech and speech-to-text defaults, Realtime provider/model routing, API Live Transcribe, and Google Meet Live Voice settings. The defaults are used when an agent omits routing fields; media_tts_speak and media_stt_transcribe may instead pass an exact enabled runtime provider_slug plus model, which is validated and never silently replaced by the default. TTS accepts OpenAI, Gemini, and OpenAI-compatible provider rows; compatible gateways use their configured /audio/speech endpoint and allow an exact manually entered model alias (for example a LiteLLM chatterbox route) when model discovery does not classify the name as TTS. When a voice reference is supplied, Clapilot sends multipart/form-data to /audio/speech with the standard fields plus a ref_audio file field; OpenAI-compatible backends without this extension should ignore unknown form fields, while requests without a reference continue to receive the existing JSON body. Chatterbox-compatible speech automatically receives the detected German, English, or Italian text language so multilingual pronunciation does not fall back to English. STT remains limited to providers with an implemented transcription adapter. Server-side speech requests use a hard deadline (CLAPILOT_TTS_REQUEST_TIMEOUT_MS, default 120000, clamped to 5 s–15 min) and a per-endpoint cool-down after a timeout or connection failure (CLAPILOT_TTS_UPSTREAM_COOLDOWN_MS, default 30000, 0 disables); during the cool-down further requests to the same endpoint fail immediately with the remembered cause and a retry_after_seconds hint. TTS failures report endpoint (host and path only), model, voice, and the network cause instead of a bare fetch failed.
AI Media: curated model catalogs are the only provider/model selection UI for image, video, and music, with the starred entry acting as the default for each non-empty capability list. Video and music add rows list every configured provider for that capability; OpenAI-compatible media rows derived from runtime providers are included. Model choices merge saved/default models with best-effort live discovery, and every catalog add row also accepts an exact manual model ID. For upgrades, an empty catalog is seeded in the UI from the effective legacy image route or the enabled video/music provider row, starred and marked unsaved; saving persists that seed. Every save also mirrors the image default into native_model_routing.image_generation and keeps exactly one legacy video/music provider enabled with its default_model matching the catalog default, so remaining legacy consumers behave identically. API-level empty-catalog fallback remains available for older clients. Each OpenAI-compatible video row has its own videoBaseUrl and videoAuthDisabled settings in media_generation_provider_configs.settings; the compact Configured video providers list edits those row-scoped values, and discovery plus submit/status/download resolve the selected row's endpoint. Gemini media uses the configured Google Gemini provider key; Kie.ai has one shared media API key. Kie.ai livestream media results are downloaded to CLAPILOT_MEDIA_OUTPUT_DIR, defaulting to /app/workspace/livestream/assets in Docker so the streamer can read completed clips.
LiteLLM: configurable LiteLLM base URL plus API key, followed by a direct usage dashboard and individual spend-log viewer backed by the configured LiteLLM spend APIs.
Search Providers: global default selection between Brave Search, Perplexity Search, SearXNG Search, Ollama Search, DuckDuckGo Search, and Browser Search. Brave and Perplexity use managed API keys. SearXNG uses a configured instance URL with JSON output enabled. Ollama reuses an enabled runtime provider; local hosts require ollama signin. DuckDuckGo is key-free and best effort because it relies on the public HTML results page.
Runtime Memory: embedding/retrieval diagnostics, workspace-memory sync, legacy transcript import, and an explicit split between durable Clapilot-native memory ownership and engine-specific context-window maintenance ownership.
Bootstrap-Dateien: editor for the shared bootstrap files (AGENTS.md, IDENTITY.md, SOUL.md, USER.md, MEMORY.md, TOOLS.md) in the shared workspace. MEMORY.md remains in this editor and the searchable memory projection even though direct prompt injection defaults off.
RAG Index: pgvector health, indexing coverage, queue diagnostics, recent failed jobs, manual reindex actions, and explicit document vision fallback controls.
Channels: Telegram/Slack/WhatsApp provider cards with branded headers, collapsed provider-specific settings by default, compact one-line JSON editors for empty settings, native WhatsApp Web QR linking, delivery settings, and approval queues.
Sessions: admin diagnostics for the native runtime session layer, including a searchable list of agent_session_state entries, the mapping back to chat_sessions / legacy session_user identities where applicable, recent agent_runs, recent agent_events, app chat transcript fallback from chat_nachrichten, and the raw bootstrap_meta / state_json payloads.
Logs: provider request audit logs across API, bridge, and embedding calls, with provider/model/timing diagnostics for actual runtime traffic.

The Sessions page is intentionally explicit about the session layering:

web/group chat continuity still starts from chat_sessions and its persisted session user identity
web/group native runtime keys are derived from that compatibility identity (agent:<agentId>:openai-user:<session_user>)
native channel and job sessions can bypass chat_sessions entirely and write direct keys such as channel:<channel>:<thread> or native-job:<id>
durable runtime state and logs live in the native tables agent_session_state, agent_runs, and agent_events

The Runtime Memory subpage has two distinct admin actions:

Workspace-Memory synchronisieren: refresh native recall from the shared workspace memory/**/*.md tree
Legacy-Memory migrieren: import persisted legacy transcript memory from the mounted compatibility state during a migration

Per-user speech-to-text

Each user selects the chat-composer transcription path under Settings -> Profile -> Speech to text:

Browser / app based is the default. Web uses the browser speech-recognition capability; iOS and macOS use Apple speech recognition.
GPT Realtime Transcribe streams microphone audio to OpenAI gpt-live-transcribe and writes incremental plus final transcription events into the existing chat composer.

GPT Realtime Transcribe detects the spoken language independently of the Clapilot interface language, so a user can dictate German while using the English UI. Completed speech items remain in the composer while later items continue streaming.

An administrator must first configure the shared API capability under Settings -> ClapilotAICore -> Audio:

enable an OpenAI API-key provider and select it as the Realtime provider;
enable API Live Transcribe;
select the compatible live-transcription model.

Provider activation is capability-wide, not a declaration that the provider participates in text routing. An OpenAI provider can therefore remain enabled with no text models and serve only Realtime transcription, text-to-speech, speech-to-text, or image generation. Chat routing considers only enabled providers that contain at least one compatible text model. Disabled providers remain visible for diagnosis but cannot be selected for API Live Transcribe.

The capability is disabled by default. The model list intentionally contains only models compatible with both the web WebRTC and Apple WebSocket paths; it starts with OpenAI's recommended gpt-live-transcribe. The committed-turn-only gpt-transcribe model is not offered because it requires a WebSocket-specific workflow and would not work in the shared browser path.

The OpenAI option is additive and explicit because microphone audio leaves the device. Codex subscription OAuth is not treated as a Realtime API credential. The long-lived provider key remains on the Clapilot server. Web and Apple clients receive only a two-minute Realtime client secret bound to a transcription-only session and the authenticated user's privacy-preserving safety identifier.

The selected value is stored per user as user_profiles.chat_preferences_json.speech_to_text_provider with device or openai_realtime. Missing or unsupported values fall back to device. Stopping dictation explicitly commits the buffered turn; clients reconcile conversation.item.input_audio_transcription.delta and .completed events, keeping the partial transcript when a final event contains no replacement text.

The global gate and model are stored in app_settings.api_live_transcribe_enabled and app_settings.api_live_transcribe_model. A user can keep the per-profile OpenAI selection while the capability is disabled, but session creation fails closed with a localized configuration error and HTTP 409; it never falls back to uploading audio elsewhere.

The global model list is derived automatically from the models selected inside each provider card. Admins only need to sort the final cross-provider order; they do not add entries manually anymore.

Detailed runtime docs:

For the current Docker-first rollout, native exec/package-install approvals are intentionally not restricted yet. Embedded owner runs and the native tool path can execute shell commands and structured package installs directly inside the clapilot-agent container. A stricter policy layer can be added later without changing the tool contract.

Native session compaction can be tuned in the runtime config snapshot under history.compaction:

enabled: default true
recentTurnsPreserve: how many recent completed turns remain verbatim outside the compacted summary
maxSummaryTokens: output cap for the native summary pass
minTurnsSinceCompact: minimum new turns before a non-budget-triggered compaction runs again
maxHistoryShare: approximate share of the model context the uncompacted history may occupy before native compaction becomes aggressive
qualityGuardMaxRetries: bounded retries when the structured compaction summary misses required sections, identifiers, or the latest ask
transcriptBytesThreshold: byte-size trigger for proactive compaction even when token estimates are stale

Key runtime flags

# Required
DATABASE_URL=postgresql://...
AUTH_SECRET=...

# Legacy compatibility env aliases
CLAPILOT_AGENT_COMPAT_BASE_URL=
CLAPILOT_FORCE_WORKSPACE_SEED=false
CLAPILOT_WORKSPACE_DIR=/app/workspace
CLAPILOT_HOME=/app/workspace/.clapilotaicore
CLAPILOT_AGENT_COMPATIBILITY_STATE_DIR=/app/workspace/.clapilotaicore
CLAPILOT_CONFIG_PATH=/app/workspace/.clapilotaicore/clapilotaicore.json
CLAPILOT_SYSTEM_AUTH_SECRET=
CLAPILOT_SYSTEM_AUTH_STATE_FILE=/app/workspace/.clapilotaicore/system-auth.json
CLAPILOT_SYSTEM_AUTH_TOKEN_TTL_SECONDS=120
CLAPILOT_SYSTEM_AUTH_AUDIENCE=clapilot-internal-api

# Native agent runtime
CLAPILOT_AGENT_BACKEND_PROVIDER=native
CLAPILOT_AGENT_BASE_URL=http://clapilot-agent:3210
CLAPILOT_AGENT_INTERNAL_TOKEN=
# app -> runtime transport: extra attempts for transient dns/connect failures, backoff base, per-attempt headers timeout (0 = off)
CLAPILOT_AGENT_TRANSPORT_RETRIES=2
CLAPILOT_AGENT_TRANSPORT_RETRY_BASE_MS=300
CLAPILOT_AGENT_TRANSPORT_HEADERS_TIMEOUT_MS=0
CLAPILOT_AGENT_CONFIG_SECRET=${AUTH_SECRET}
CLAPILOT_AGENT_OPENAI_ENABLED=true
CLAPILOT_AGENT_ANTHROPIC_ENABLED=true
CLAPILOT_AGENT_BEDROCK_ENABLED=false
CLAPILOT_AGENT_BEDROCK_REGION=eu-central-1
CLAPILOT_AGENT_BEDROCK_MODELS=us.amazon.nova-pro-v1:0
CLAPILOT_AGENT_BEDROCK_API_KEY=
CLAPILOT_AGENT_BEDROCK_BASE_URL=
CLAPILOT_AGENT_AZURE_OPENAI_ENABLED=false
CLAPILOT_AGENT_AZURE_OPENAI_BASE_URL=
CLAPILOT_AGENT_AZURE_OPENAI_MODELS=
CLAPILOT_AGENT_AZURE_OPENAI_API_KEY=
CLAPILOT_AGENT_AZURE_OPENAI_API_VERSION=v1
CLAPILOT_PROVIDER_TIMEOUT_MAX_ATTEMPTS=3
CLAPILOT_PROVIDER_TIMEOUT_BACKOFF_BASE_MS=2000
CLAPILOT_PROVIDER_TIMEOUT_BACKOFF_MAX_MS=30000
CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_THRESHOLD=3
CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_OPEN_MS=600000
CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_PROBE_INTERVAL_MS=30000
CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_WINDOW_MS=900000
CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_MAX_OPEN_MS=7200000
CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_PROBE_TIMEOUT_MS=20000
CLAPILOT_PROVIDER_TURN_MAX_REQUESTS=3
CLAPILOT_PROVIDER_TURN_MAX_FAILURE_DOMAINS=2
CLAPILOT_PROVIDER_TURN_MAX_IDENTICAL_FAILURES=2
CLAPILOT_AGENT_JOB_POLL_MS=15000
CLAPILOT_VIDEO_POLL_ERROR_BASE_DELAY_SECONDS=60
CLAPILOT_VIDEO_POLL_ERROR_MAX_DELAY_SECONDS=600
CLAPILOT_VIDEO_POLL_ERROR_FAIL_MINUTES=30
CLAPILOT_AGENT_JOB_RETRY_MS=300000
CLAPILOT_AGENT_JOB_MAX_RETRY_MS=3600000
CLAPILOT_AGENT_JOB_RETRY_JITTER_RATIO=0.35
CLAPILOT_AGENT_COMPAT_BASE_URL=
CLAPILOT_AGENT_CHANNELS=telegram,slack,whatsapp
CLAPILOT_AGENT_MEMORY_EMBEDDING_MODEL=text-embedding-3-small
CLAPILOT_AGENT_MEMORY_TOP_K=6
CLAPILOT_AGENT_MEMORY_MIN_SCORE=0.12
CLAPILOT_AGENT_EXCLUDE_MEMORY_MD=true
CLAPILOT_AGENT_MEMORY_FLUSH_ENABLED=true
CLAPILOT_AGENT_MEMORY_FLUSH_TRANSCRIPT_BYTES=18000
CLAPILOT_AGENT_MEMORY_FLUSH_RECENT_RUNS=8
CLAPILOT_AGENT_MAINTENANCE_COMPLETION_TIMEOUT_MS=240000
CLAPILOT_AGENT_MAINTENANCE_PROVIDER_TIMEOUT_MS=120000
CLAPILOT_AGENT_COMPACTION_PROVIDER_TIMEOUT_MS=90000
CLAPILOT_AGENT_COMPACTION_COMPLETION_TIMEOUT_MS=100000
CLAPILOT_AGENT_HISTORY_COMPACTION_CHUNK_TOKENS=4000
CLAPILOT_AGENT_MAINTENANCE_ALLOW_RETRIES=true
CLAPILOT_AGENT_MAINTENANCE_ALLOW_FALLBACKS=true
CLAPILOT_AGENT_MEMORY_DREAMING_ENABLED=true
CLAPILOT_AGENT_MEMORY_DREAMING_MAX_INPUT_MEMORIES=80
CLAPILOT_AGENT_MEMORY_DREAMING_MAX_INPUT_CHARS=30000
CLAPILOT_AGENT_MEMORY_DREAMING_FACT_QUOTA_RATIO=0.5
CLAPILOT_AGENT_MEMORY_DREAMING_PER_SESSION_ACTIVITY_CAP=3
CLAPILOT_AGENT_MEMORY_DREAMING_SYSTEM_SESSION_PREFIXES=clapilot-system:,clapilot-automation:,system:
CLAPILOT_AGENT_MEMORY_RETENTION_ENABLED=true
CLAPILOT_AGENT_MEMORY_LOSSLESS_ENABLED=true
CLAPILOT_AGENT_LEARNING_EXTRACTION_ENABLED=true
CLAPILOT_AGENT_LEARNING_EXTRACTION_MIN_CONFIDENCE=0.75
CLAPILOT_AGENT_LEARNING_EXTRACTION_MAX_CANDIDATES=3
CLAPILOT_AGENT_LEARNING_EXTRACTION_MAX_SOURCE_CHARS=6000
CLAPILOT_AGENT_LEARNING_EXTRACTION_ALLOW_SUBSCRIPTION_RUNTIME=true
CLAPILOT_AGENT_LEARNING_EXTRACTION_AUTO_APPROVE_EXPLICIT_USER_FACTS=true
CLAPILOT_AGENT_LEARNING_EXTRACTION_AUTO_APPROVE_SAFE_FACTS=true
CLAPILOT_AGENT_LEARNING_OPTIMISTIC_ACTIVATION=true
CLAPILOT_AGENT_LEARNING_CURATOR_ENABLED=true
CLAPILOT_AGENT_LEARNING_CURATOR_APPROVE_CANDIDATES=true
CLAPILOT_AGENT_LEARNING_CURATOR_REVIEW_AUTO_APPROVED=true
CLAPILOT_AGENT_LEARNING_CURATOR_REJECT_NOISE=true

# Workers
TASK_SCHEDULER_ENABLED=true
AGENT_EMAIL_POLL_ENABLED=true
DOCUMENT_POSTPROCESS_PROVIDER_LIMIT_PAUSE_MS=3600000
DOCUMENT_POSTPROCESS_QUEUE_RETENTION_DAYS=90
# Max seconds the email prepared-answer flow waits for attachment text extraction
# before drafting (0 disables waiting; capped at 300).
EMAIL_AUTOMATION_ATTACHMENT_WAIT_SECONDS=60

# Module / Skill hub
SKILL_HUB_URL=https://hub.clapilot.com
SKILL_HUB_SECRET=...
MODULE_HUB_URL=
MODULE_HUB_SECRET=...
GITHUB_TOKEN=
GITHUB_PR_REVIEW_TOKEN=

Bundled seeded workspace assets from workspace-seed/ such as skills, modules, avatars, and demo documents now auto-sync into /app/workspace on normal container starts. AGENTS.md is the Clapilot-managed runtime policy and is overwritten from the image seed on every container start so policy fixes also reach existing persistent volumes. The runtime keeps this policy in the system prompt even for lightContext/minimalContext chat runs; those modes may omit optional profile and retrieval layers, but not the managed policy. The remaining workspace profile docs (TOOLS.md, MEMORY.md, SOUL.md, USER.md, IDENTITY.md, BOOT.md, BOOTSTRAP.md) preserve non-empty local edits unless they are placeholder or legacy copies.

Except for the managed AGENTS.md policy, profile docs remain seed-once and agent-owned. An unedited profile doc that byte-matches any historical seed version is auto-synced to the current seed at container start. The historical hashes live in workspace-seed/.seed-history.json and are regenerated with node scripts/generate-workspace-seed-history.mjs.

CLAPILOT_FORCE_WORKSPACE_SEED is the canonical one-shot env for force-syncing the entire workspace-seed/ tree into /app/workspace on next start, including profile docs that would otherwise preserve local edits. OPENCLAW_FORCE_WORKSPACE_SEED remains accepted as a legacy fallback alias.

For native inbound channels, public_base_url is only required when a provider uses webhook delivery. Telegram now defaults to polling in ClapilotAICore; if you explicitly switch Telegram to webhook mode, target Clapilot's public route under /api/agent-runtime/channels/telegram/inbound, which the app forwards internally to clapilot-agent. Native WhatsApp Web still uses the backend-owned QR session instead of this webhook path, but the public Clapilot route now also supports Meta's verification handshake at /api/agent-runtime/channels/whatsapp/inbound when the WhatsApp channel settings JSON contains one of webhook_verify_token, webhookVerifyToken, verify_token, or verifyToken.

clapilot-agent must also share the same secret material as the main app so it can decrypt runtime provider/channel credentials from Postgres. Set CLAPILOT_AGENT_CONFIG_SECRET=${AUTH_SECRET} or pass AUTH_SECRET into the agent container directly.

Provider timeouts are retried by one bounded runtime layer with exponential backoff and jitter. CLAPILOT_PROVIDER_TIMEOUT_MAX_ATTEMPTS includes the initial call, while the backoff values are milliseconds. OpenAI-family HTTP helpers hand timeout failures directly to this layer instead of multiplying retries internally. A provider/model circuit opens after CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_THRESHOLD exhausted timeout runs, either consecutively or inside the sliding CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_WINDOW_MS window (default 15 minutes, so an intermittently stalling provider with successes in between still trips the breaker), and remains open for CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_OPEN_MS the first time. Every re-open without a successful answer in between (a failed half-open probe or a failed first request after the window) doubles the open window up to CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_MAX_OPEN_MS (default 2 hours): 10, 20, 40, 80, 120 minutes. A success ends the consecutive streak but keeps the window; a non-timeout failure does the same. When the open window elapses without a successful half-open probe the circuit stays half-open: the next fixed timeout re-opens it immediately (circuitOpenTrigger=half_open_recovery) instead of starting a fresh countdown of full-length timeouts. Each failed probe doubles the wait before the next probe, and that probe backoff is carried across re-opens; only a successful answer resets it. Whenever a fallback can still answer the turn, a half-open probe or recovery request receives a bounded stall budget (probeRequestTimeoutMs, circuitProbe=true in the attempt telemetry): CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_PROBE_TIMEOUT_MS (default 20 seconds) doubled per failed probe (20, 40, 80 seconds, ...) up to the provider's normal stall budget, and never more than half of the remaining conversation deadline, so the probe cannot burn the whole 45s/60s conversation limit and the fallback still answers inside the same turn; without a fallback the probe keeps the full budget. A probe that stalls against such a reduced budget (probeBudgetReduced=true) re-opens the circuit and backs off the next probe, but it does not escalate the open window, because it only proved that the provider could not answer inside the handicap; only a failure against the provider's normal budget (or an HTTP timeout status from the provider itself) advances reopenStreak. This keeps a slow-but-healthy model (for example a reasoning model with a first token after 25 seconds) from being locked out permanently: after a few bounded probes it is measured against its real budget again. The breaker state is mirrored into agent_provider_circuit_states (migration 305) and restored on the first provider request after a runtime restart, so an image update or crash no longer resets an open circuit; a missing table disables the mirror with one warning and the in-memory breaker keeps working, and a transient database error during the restore is retried on the next provider request instead of silently dropping the persisted circuits (persisted=false is reported in the meantime). Rows older than the retention window (maximum open window plus two sliding windows) are pruned at restore time. Administrators can reset a circuit from the provider dialog in Einstellungen (DELETE /api/agent-runtime/provider-status/circuit?slug=<slug>&key=<circuit-key>), which clears both the in-memory breaker and the database row. Stall deadlines (PROVIDER_REQUEST_TIMEOUT) and HTTP timeout statuses are produced by the upstream request itself, so they charge the circuit even after the run made irreversible progress (the run is still not replayed; the attempt records status=aborted_after_irreversible_progress with circuitCharged=true and, when the breaker trips, circuitOpened=true). Timeout-shaped errors thrown by local tools are never charged. Hard conversation deadlines record status=conversation_timeout with decision=abort_conversation_timeout; the active provider is charged only when the outbound request had started, it received at least half of its applicable deadline budget (bounded by the fallback budget for fallback attempts), and no local tool owned the clock when the deadline fired (toolInFlight), while a starved fallback or a deadline inside a tool call records circuitCharged=false; a half-open probe or recovery request that reaches the deadline is charged like any other attempt (a probe in fallback position that never received a usable share of the deadline stays exempt), so the open window escalates instead of admitting another sacrificial request later. If a run has already emitted output or started/executed a tool, Clapilot does not replay it or move to a fallback model, preventing duplicated visible output and side effects. Before progress, fetch failed, terminated, and other transport failures move to the next distinct configured model in the global priority, including a model from another provider; a provider-attempt event uses decision=fallback only when such a candidate exists. Without an executable candidate it records decision=fail_no_fallback, and interactive chat returns a localized configuration message instead of exposing the raw transport error. CLAPILOT_AGENT_JOB_RETRY_JITTER_RATIO applies bounded jitter to scheduled-job backoff, including retries already at the configured maximum delay. Provider subscription/session quota exhaustion is independent of timeout retries: the affected model is cooled down until its advertised reset (15 minutes when unknown), then an approved model from the existing routing priority/fallback configuration is tried. If none succeeds, scheduled jobs retain their payload and retry beyond their normal retry limit without transient chat notifications.

A run is reported as timeout only when its measured elapsed time reaches or exceeds the timeout configured for that concrete run or provider attempt. Timeout-shaped provider responses that arrive earlier are reported as provider_error; their provider message and HTTP status remain available after credentials, authorization values, tokens, and secrets have been redacted. The model runner, agent session finalizer, orchestrator bridge, and OpenAI-compatible inference bridge use this same boundary rule.

The stricter turn envelope defaults to three upstream requests (CLAPILOT_PROVIDER_TURN_MAX_REQUESTS), two provider failure domains (CLAPILOT_PROVIDER_TURN_MAX_FAILURE_DOMAINS), and two identical failures per provider/model/endpoint (CLAPILOT_PROVIDER_TURN_MAX_IDENTICAL_FAILURES). These limits can stop retries before CLAPILOT_PROVIDER_TIMEOUT_MAX_ATTEMPTS is reached so an independent fallback retains request capacity. The longer-lived timeout circuit key also includes an endpoint fingerprint, preventing failures on one gateway from opening the circuit for the same model on another endpoint. While that circuit is open, the runtime allows at most one half-open recovery probe per CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_PROBE_INTERVAL_MS (default 30 seconds), doubling after every failed probe and bounded by CLAPILOT_PROVIDER_TIMEOUT_CIRCUIT_PROBE_TIMEOUT_MS when a fallback exists.

Interactive timeout recovery does not replay a progressed run immediately, because completed tools may have external side effects. Instead, the runtime checkpoints the request and completed-tool status in PostgreSQL and resumes from conversation history on the next turn. A pending checkpoint may promote the adaptive-routing recommendation for exactly that recovery turn, including a recommendation learned while adaptive routing was in shadow mode; an explicit per-request model override still wins.

Generated-video status polling tolerates transient provider/download errors before giving up. When a status poll or result-download attempt throws, the job stays generating and is re-polled with exponential backoff starting at CLAPILOT_VIDEO_POLL_ERROR_BASE_DELAY_SECONDS (default 60) and capped at CLAPILOT_VIDEO_POLL_ERROR_MAX_DELAY_SECONDS (default 600). The video is only marked failed once errors have persisted for CLAPILOT_VIDEO_POLL_ERROR_FAIL_MINUTES (default 30); the next-poll time is clamped so a large backoff can never push the terminal check past that deadline. Status-poll and result-download failures are tracked in independent windows, so a transient download error after the provider already reported complete cannot fail a genuinely-finished video, and the stored error message names the actual failure kind.

BRAVE_API_KEY (or the mirrored admin setting app_settings.brave_search_api_key) is also used by the Mandanten create flow for optional website/logo/profile enrichment in the customer detail view. The crawl itself is additionally controlled by the admin feature toggle app_settings.mandant_profile_web_crawl_enabled from /admin/features. If the toggle is off, customer creation still succeeds and enrichment is skipped.

LITELLM_API_BASE_URL and LITELLM_API_KEY are optional env fallbacks for the LiteLLM settings page. In normal operation they are stored through app_settings.litellm_api_base_url and app_settings.litellm_api_key from ClapilotAICore -> LiteLLM, and Clapilot proxies LiteLLM's /user/daily/activity plus /spend/logs endpoints server-side for the admin dashboard.

CLAPILOT_BASE_URL is optional, but it becomes the first candidate for internal tool and live-tool proxy hops before the fixed safe fallbacks (127.0.0.1, localhost, clapilot). Request headers are intentionally not trusted for this resolution path, so deployments that do not expose the app on those local hostnames should set CLAPILOT_BASE_URL explicitly.

CLAPILOT_PUBLIC_URL controls the absolute public origin used by page canonicals, /robots.txt, and /sitemap.xml; it takes precedence over the public base URL saved in App Settings and defaults to https://app.clapilot.com when neither source is configured. Docker Compose forwards this value and the supported public URL aliases into the web container, and SEO metadata resolves the persisted setting at request time rather than baking an origin into the image. The sitemap intentionally contains only the unauthenticated /docs pages. Robots metadata and robots.txt keep login, application, admin, and API routes out of search results so private tenant URLs are never advertised to crawlers.

Provider secrets and auth flows for OpenAI-API, OpenAI-Codex, Anthropic-API, Anthropic-Claude, Azure OpenAI, AWS Bedrock, Google Gemini, and OpenAI Compatible are now managed in ClapilotAICore -> Provider & Modelle. Provider cards are no longer auto-rendered by default; admins add them explicitly through Provider and can remove them again from the same panel. OpenAI Compatible can be added multiple times and each instance can be named independently for different compatible backends. The legacy app-level OpenAI / Anthropic fields only remain as compatibility mirrors so older paths continue to resolve credentials during migration.

When CLAPILOT_AGENT_ANTHROPIC_MODELS is unset or empty, the shipped Anthropic defaults are latest, claude-opus-5, claude-fable-5-1, and claude-fable-5. The retired claude-opus-4-8 ref is no longer injected by default because its provider-side alias can resolve to Opus 5 and violate exact-model execution. An explicit CLAPILOT_AGENT_ANTHROPIC_MODELS value remains authoritative and may still contain custom or older model refs.

For AWS Bedrock, the supported provider setup is the native Bedrock Converse API key / bearer token path: paste the raw Bedrock API key or a copied AWS_BEARER_TOKEN_BEDROCK=... export line into the provider secret field. The region is still required. Bedrock model auto-discovery may not work on that auth path, so admins should expect to add the Bedrock model ID manually when necessary.

Older SigV4-based Bedrock secrets are still read by the runtime for compatibility, but they are no longer the primary documented/admin-facing setup path.

Embedding provider + model selection for native memory and the document RAG index is managed in ClapilotAICore -> Provider & Modelle. Realtime provider + model selection is managed in ClapilotAICore -> Audio, next to API Live Transcribe and the Google Meet Live Voice enablement, optional Meet model override, voice, and display-name settings. CLAPILOT_AGENT_MEMORY_EMBEDDING_MODEL is now only an env fallback for bootstrap / recovery cases when no provider selection is stored yet.

Memory v2 stores canonical assertions, exact evidence links, reviews/conflicts, embedding generations, retrieval feedback, and an ingestion outbox in PostgreSQL. CLAPILOT_AGENT_MEMORY_DREAMING_ENABLED controls the scheduled source-backed consolidation pass. Its schema-constrained output is validated before any assertion or Wiki proposal is written; malformed, empty, truncated, or ungrounded output is failed/skipped without a deterministic publication fallback. Safe direct-human facts and preferences can be policy-activated and projected into the approved-only Knowledge Graph automatically. Assistant-generated automation/job/heartbeat inferences remain inactive, and system/automation runtime sessions are excluded from Dreaming input; user-authored automation decisions in Team Chat remain eligible. Every Wiki change remains a review-only proposal; Dreaming never approves or publishes Wiki content. The remaining CLAPILOT_AGENT_MEMORY_DREAMING_* values bound input size, cadence, and human-source balancing. CLAPILOT_AGENT_MEMORY_RETENTION_ENABLED and CLAPILOT_AGENT_MEMORY_LOSSLESS_ENABLED independently control lifecycle cleanup and lossless session history.

CLAPILOT_AGENT_LEARNING_EXTRACTION_ENABLED controls the conservative post-response learning producer. When enabled, it reuses the existing shared-facts postprocess output and creates canonical durable facts or low-risk procedure drafts. CLAPILOT_AGENT_LEARNING_OPTIMISTIC_ACTIVATION defaults to true: safe, non-conflicting direct-human facts and stable preferences become prompt-eligible immediately, while assistant inferences, policies/procedures, corrections, explicit conflicts, secrets, and non-durable runtime state remain blocked or staged. CLAPILOT_AGENT_LEARNING_EXTRACTION_ALLOW_SUBSCRIPTION_RUNTIME defaults to true, allowing Codex/Claude subscription-bridge chat runs to participate. learning_search and learning_get_object expose only approved, visible Learning objects, and context_search / context_get include them in unified read-only retrieval; none of these tools expose approval or curator mutation paths. CLAPILOT_AGENT_LEARNING_EXTRACTION_MIN_CONFIDENCE, CLAPILOT_AGENT_LEARNING_EXTRACTION_MAX_CANDIDATES, and CLAPILOT_AGENT_LEARNING_EXTRACTION_MAX_SOURCE_CHARS bound extraction per run.

CLAPILOT_AGENT_LEARNING_CURATOR_ENABLED controls the bundled native Learning Curator system automation. The curator is model-backed: select its exact model on /geplante-aufgaben, just like other configurable system automations. Every run sends only previously unchecked or content-changed durable facts plus bounded source evidence to that model under a strict JSON schema. The default decision is keep; a rejection is applied only for a validated high-confidence classification such as false/unsupported, contradicted, duplicate, temporary, runtime noise, unsafe, or not worth retaining. Checked content is stamped with the curator policy version and content hash, so it is not repeatedly billed unless the fact or policy changes. Manual admin/user decisions are authoritative and are never overwritten. The older CLAPILOT_AGENT_LEARNING_CURATOR_* thresholds remain available to the immediate deterministic safety pass used by targeted Memory Dreaming completion; the scheduled curator model and its rejection threshold are stored in the automation payload.

DOCUMENT_POSTPROCESS_PROVIDER_LIMIT_PAUSE_MS is the fallback pause for the durable document post-extraction queue when a verified provider-limit error has no reset header, timestamp, or short cooldown duration in its provider error message. It defaults to one hour and is never used for arbitrary agent/document output. DOCUMENT_POSTPROCESS_QUEUE_RETENTION_DAYS controls bounded cleanup of terminal queue rows and defaults to 90 days (minimum 7).

Subscription Usage reads Grok directly from an OAuth-backed xAI Grok provider, so the account configured under ClapilotAICore -> Provider & Modelle is also the usage identity. Cursor likewise reuses the User API key from the configured cursor provider: it exchanges that key for a short-lived account token and reads the current monthly included-usage percentage, remaining balance, limit, consumed amount, and billing-cycle reset. Ollama is configured in that same provider catalog: use http://host.docker.internal:11434 for a host-local Ollama service or https://ollama.com plus an Ollama Cloud API key. Ollama's API key authenticates Cloud model requests and its inference responses include per-request token/timing metrics, but Ollama does not expose the account's 5-hour and weekly plan windows through the documented API-key API. The Ollama provider detail therefore also accepts a browser Cookie header copied from an authenticated ollama.com/settings request for the plan-limit display. Clapilot stores the API key and usage session together in the provider's encrypted secret material but uses the cookie only to read Subscription Usage. A saved usage session remains eligible even when the provider has no routed models and is inactive for inference. Only a masked cookie-name hint is returned. CLAPILOT_OLLAMA_COOKIE remains an optional deployment override.

The Audio page stores explicit Realtime provider + model selection alongside the other audio settings. This routing is intentionally separate from embeddings and standard chat priority so live audio paths can target providers like Google Gemini, Azure OpenAI, or custom OpenAI Compatible backends without accidentally becoming the default text-chat provider.

Developer API keys

When app_settings.developer_mode_enabled=true, admins can manage instance API keys under Settings -> Developer. Keys are intended for small external clients and automations that need a narrow, revocable permission rather than an interactive Clapilot login.

subscription_usage:read grants read-only access to GET /api/v1/subscription-usage.
notifications:read grants read-only access to the creating admin's personal-chat and Team Chat notification inbox through GET /api/v1/notifications. Pollers keep the returned next_cursor and pass it as after on the next request; reads do not mark the underlying chat room as read.
memory:read grants creator-bound search and exact retrieval through GET /api/v1/memory?query=... and GET /api/v1/memory/{id}. Only approved, active memories visible to the user who created the key are returned.
memory:write grants creator-bound submission through POST /api/v1/memory. It is independent from memory:read; writes use the native safety, deduplication, assertion, embedding, and review pipeline, so a review-pending write is not immediately searchable.
tools:execute grants creator-bound access to POST /api/v1/tools/execute, which powers remote clapilot-cli use. It is a high-privilege private scope covering the full installed agent-tool catalog, including mutations and shell commands; server-side module restrictions, approval flows, and UI mutation/audit behavior remain active.
For remote CLI use, set CLAPILOT_CLI_BASE_URL=https://your-instance.example and provide the key through CLAPILOT_CLI_API_KEY (or --api-key). Do not reuse or expose the internal agent secret or a web session key.
Memory API limits are per key and enforced atomically in PostgreSQL: reads allow 120 requests per 10 minutes and 5,000 per day; writes allow 60 requests per 10 minutes and 500 per day. Rate-limited responses include Retry-After.
Tool execution limits are per key and enforced atomically in PostgreSQL: 300 calls per 10 minutes and 10,000 per day.
issue_reports:write grants write-only access to POST /api/v1/issue-reports for selected full repositories. It is always isolated on a dedicated clp_public_ key, cannot be combined with any private scope, and only creates untrusted open reports in the Hub review queue. The selected repository allowlist is immutable; replace and revoke the key to change it.
Send the one-time plaintext key as Authorization: Bearer clp_live_... for private scopes or Authorization: Bearer clp_public_... for Issue Reporter; X-API-Key is accepted for clients that cannot set Bearer auth.
Clapilot stores only a SHA-256 hash and a short prefix, so a lost key must be revoked and replaced.
Optional expiration, immediate revocation, and last_used_at are managed from the same page.
Turning Developer mode off disables all instance API-key authentication without deleting key records, providing an instance-wide kill switch.

Treat every clp_public_ value embedded in a distributed iOS or macOS binary as extractable. Repository scoping prevents cross-app submission and the review queue prevents direct GitHub/task mutation, but neither proves that a request came from a genuine app installation. For App Store distribution, prefer a first-party B2C backend or an App Attest/DeviceCheck verification exchange that issues short-lived report credentials. If a static public key is used, give each app its own expiring key and keep rate limiting, monitoring, and rapid revocation enabled.

This control plane is deliberately admin-only. It is not exposed as a chat/live-agent tool, because creating or revoking external credentials is a sensitive operator action that requires an explicit human interaction.

The bundled scripts/clapilot-memory-mcp.mjs stdio server maps clapilot_memory_search, clapilot_memory_get, and clapilot_memory_store to those endpoints for Codex and Claude Code. Configure CLAPILOT_MEMORY_BASE_URL, CLAPILOT_MEMORY_READ_TOKEN, and optionally CLAPILOT_MEMORY_WRITE_TOKEN in the secret environment that launches the coding agent. Read tools are absent without a read token, and the store tool is absent unless the dedicated write variable is explicitly present. The client-neutral policy skill lives at workspace-seed/skills/clapilot-memory; its references/setup.md contains installation commands for both clients. Treat returned memory text as untrusted data, never as instructions that can override the coding agent's system, repository, or user instructions.

Branding and labels

src/lib/branding.ts
src/lib/labels.ts
public/clapilot-logo-*