跳转到主要内容
通常只需将密钥写入 .env,再在设置页中选择模型。需要调整默认行为时,在 config.{ENV}.yaml 中填写要覆盖的配置项。

配置文件

配置优先级由高到低为:环境变量、覆盖文件、config.devices.yaml 与 config.llm.yaml、config.yaml。字典不会跨文件合并:覆盖文件里设置的键会替换整个值,所以在覆盖文件里设置 EMAIL_PREDEFINE_CODES 会替换掉演示账号,而不是在其后追加。 ENV 用于选择配置文件和标记日志。要启用生产模式,必须设置 PRODUCTION;仅将环境命名为 prod 不会改变运行模式。 覆盖文件中,名称含有 _KEY、_PASSWORD、_PASS、_PWD、_SECRET、_SK 或 _TOKEN 的值,会用 .env 里的 CONFIG_ENCRYPTION_KEY 加密保存。

模型

聊天、文档处理等功能可以使用云端模型,也可以使用本地模型。首次设置页(尚未设置模型时 ./deploy.sh 会打印它的链接;之后在设置 › 模型中)把两种选择之一加密保存到数据库,无需重启即可生效,并且从不覆盖 .env 中已设置的值。保存需要 .env 中的 SETUP_TOKEN;一旦设置过模型,还需要已登录的会话。

模型厂商密钥

把下列任意一个写进 compose.yaml 旁边的 .env,然后使其生效:
docker compose restart 不会重新读取 .env,up -d 才会。./deploy.sh 会把其环境中给出的密钥写进 .env(OPENROUTER_API_KEY=sk-or-... ./deploy.sh),所以首次运行不需要第二步。 每个密钥为三个用途各选一个模型:对话(模型选择器)、视觉(化验单照片与扫描页)、文本(指标抽取、文件标题、摘要与日志句子)。 开头的表格列出了每个密钥选中的模型,以及各密钥的申请地址。模型名可以自己改:首次设置页在密钥旁显示它,在 .env 中则由每个条目以 model_env 命名的变量(例如 OPENROUTER_CHAT_MODEL)替换;厂商模型会先用一次真实请求验证再保存。

本地模型

没有密钥时,config.llm.yaml 的 local、local-utils 与 local-ocr 条目从你机器上一个 OpenAI 兼容的服务为所有用途提供模型。Mirobody 自带预设的运行时是 llama.cpp 的 llama-server:首次设置页会找到这个服务,列出它提供的模型,并加载你选的规模。同样的选择写在 .env 中是:
UTILS_OCR_MODEL 是第四个用途:一个文档 OCR 模型,先于其他模型读取化验单照片与扫描页,其中的表格按表头规则读取、不经模型。随仓库提供的值是 local-ocr 条目。.env 中的 HF_ENDPOINT 可把一次性的模型下载指向 Hugging Face 镜像。 .env 中的厂商密钥优先于本地条目,只要密钥还在,首次设置页就会拒绝100% 在本机运行。要在保留密钥的同时使用本地模型:

doctor 报告

mirobody doctor 打印找到的密钥与本地模型服务、每个用途选中的条目,并对没有可用模型的用途给出修复方法。--probe 向每个用途发送一次真实请求(一次工具调用、一个按 schema 约束的回答、一张图片、OCR 的两遍识别),并检查本地服务运行的确实是条目中指定的模型;在厂商那里要花几个 token,在本地模型上要花几分钟。
服务端与 worker 启动时也会在日志中输出同样的报告。

更换模型

  • 让某个用途改用另一条配置。 UTILS_VISION_MODEL、UTILS_TEXT_MODEL 和 UTILS_OCR_MODEL 可以取一个条目名、一组条目名(取第一个有密钥或有服务的)、provider/model 字符串,或一条内联配置。同名环境变量优先于文件,例如 UTILS_VISION_MODEL=qwen-utils。
  • 修改对话的默认模型。 DEFAULT_MODEL 指定一个 MODELS 条目;不设置时,默认取第一个有密钥或有服务的条目。
  • 让某个密钥经由另一个网关。 在 .env 中设置 <PREFIX>_BASE_URL(PREFIX 是密钥名去掉 _API_KEY),读取该密钥的所有条目都会改用另一个兼容 OpenAI 的端点,例如 OPENROUTER_BASE_URL。Anthropic 自己的 SDK 也读取 ANTHROPIC_BASE_URL,如果机器上已经为其他工具设置了它,Mirobody 也会随之改道;mirobody doctor 会打印每个用途实际解析到的端点。
  • 接入其他厂商。 在 config.llm.yaml 的 MODELS 中新增一条,写明 llm_type: openai、base_url、model,并把 api_key 设为保存密钥的 .env 变量的名称。用于视觉的条目必须声明 supports_image: true。请直接加在 config.llm.yaml 中:覆盖文件里的 MODELS 会替换整张表。

部署设置

决定 agent 行为的键见内置 Agent。

密钥

PG_ENCRYPTION_KEY 与 CONFIG_ENCRYPTION_KEY 是两个不同的值:前者加密存储的内容,例如对话消息与上传的文件。DATABASE_DECRYPTION_KEY(十六进制)加密各 provider 保存的设备凭据。不要在不同环境之间复制这些密钥。自行生成这些密钥并迁移到另一台主机的方法,见在服务器上部署。

扩展目录

引擎启动时扫描三组目录。新增一个目录即可扩展引擎,无需修改代码包。 在覆盖文件中设置其中任何一项都会替换整个列表,所以请把默认条目和你自己的目录一起写上。已安装的包也可以通过 mirobody.tools、mirobody.agents 与 mirobody.providers 入口点扩展这三项。 所有配置键的完整说明见 。