環境變數

Multica 在程序啟動時讀取環境變數。修改後通常需要重啟對應的 API、Web 或守護程序。Docker Compose 的 docker compose restart 不會重新讀取 .env，要用 up -d 重建容器才能生效。

本頁按分組列出面向部署者的配置，測試變數和內部執行變數不在這裡展開。完整部署步驟見自託管快速上手。

生產環境最小配置Copy Anchor Link

DATABASE_URL=postgres://user:password@postgres:5432/multica?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://multica.example.com
MULTICA_APP_URL=https://multica.example.com
MULTICA_PUBLIC_URL=https://api.multica.example.com

還需要選擇一種郵件服務，否則驗證碼和邀請只會寫入服務端日誌。

API 與資料庫Copy Anchor Link

在 Kubernetes 中設定 shutdown hold 時，terminationGracePeriodSeconds 要大於 hold 與實際退出所需時間之和。

主庫與從庫的連線上限彼此獨立，需要按全部 API 程序的連線數總和預留 PostgreSQL 叢集連線額度。從庫連線預設五分鐘回收一次，以便在提升後重新校驗只讀狀態。從庫連線失敗時，基礎設施會透明回退主庫並短暫開啟被動熔斷器，不會增加後臺資料庫探測。應用不保證從庫資料的最大陳舊時間；請在資料庫層監控複製延遲，一致性敏感的讀取繼續走主庫。

對外地址與瀏覽器訪問Copy Anchor Link

前端和 API 使用不同 host、且瀏覽器直接訪問 API 域時，必須設定 COOKIE_DOMAIN，否則瀏覽器讀不到 CSRF cookie——所有寫請求返回 403 CSRF validation failed，而讀請求一切正常。取值用能同時覆蓋兩個 host 的最窄父域（.agent.example.com 優於 .example.com）。它會把登入會話 cookie 擴散到該域下的所有 host，只有這些 host 都由同一可信主體運維時才可用。修改後需要在兩個 host 上清除舊 cookie 並重新登入。若採用自託管快速上手的同源配方（瀏覽器只訪問 app 域），保持為空即可。不要填寫 IP 地址，瀏覽器會忽略帶 IP Domain 的 cookie。

郵件與登入Copy Anchor Link

ResendCopy Anchor Link

SMTPCopy Anchor Link

只要 SMTP_HOST 非空，SMTP 就會優先於 Resend。

Google OAuthCopy Anchor Link

註冊範圍Copy Anchor Link

白名單的準確判斷順序見登入與註冊。

附件儲存Copy Anchor Link

沒有設定 S3_BUCKET 時，Multica 使用本地磁碟。

S3 或相容儲存Copy Anchor Link

當 AWS_ENDPOINT_URL 指向 Google Cloud Storage 時，會自動將 Accept-Encoding 排除在請求籤名之外。

內網 MinIO 等 endpoint 無法被瀏覽器直接訪問時，使用 ATTACHMENT_DOWNLOAD_MODE=proxy。

本地磁碟Copy Anchor Link

CloudFrontCopy Anchor Link

Redis 與限流Copy Anchor Link

反向代理後的部署需要填寫真實代理網段。不要直接信任所有來源，否則客戶端可以偽造轉發 IP。

認證限流需要配置 REDIS_URL；未配置時，啟動日誌會提示認證限流已關閉。邀請限流在沒有 Redis 時仍使用程序記憶體，配置 Redis 後則在多個副本間共享額度。如果已配置的 Redis 臨時不可用，認證限流仍選擇放行，而邀請建立會返回可重試的 503，不會在失去防護時傳送郵件。

外部整合Copy Anchor Link

不配置 GITHUB_APP_ID 和私鑰時，PR 仍會正常關聯、映象，並在合併後改狀態，但卡片上不顯示 CI 與可合併狀態，"從 GitHub 選擇"倉庫入口也會禁用。

配置步驟見 GitHub 整合、飛書 Bot、Slack Bot和 Telegram Bot。

服務端 LLMCopy Anchor Link

這組配置用於服務端的輔助生成能力，例如對話標題；它不是 AI 代理執行時使用的 AI 程式設計工具憑據。

MULTICA_LLM_MAX_RETRIES 是重試策略的唯一配置源。不設定時使用預設的 2 次；設為 0 表示每次呼叫只發一個請求；設為 1–5 表示最多重試這麼多次。它是上限而不是配額：只有可重試的失敗才會消耗它，請求成功或呼叫方自身的超時都會讓呼叫提前結束。其它取值（負數、非數字、大於 5）會讓服務啟動失敗，不會被靜默糾正。上限是一個延遲預算：退避從 0.5s 開始翻倍，上限 8s，更大的預算會超出呼叫方自身的超時，把可重試的失敗變成超時失敗。重試覆蓋連線失敗以及 HTTP 408、409、429 和 5xx；其餘 4xx 直接返回。服務啟動時會以 llm retry policy 列印生效策略，其中不包含任何憑據。

