环境变量

Multica 在进程启动时读取环境变量。修改后通常需要重启对应的 API、Web 或守护进程。Docker Compose 的 docker compose restart 不会重新读取 .env，要用 up -d 重建容器才能生效。

本页只列面向部署者的配置；测试变量和内部 task 变量不在这里展开。本页是分组参考；完整部署步骤见自托管快速上手。

生产环境最小配置

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

还需要选择一种验证码投递服务，否则验证码只会写入服务端日志。工作区邀请邮件仍需要 Resend 或 SMTP。

API 与数据库

在 Kubernetes 中设置 shutdown hold 时，terminationGracePeriodSeconds 要大于 hold 与实际退出所需时间之和。

对外地址与浏览器访问

前端和 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。

验证码与登录

飞书验证码 Webhook

只要任一飞书配置存在，所有登录验证码就只会发送到飞书，配置或发送失败时不会回退到邮件。两个变量都必须设置。工作区邀请邮件仍使用 Resend 或 SMTP。

Resend

SMTP

两个飞书配置都为空时，只要 SMTP_HOST 非空，SMTP 就会优先于 Resend。

Google OAuth

注册范围

白名单的准确判断顺序见登录与注册。

附件存储

没有设置 S3_BUCKET 时，Multica 使用本地磁盘。

S3 或兼容存储

内网 MinIO 等 endpoint 无法被浏览器直接访问时，使用 ATTACHMENT_DOWNLOAD_MODE=proxy。

本地磁盘

CloudFront

Redis 与限流

反向代理后的部署需要填写真实代理网段。不要直接信任所有来源，否则客户端可以伪造转发 IP。

认证限流需要配置 REDIS_URL；未配置时，启动日志会提示认证限流已关闭。邀请限流在没有 Redis 时仍使用进程内存，配置 Redis 后则在多个副本间共享额度。如果已配置的 Redis 临时不可用，认证限流仍选择放行，而邀请创建会返回可重试的 503，不会在失去防护时发送邮件。

外部集成

不配置 GITHUB_APP_ID 和私钥时，PR 仍会正常关联、镜像和触发合并转 done，但卡片上不显示 CI 与可合并状态，"从 GitHub 选择"仓库入口也会禁用。

配置步骤见 GitHub 集成、飞书 Bot、Slack Bot和 Telegram Bot。

服务端 LLM

这组配置用于服务端的辅助生成能力，例如对话标题；它不是智能体 task 时使用的 AI 编程工具凭据。

MULTICA_LLM_MAX_RETRIES 是重试策略的唯一配置源。不设置时使用默认的 2 次；设为 0 表示每次调用只发一个请求；设为 1–5 表示最多重试这么多次。它是上限而不是配额：只有可重试的失败才会消耗它，请求成功或调用方自身的超时都会让调用提前结束。其它取值（负数、非数字、大于 5）会让服务启动失败，而不是被静默纠正。上限是一个延迟预算：退避从 0.5s 开始翻倍，上限 8s，更大的预算会超出调用方自身的超时，把可重试的失败变成超时失败。重试覆盖连接失败以及 HTTP 408、409、429 和 5xx；其余 4xx 直接返回。服务启动时会以 llm retry policy 打印生效策略，其中不包含任何凭据。

有两个功能会使用这一层，它们都会把聊天内容发送到你配置的 endpoint：

• 对话标题自动生成 —— 发送新对话中用户的第一条消息，原文发送。附件不会包含在内。
• 后续提问建议（智能体回复下方的按钮）—— 发送对话末尾的内容：最多 6 条消息，其中被追问的那条回复上限 3000 字符，更早的每条上限 800 字符。

API key 与 base URL 都为空时，这一层关闭，不会发出任何上游请求——上面两个功能都不再发送内容。如果你的政策不允许这一层把聊天内容发到部署之外，这就是受支持的配置方式：对话继续使用客户端根据第一条消息生成的标题，后续提问按钮不再出现，其余功能不受影响。

守护进程配置

下面的变量在运行智能体的电脑上读取，不是在 API 容器中读取。

守护进程注入智能体 task 的内部上下文见 Task 运行时环境。

各 AI 编程工具可以使用 MULTICA_<PROVIDER>_PATH 覆盖命令路径；支持模型覆盖的工具还可以使用 MULTICA_<PROVIDER>_MODEL。QwenPaw 和 MiniMax Code 没有模型变量，因为 Multica 不会向它们传模型；MiniMax Code 的路径变量是 MULTICA_MCODE_PATH。详见 AI 编程工具对比。DeepSeek Harness 支持 MULTICA_DSH_PATH 和 MULTICA_DSH_MODEL（取值为 dsh 模型目录中的模型 id，例如 deepseek-official/deepseek-chat）。ZeroClaw 支持 MULTICA_ZEROCLAW_PATH，但没有模型变量；模型由 ZeroClaw 的智能体配置管理。全机默认参数 MULTICA_<PROVIDER>_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

优先级为命令行 flag → 环境变量 → ~/.multica/config.json → 内置默认。watchdog 的行为见守护进程与运行时。

守护进程配置的持久化

守护进程侧的常用配置也可以写入 ~/.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 值在保存时会转换为绝对路径。

观测与统计

接下来

• 登录与注册 — 登录方式与注册限制。
• 故障排查 — 部署问题的症状排查。
• 守护进程与运行时 — 守护进程侧的对应配置。