环境变量

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

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

生产环境最小配置

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 与数据库

在 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。

邮件与登录

Resend

SMTP

只要 SMTP_HOST 非空，SMTP 就会优先于 Resend。

Google OAuth

注册范围

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

附件存储

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

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。

服务端 LLM

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

API key 与 base URL 都为空时，服务端 LLM 生成关闭，调用方会使用本地回退逻辑。

守护进程配置

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

各 AI 编程工具可以使用 MULTICA_<PROVIDER>_PATH 和 MULTICA_<PROVIDER>_MODEL 覆盖命令路径与默认模型。QwenPaw 是例外：它没有 MULTICA_QWENPAW_MODEL，因为 Melso 不会向它传模型，详见 AI 编程工具对比。DeepSeek Harness 支持 MULTICA_DSH_PATH 和 MULTICA_DSH_MODEL（取值为 dsh 模型目录中的模型 id，例如 deepseek-official/deepseek-chat）。全机默认参数 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：

melso config set poll_interval 10s
melso config show

支持的键：

几条取值规则：

• duration 类键接受正的 Go duration（如 10s、2h），0s 和负值会被拒绝。唯一例外是 agent_timeout：0s 合法，表示明确关闭执行时限。
• 传空字符串清除已持久化的值，回到环境变量或内置默认，例如 melso config set poll_interval ""。
• max_concurrent_tasks 要求非负整数。
• 相对的 workspaces_root 值在保存时会转换为绝对路径。

观测与统计

接下来

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