MULTICA_LLM_DISABLE_THINKING 面向"模型會先跑一段推理（thinking）並吃掉輔助呼叫延遲預算"的閘道器。設為 true（或 1）時，服務端會在每個請求體中附帶 chat_template_kwargs: {"enable_thinking": false}；支援透傳該欄位的閘道器（vLLM/sglang 類部署、部分 GLM/Qwen 系的 LiteLLM 路由）會因此跳過思考階段。標準 OpenAI 端點會拒絕未知的請求體欄位，所以僅在上游接受時啟用。GPT-5.6 系模型和 GPT-6 Luna 在後續提問建議請求中已由服務端附帶 reasoning_effort: none。會話自動命名不傳送推理欄位；只有當所配置的上游接受 chat_template_kwargs 時，此項才會影響它。可接受的取值為 true/false 和 1/0（不區分大小寫）；其它取值會讓服務啟動失敗。啟動日誌會在重試策略旁列印生效狀態。

有兩個功能會使用這一層，它們都會把聊天內容傳送到你配置的 endpoint：

• 對話標題自動生成 —— 傳送新對話中使用者的第一條訊息，原文傳送。附件不會包含在內。
• 後續提問建議（AI 代理回覆下方的按鈕）—— 傳送對話末尾的內容：最多 6 條訊息，其中被追問的那條回覆上限 3000 字元，更早的每條上限 800 字元。

API key 與 base URL 都為空時，這一層關閉，不會發出任何上游請求——上面兩個功能都不再傳送內容。如果你的政策不允許這一層把聊天內容發到部署之外，這就是受支援的配置方式：對話繼續使用客戶端根據第一條訊息生成的標題，後續提問按鈕不再出現，其餘功能不受影響。

守護程序配置Copy Anchor Link

下面的變數在執行 AI 代理的電腦上讀取，不是在 API 容器中讀取。

守護程序注入 AI 代理 task 的內部上下文見 Task 執行時環境。MULTICA_REPO_CHECKOUT_MODE 也屬於這類變數：守護程序只在 Linux 和 Windows 的 Codex 執行中把它設為 isolated，不需要也無法手動配置。守護程序自身環境裡的 MULTICA_* 變數不會傳進執行。

優先順序為命令列 flag → 環境變數 → ~/.multica/config.json → 內建預設。watchdog 的行為見守護程序與執行時。

清理與保留Copy Anchor Link

守護程序定期清理執行工作目錄、倉庫快取、會話記錄和臨時目錄，各類資料的刪除條件見清理與保留。時長接受 Go duration，另外支援 d 表示天（如 14d、1d12h）。

守護程序日誌Copy Anchor Link

守護程序在後臺執行（不連著終端）時，日誌寫入 ~/.multica/daemon.log，命名 profile 為 ~/.multica/profiles/<name>/daemon.log，並按大小輪轉，輪轉出的檔案用 gzip 壓縮。

三個變數都要求正整數；0、負數或無法解析的值按預設值處理，不會變成"不限制"。保留數量和天數哪個先到就按哪個刪除。崩潰輸出寫在同目錄的 daemon.err.log，啟動時超過 5 MB 就改名為 daemon.err.log.1。

各 AI 程式設計工具的路徑、模型與引數Copy Anchor Link

每款內建工具都有路徑變數 MULTICA_<字首>_PATH。設定後，守護程序用這個路徑代替在 PATH 中查詢命令；路徑不存在時這款工具不會註冊，也不會退回 PATH 裡的同名命令。多數工具還有模型變數 MULTICA_<字首>_MODEL：AI 代理沒有選擇模型時，用它作為這臺電腦的預設模型；兩者都為空時不傳模型，由工具自己決定。

QwenPaw 和 MiniMax Code 沒有模型變數，因為 Multica 不會向它們傳模型，詳見 AI 程式設計工具對比。DeepSeek Harness 另有 MULTICA_DSH_PROFILE_BUNDLE 和 MULTICA_DSH_PLUGIN_PATH，見下一節。

全機預設引數 MULTICA_<字首>_ARGS 目前支援 Claude Code、Codex、CodeBuddy、Qwen Code 和 QwenPaw 五款工具，對應變數是 MULTICA_CLAUDE_ARGS、MULTICA_CODEX_ARGS、MULTICA_CODEBUDDY_ARGS、MULTICA_QWEN_ARGS 和 MULTICA_QWENPAW_ARGS。例如：

MULTICA_CLAUDE_PATH=/opt/bin/claude
MULTICA_CLAUDE_ARGS=--max-turns 40

DeepSeek Harness 的 profile 安裝Copy Anchor Link

MULTICA_DSH_PROFILE_BUNDLE 指定 multica profile 缺失時要安裝的 bundle，多個候選用逗號分隔、按序嘗試，每項可以是 npm 包名、目錄或打包好的 tarball。該變數預設不設定。Multica 驅動的 --stdio 協議正是由這個 profile 提供，所以不設定時不會改動 DSH 的安裝，守護程序會報告缺少 profile，不會註冊一個不可用的執行時。

Multica 自己的橋接還沒有釋出到公共 npm registry，如何選取值見安裝 AI 代理執行時。這裡填的東西會在沒有二次確認的情況下裝進每一臺守護程序宿主的 DSH 家目錄，請當作供應鏈決策來對待。

這項安裝被刻意限制了範圍：每個守護程序生命週期最多執行一次，只在探測確認 profile 確實缺失時執行；失敗時會把包管理器自身的輸出記入日誌，且只有重啟守護程序後才會重試。探測超時、或返回本守護程序不支援的協議版本時，只做報告，絕不覆蓋安裝：守護程序不會覆蓋一個明顯是刻意裝上去的 profile。排查時在守護程序日誌中搜尋 DSH runtime profile；要撤銷安裝，刪除 $DSH_HOME/profiles/multica（預設 ~/.dsh/profiles/multica）。

MULTICA_DSH_PLUGIN_PATH 用於覆蓋安裝時解析 pnpm 的目錄。dsh plugin 轉發到的那個 pnpm 由 DSH Desktop 放在它私有的 runtime-commands 目錄裡，macOS 和 Windows 都是如此，守護程序會自動找到並加到 PATH 最前，較新版 Desktop 採用的帶版本號目錄結構也能找到。所以只有守護程序找不到的安裝位置、或者你想讓安裝使用自己的 pnpm 時，才需要這個變數。一旦設定就完全取代自動查詢：目錄不存在時，安裝會退回使用守護程序 PATH 上的 pnpm，不會用內建的那個。Linux 上沒有 DSH Desktop，安裝始終使用 PATH。

Cursor 後臺程序清理Copy Anchor Link

Cursor 已驗證的後臺清理需要 Linux 6.9 及以上（程序組 pidfd）、macOS 核心對程序身份查詢與 audit token 發訊號的支援，或 Windows 上成功分配的巢狀 Job Object。在 macOS 上，每個程序都按核心校驗的 PID version 發訊號，不需要加入同一 session 的程序組；這些 macOS 介面是私有的，會在捕獲時做探測。無法認領的後臺啟動會返回它原本的工具結果並回到普通的 idle watchdog，工具 watchdog 為 0 時同樣如此。已經認領的工作在清理無法確認時會繼續算作執行中。當工具 watchdog 設為 0 時則完全沒有這個邊界：已認領的後臺工作只要還活著就一直讓執行處於執行中，此時執行僅受 MULTICA_AGENT_TIMEOUT 約束，而它預設也是 0。

執行正常結束時，被認領的 Cursor 後臺程序同樣會被停止，因此該次執行啟動的後臺服務不會有意留到收尾之後。macOS 可以透過保留的原始父程序身份識別後期產生的子程序，但無法證明中間程序在被觀察到之前就已消失的那條鏈路。這類程序、離開被追蹤程序組的工作，以及持續的歸屬或發訊號錯誤，都可能留下殘餘的後臺工作。未確認的清理會被記錄下來，且永遠不會換取一次"清理成功"的恢復視窗；不會僅憑數字 PID 或程序組就去殺掉未知程序。

守護程序配置的持久化Copy Anchor Link

守護程序側的常用配置也可以寫入 ~/.multica/config.json，不必依賴 shell 環境變數；命名 profile 的配置檔案在 ~/.multica/profiles/<name>/config.json：

multica config set poll_interval 10s
multica config show

支援的鍵：

幾條取值規則：

• duration 類鍵接受正的 Go duration（如 10s、2h），0s 和負值會被拒絕。唯一例外是 agent_timeout：0s 合法，表示明確關閉執行時限。
• 傳空字串清除已持久化的值，回到環境變數或內建預設，例如 multica config set poll_interval ""。
• max_concurrent_tasks 要求非負整數。
• 相對的 workspaces_root 值在儲存時會轉換為絕對路徑。

觀測與統計Copy Anchor Link

首方自託管遙測每天按 UTC 傳送一份部署級快照，固定且不可配置的地址為 https://telemetry.multica.ai/v1/telemetry/events。快照只包含正式釋出版本、工作區數/去重成員數/活躍 AI 代理數/過去 24 小時活躍守護程序數的分桶，過去 24 小時執行的開始、完成、失敗和取消總數，以及過去 1、7、28 個完整 UTC 日內登入後開啟過網頁端或桌面端的成員數、親自發起過 AI 代理執行（分配、@、評論、聊天、手動執行或重跑；不含 autopilot 和 AI 代理之間的委派）的成員數的分桶。成員只在本部署內計數，不會被識別。不會傳送名稱、信箱或網域、IP、業務識別符號、主機或裝置資訊、程式碼倉庫、模型或 plugin、prompt/output、評論或聊天、檔案路徑、token/費用、憑據、錯誤文字、stack 或日誌。此資料只用於瞭解自託管版本採用、部署規模區間、聚合使用量與成員活躍情況，不用於計費、授權、認證或安全決策。

DO_NOT_TRACK 與 ANALYTICS_DISABLED 相互獨立：前者控制這份首方匿名快照，後者控制可選的 PostHog 整合。

接下來Copy Anchor Link

• 登入與註冊 — 登入方式與註冊限制。
• 故障排查 — 部署問題的症狀排查。
• 守護程序與執行時 — 守護程序側的對應配置。