跳转到主要内容
所有配置都通过 .env 完成。复制 example.env 并填入你的值： 
cp example.env .env

​
配置级别

每个集成都有一个配置级别，表示其重要性：
级别含义未配置时的行为
必需核心系统依赖系统将出错 — 聊天和主要功能将无法工作
推荐重要功能启用器优雅降级 — 该功能明显不可用，但系统继续运行
可选增强功能透明降级 — 系统运行正常，该功能不存在
注意：管理员配置的模型（管理员 → 模型页面）可以替代 LLM 环境变量。健康检查会考虑两个来源。

​
前端（仅本地开发）

前端有一个仅用于本地开发的独立环境文件：frontend/.env.local。
此文件在 Docker 中不使用。 在 Docker 容器内，Next.js 在内部将 /api/* 代理到 Python 后端（端口 8000 是容器内部的），因此不需要前端环境文件。
对于本地开发，默认设置开箱即用 — 除非你的后端运行在非默认端口，否则不需要创建 frontend/.env.local。 如果需要覆盖，请手动创建 frontend/.env.local： 
echo 'NEXT_PUBLIC_API_URL=http://localhost:9000' > frontend/.env.local
变量默认值描述
NEXT_PUBLIC_API_URLhttp://localhost:8000 （自动）浏览器用于直接 API 调用（OAuth 重定向、流式传输）的后端 URL。如果未设置，则从 window.location 自动检测 — 仅当后端在本地运行于非标准端口时才需覆盖。
构建时注意：NEXT_PUBLIC_* 变量在 pnpm build 时被烘焙到 JS 包中。在运行时更改它们（例如通过根目录 .env）无效 — 这就是为什么它们仅存在于本地开发的 frontend/.env.local 中。

​
LLM（必需）

变量必需默认值描述
LLM_API_KEY是—LLM 提供商的 API 密钥
LLM_BASE_URL否https://api.openai.com/v1任何 OpenAI 兼容 API 的基础 URL
LLM_MODEL否gpt-4o主模型 — 用于规划、分析和 ReAct 智能体
FAST_LLM_MODEL否（回退到 LLM_MODEL）快速模型 — 用于 DAG 步骤执行（更便宜、更快）
LLM_TEMPERATURE否0.7默认采样温度
LLM_CONTEXT_SIZE否128000主 LLM 的上下文窗口大小
LLM_MAX_OUTPUT_TOKENS否64000主 LLM 每次调用的最大输出 token 数
FAST_LLM_API_KEY否（回退到 LLM_API_KEY）快速模型提供商的 API 密钥。当快速模型由不同的提供商托管时使用
FAST_LLM_BASE_URL否（回退到 LLM_BASE_URL）快速模型提供商的基础 URL
FAST_LLM_TEMPERATURE否（回退到 LLM_TEMPERATURE）快速模型的采样温度
FAST_LLM_CONTEXT_SIZE否（回退到 LLM_CONTEXT_SIZE）快速 LLM 的上下文窗口大小
FAST_LLM_MAX_OUTPUT_TOKENS否（回退到 LLM_MAX_OUTPUT_TOKENS）快速 LLM 每次调用的最大输出 token 数
LLM_REASONING_EFFORT否（禁用）支持的模型的扩展思考级别（OpenAI o 系列、Gemini 2.5+、Claude）。值：low、medium、high。LiteLLM 会自动将其转换为每个提供商的原生格式。模型的思维链在 UI”思考”步骤中显示。
LLM_REASONING_BUDGET_TOKENS否（从努力级别自动计算）Anthropic 思考的显式 token 预算（最少 1024）。对于 OpenAI/Gemini，直接使用努力级别。仅在设置 LLM_REASONING_EFFORT 时有效。
LLM_JSON_MODE_ENABLED否trueresponse_format=json_object 的全局开关。如果您的提供商拒绝 LiteLLM 的助手预填充注入（例如 AWS Bedrock 中继 → 第 2+ 个智能体迭代上的 ValidationException），请设置为 false。禁用时，结构化调用跳过 JSON 模式，回退到纯文本正则表达式提取 — 无质量损失。适用于所有模型（ENV 配置和管理员配置）。
LLM_TOOL_CHOICE_ENABLED否true结构化输出提取中强制 tool_choice 的全局开关（级别 1 — 原生函数调用）。如果您的模型在强制工具选择时返回错误（例如拒绝 tool_choice='specified' 的思考模式模型），请设置为 false。禁用时，结构化调用跳过原生 FC，从 JSON 模式开始。在设置 → 模型 → 高级中提供按模型覆盖。
REASONING_LLM_MODEL否（回退到 LLM_MODEL）推理层的模型名称。用于需要深度分析的任务（例如 DAG 规划、计划分析）
REASONING_LLM_API_KEY否（回退到 LLM_API_KEY）推理模型提供商的 API 密钥
REASONING_LLM_BASE_URL否（回退到 LLM_BASE_URL）推理模型提供商的基础 URL
REASONING_LLM_TEMPERATURE否（回退到 LLM_TEMPERATURE）推理模型的采样温度
REASONING_LLM_CONTEXT_SIZE否（回退到 LLM_CONTEXT_SIZE）推理模型的上下文窗口大小
REASONING_LLM_MAX_OUTPUT_TOKENS否（回退到 LLM_MAX_OUTPUT_TOKENS）推理模型每次调用的最大输出 token 数
REASONING_LLM_EFFORT否（回退到 LLM_REASONING_EFFORT）推理模型层的推理努力级别。值：low、medium、high
REASONING_LLM_BUDGET否（回退到 LLM_REASONING_BUDGET_TOKENS）推理的 token 预算（主要用于 Anthropic）。覆盖推理层的自动计算预算
LLM_SUPPORTS_VISION否true （乐观）控制是否尝试 ENV 模式文档 OCR（通过 MarkItDown + markitdown-ocr）。仅在管理员 → 模型中未配置活跃模型组时适用（纯 ENV 模式）。当默认 true 生效时，convert_to_markdown 和 RAG 摄取假设 LLM_MODEL 支持视觉并调用它进行图像 OCR — 这对所有常见选择（gpt-4o、claude-3-5-sonnet、gemini-1.5-pro/flash）都是正确的行为。当您的 ENV 配置的 LLM_MODEL 不支持视觉时（例如 deepseek-v3、qwen-chat、llama-3.1、gpt-3.5-turbo、o1-mini），将其设置为 false 以跳过失败的视觉调用并直接进行纯文本提取。当管理员 → 模型面板中存在活跃模型组时，此标志被忽略，组的 supports_vision 标志接管 — 管理员策划的选择始终是数据库模式中的真实来源。
解析顺序：用户偏好 → 管理员模型（数据库）→ ENV 回退。如果在管理员 → 模型中配置了角色为”通用”的管理员模型，这些 ENV 变量仅作为回退。健康检查考虑两个来源。

​
MarkItDown OCR 分辨率

convert_to_markdown 内置工具和 RAG 摄取管道都使用 Microsoft 的 MarkItDown + 官方 markitdown-ocr 插件从文档中提取文本 — 包括在有支持视觉的 LLM 可用时对嵌入图像和扫描 PDF 页面进行 OCR。 视觉 LLM 分辨率顺序（首次匹配获胜）：
#来源优先级原因
1智能体的主要 LLM（如果 supports_vision=True）一致性：相同的 API 密钥、相同的计费桶、与对话相同的速率限制池。
2活跃的模型组 → 快速模型（如果 supports_vision=True）快速模型（gpt-4o-mini、claude-haiku、gemini-1.5-flash）是理想的 OCR 工具 — 便宜、低延迟、通常支持多模态。
3活跃的模型组 → 通用模型（如果 supports_vision=True）当主要模型不在组中时的质量备选方案。
4ENV 主要 LLM（LLM_MODEL）纯 ENV 模式的乐观备选方案。仅在不存在活跃模型组时采用。由 LLM_SUPPORTS_VISION 控制。
推理模型永远不会被优先选择用于 OCR。 推理层级（o1、o3-mini、DeepSeek-R1）历来缺乏视觉支持，本身也不是 OCR 的合适工具 — OCR 是一项感知任务，而非推理任务。如果工作区仅有一个支持视觉的推理模型（supports_vision=True），它仍会通过主要 LLM 路径被选中，但解析器不会主动将其排名高于快速/通用模型。 零回归备选方案：当在任何级别都找不到支持视觉的模型时，OCR 会被静默禁用，MarkItDown 以纯文本模式运行。Word/PowerPoint/Excel 嵌入图像 OCR 变为不可用（与此功能发布前相同），但所有其他文本提取（标题、表格、段落文本）继续正常工作。不存在添加此功能使提取效果比之前行为更差的情况。 非 OpenAI 提供商（Anthropic、Google Gemini 等） 得到透明支持：解析的 LLM 被包装在 LiteLLMOpenAIShim 中，该 shim 将 chat.completions.create(...) 调用路由通过 litellm.completion()，后者处理提供商特定的消息格式转换（例如 Anthropic 的 source.type="base64" 图像块）。一个 shim 覆盖 LiteLLM 支持的每个提供商 — 添加新提供商在 FIM One 中零代码更改成本。

​
扩展思维（推理）

当设置 LLM_REASONING_EFFORT 时，FIM One 启用模型的扩展思维能力，使内部思维链在 UI 的”思维”步骤中显示。FIM One 使用 LiteLLM 自动将推理努力参数转换为每个提供商的原生格式。

​
支持的提供商

提供商LLM_BASE_URL工作原理返回推理内容?
OpenAI (o1 / o3 / o4-mini)https://api.openai.com/v1reasoning_effort 原生发送是
Anthropic (Claude 3.7+)https://api.anthropic.com/v1/LiteLLM 通过原生 Anthropic API 路由，使用 thinking 参数是
Google Gemini (2.5+)https://generativelanguage.googleapis.com/v1beta/openai/reasoning_effort 在兼容端点上发送是
LiteLLM 从 LLM_BASE_URL 自动检测提供商，并将其映射到正确的 API 格式。未知 URL 被视为 OpenAI 兼容。

​
重要注意事项

第三方代理 / 自定义端点不保证兼容。 如果您的 LLM_BASE_URL 指向第三方 API 代理（例如 OpenRouter、one-api、自定义网关），LiteLLM 将尝试根据 URL 正确路由。但是，如果您的代理需要非标准格式，推理可能无法按预期工作。请查阅代理的文档以了解其预期的参数格式。

​
推理时的温度约束

某些提供商在启用推理时会施加温度限制：
  • Anthropic: 启用扩展思考时需要 temperature=1。如果使用 Anthropic 的扩展思考功能，你必须设置 LLM_TEMPERATURE=1 — 当启用思考时，Anthropic 会拒绝其他值。
  • OpenAI GPT-5.x: 始终仅支持 temperature=1。LiteLLM 的 drop_params 过滤会自动处理此问题 — 不支持的温度值会被静默丢弃。对于 GPT-5.x，无需用户采取任何操作。

​
LLM_REASONING_BUDGET_TOKENS 的工作原理

此变量主要对 Anthropic 路径有意义。设置时，它会覆盖自动计算的预算，并通过 LiteLLM 作为 thinking 参数中的 budget_tokens 发送。未设置时，预算从 LLM_MAX_OUTPUT_TOKENS x 努力比率派生：
LLM_REASONING_EFFORT预算比率示例 (max_tokens = 64000)
low20%12,800 tokens
medium50%32,000 tokens
high80%51,200 tokens
最小预算为 1,024 tokens（Anthropic 的硬性最小值）。 对于 OpenAI 和 Gemini，提供商根据 reasoning_effort 级别在内部处理 token 分配 — LLM_REASONING_BUDGET_TOKENS 无效。

​
智能体执行

​
ReAct 智能体

变量必需默认值描述
REACT_MAX_ITERATIONS否20每个 ReAct 请求的最大工具调用迭代次数。更高的值 = 更彻底但更慢且成本更高
REACT_MAX_TURN_TOKENS否0紧急断路器：单个 ReAct 轮次的最大累积 token 数（所有迭代的提示词 + 完成）。默认 0 = 无限制。这不是用于日常 token 控制的 — 请使用按用户的 token_quota。这是针对极端场景（如智能体陷入无限工具调用循环）的最后手段安全阀。达到此限制会中止任务执行，浪费所有已消耗的 token，并返回不完整的结果。除非您有特定的失控智能体问题需要控制，否则保持为 0
REACT_TOOL_SELECTION_THRESHOLD否12当注册的工具总数超过此阈值时，轻量级 LLM 调用会在每个请求前选择最相关的子集
REACT_TOOL_SELECTION_MAX否6智能选择后保留的最大工具数（仅在工具数超过 REACT_TOOL_SELECTION_THRESHOLD 时有效）
REACT_SELF_REFLECTION_INTERVAL否6每 N 次工具调用后注入一个自我反思提示词，帮助智能体纠正方向并避免循环
REACT_TOOL_OBS_TRUNCATION否8000合成最终答案时每个工具观察的最大字符数。更高的值以更多 token 为代价保留更多结构化数据（JSON、表格）
REACT_TOOL_RESULT_BUDGET否40000单个会话中所有工具结果的聚合 token 预算。当工具结果 token 总数超过此上限时，新结果会被截断并显示通知。防止来自大型 API 响应的上下文膨胀（例如，5 个连接器调用各返回 8K）。设置为 0 以禁用上限
REACT_COMPLETION_CHECK_SKIP_CHARS否800当智能体的最终答案超过此字符数时，跳过答案后完成检查 LLM 调用。长详细答案不需要”我是否遗漏了什么？“验证往返。设置较低值以更积极地跳过；设置为非常大的值以始终运行检查
REACT_CYCLE_DETECTION_THRESHOLD否2当相同工具连续使用相同参数调用此次数时，会注入一个确定性警告，告诉智能体尝试不同的方法。与依赖 LLM 注意循环的自我反思不同，这是一个基于哈希的检查，无法绕过。也适用于 DAG 步骤
REACT_COMPLETION_CHECK_MIN_TOOLS否3完成检查清单触发前的最少工具调用数。简单任务（1-2 次工具调用）跳过验证以避免不必要的延迟。设置为 1 以始终进行验证。也适用于 DAG 步骤
REACT_TURN_PROFILE_ENABLED否true发出每轮阶段级别的计时日志（memory_load、compact、tool_schema_build、llm_first_token、llm_total、tool_exec）。每轮一行结构化日志。设置为 false 以完全禁用分析（零开销）
LLM_RATE_LIMIT_PER_USER否true使用按用户键控的速率限制桶而不是单个进程全局桶。防止一个嘈杂的用户耗尽同一工作进程上的所有其他用户。底层速率硬编码为每个桶 60 请求/分钟和 100K token/分钟 — 此设置仅控制桶是共享（全局）还是分区（按用户）。设置为 false 以恢复到旧版全局桶（不推荐）

​
DAG 规划器

变量必需默认值描述
MAX_CONCURRENCY否5DAG 执行器中的最大并行步骤数
DAG_STEP_MAX_ITERATIONS否15每个 DAG 步骤内的最大工具调用迭代次数
DAG_STEP_TIMEOUT否600步骤执行超时时间（秒）。超过此时间的步骤被标记为失败，其依赖步骤将级联跳过
DAG_MAX_REPLAN_ROUNDS否3当目标未达成时的最大自主重新规划尝试次数。用户中断（注入）次数不受限制，不计入此预算
DAG_REPLAN_STOP_CONFIDENCE否0.8当智能体对目标不可达成的置信度超过此阈值时停止重试（0.0 = 永不提前停止，1.0 = 任何失败时停止）
DAG_VERIFY_TRUNCATION否2000发送给步骤验证器 LLM 进行质量判断的步骤输出最大字符数
DAG_ANALYZER_TRUNCATION否10000为执行后分析器格式化时每个步骤结果的最大字符数
DAG_REPLAN_RECENT_TRUNCATION否500构建重新规划上下文时最近一轮步骤结果的最大字符数
DAG_REPLAN_OLDER_TRUNCATION否200构建重新规划上下文时较早轮次步骤结果的最大字符数。较早的轮次会更激进地截断以节省上下文
DAG_TOOL_CACHE否true在单个 DAG 执行中缓存相同的工具调用。仅缓存明确标记为 cacheable 的工具（如搜索、知识检索等只读工具）。设置为 false 可完全禁用缓存
DAG_STEP_VERIFICATION否false每个 DAG 步骤后的通用 LLM 质量检查。失败时，步骤将根据反馈重试一次。默认关闭 — 在每个步骤上增加延迟，很少需要；大多数步骤输出无需重新检查即可接受。仅在观察到频繁的低质量步骤结果时使用
DAG_CITATION_VERIFICATION否true专业领域步骤的引文准确性检查。前置条件：查询必须首先由 LLM 领域分类器分类为专业领域（参见 ESCALATION_DOMAINS）。当检测到该领域且此标志为 true 时，每个完成的步骤都会被扫描以查找法律/医学/财务引文，并验证其准确性 — 捕捉幻觉的文章编号、虚构的案例参考和不正确的监管引文。如果领域分类返回 null（通用查询），则无论此设置如何，引文验证都不会运行
DAG_CITATION_VERIFY_TRUNCATION否6000发送给引文验证提示的步骤结果最大字符数

​
领域分类

控制独立的基于LLM的领域检测层，在ReAct和DAG执行之前运行。当查询被分类为专家领域时，系统激活领域感知功能：升级到推理模型、领域特定的SOP指令和引用验证（仅DAG）。
变量必需默认值描述
ESCALATION_DOMAINS否legal,medical,financial,tax,compliance,patent专家领域的逗号分隔列表。快速LLM根据此列表对每个查询进行分类。匹配时，系统：(1) 升级到推理模型以获得更高的准确性，(2) 注入领域特定的SOP指令（例如在写入前通过搜索验证引用），(3) 为DAG步骤启用引用验证。根据需要添加自定义领域（例如 legal,education,construction）

​
上下文守卫

控制自动上下文窗口管理，防止对话超过模型的限制。
变量必需默认值描述
CONTEXT_GUARD_DEFAULT_BUDGET否32000上下文窗口管理的默认令牌预算。当对话超过此值时，较早的消息会被压缩
CONTEXT_GUARD_MAX_MSG_CHARS否50000任何单条消息的硬字符限制。超过此限制的消息会被截断作为安全网
CONTEXT_GUARD_KEEP_RECENT否4压缩对话历史时保留的最近消息数

​
智能体工作区

变量必需默认值描述
WORKSPACE_OFFLOAD_THRESHOLD否8000当工具输出超过这么多字符时，它会被保存到工作区文件中，并将截断的预览注入到对话上下文中
WORKSPACE_PREVIEW_CHARS否2000截断的工作区引用中包含的预览字符数
WORKSPACE_CLEANUP_MAX_HOURS否72超过这么多小时的工作区文件符合自动清理的条件

​
系统

变量必需默认值描述
SYSTEM_PROMPT_RESERVE——已移除。 之前从上下文预算中减去固定的 4K 保留用于系统提示。这导致了重复计算，因为 ContextGuard 在估计消息列表令牌时已经包含了系统提示。预算公式现在简单为 context_size - max_output_tokens，系统提示的实际大小动态计算

​
Web 工具（可选）

变量必需默认值描述
JINA_API_KEY否—Jina API 密钥。当未设置特定服务密钥时，作为搜索、获取、嵌入和重排序的共享备用方案。在 jina.ai 获取
TAVILY_API_KEY否—Tavily 搜索 API 密钥（如果设置且 WEB_SEARCH_PROVIDER 未设置，则自动选择）
BRAVE_API_KEY否—Brave 搜索 API 密钥（如果设置且 WEB_SEARCH_PROVIDER 未设置，则自动选择）
EXA_API_KEY否—Exa 搜索 API 密钥（如果设置且 WEB_SEARCH_PROVIDER 未设置，则自动选择）。在 exa.ai 获取
WEB_SEARCH_PROVIDER否jina搜索提供商选择器：jina / tavily / brave / exa
WEB_FETCH_PROVIDER否jina（如果密钥已设置，否则 httpx）获取提供商：jina（使用 Jina Reader API）/ httpx（直接 HTTP 请求，无需 API 密钥）
快速开始提示：仅设置 JINA_API_KEY 即可同时启用网页搜索、网页获取、嵌入和重排序——一个密钥，四项服务。您可以使用下面的变量单独覆盖每项服务。

​
RAG 与知识库（推荐）

​
嵌入

嵌入将文本转换为向量以进行知识库搜索。FIM One 使用标准的 OpenAI 兼容 /v1/embeddings 端点，因此它适用于任何公开此接口的提供商 — 不仅仅是 Jina。
变量必需默认值描述
EMBEDDING_API_KEY否(回退到 JINA_API_KEY)嵌入提供商的 API 密钥
EMBEDDING_BASE_URL否https://api.jina.ai/v1嵌入提供商的基础 URL
EMBEDDING_MODEL否jina-embeddings-v3模型标识符
EMBEDDING_DIMENSION否1024向量维度
提供商示例 — 只需设置这三个变量即可切换：
提供商EMBEDDING_BASE_URLEMBEDDING_MODELEMBEDDING_DIMENSION
Jina (默认)https://api.jina.ai/v1jina-embeddings-v31024
OpenAIhttps://api.openai.com/v1text-embedding-3-small1536
Voyagehttps://api.voyageai.com/v1voyage-31024
Ollama (本地)http://localhost:11434/v1nomic-embed-text768
更改嵌入模型或维度会使所有现有知识库向量失效。 旧向量是在不同的嵌入空间中计算的 — 检索准确性将无声地降低。切换后，您必须重建所有知识库索引。

​
检索

变量必需默认值描述
RETRIEVAL_MODE否groundinggrounding（带引用和置信度评分的完整管道）或 simple（基础 RAG）

​
重排器

重排器对检索到的文档重新评分以提高相关性。支持三个提供商 — 通过 RERANKER_PROVIDER 选择或让系统从可用的 API 密钥自动检测。
变量必需默认值描述
RERANKER_PROVIDER否(自动检测)jina / cohere / openai。如果未设置：如果设置了 COHERE_API_KEY 则使用 Cohere，否则使用 Jina
RERANKER_MODEL否jina-reranker-v2-base-multilingual模型标识符（适用于 Jina 和 OpenAI 提供商）
COHERE_API_KEY否—Cohere API 密钥（当设置且 RERANKER_PROVIDER 未设置时自动选择 Cohere 重排器）
COHERE_RERANKER_MODEL否rerank-multilingual-v3.0Cohere 特定的重排器模型
Jina 使用 JINA_API_KEY（来自上面的 Web 工具）。OpenAI 复用 LLM_API_KEY / LLM_BASE_URL — 无需额外密钥。Cohere 需要其自己的 COHERE_API_KEY。
重排器是可选的 — 知识库搜索可以在不使用它的情况下使用融合评分。对于知识库功能，推荐使用嵌入。

​
向量存储

变量必需默认值描述
VECTOR_STORE_DIR否./data/vector_storeLanceDB 向量存储数据的目录（基于文件，无需外部服务）

​
代码执行

变量必需默认值描述
CODE_EXEC_BACKEND否locallocal（直接主机执行）或 docker（隔离容器）
DOCKER_PYTHON_IMAGE否python:3.11-slimPython 执行的 Docker 镜像
DOCKER_NODE_IMAGE否node:20-slimNode.js 执行的 Docker 镜像
DOCKER_SHELL_IMAGE否python:3.11-slimshell 执行的 Docker 镜像
DOCKER_MEMORY否（Docker 默认值）每个容器的 RAM 上限（例如 256m、512m、1g）
DOCKER_CPUS否（Docker 默认值）每个容器的 CPU 配额（例如 0.5、1.0）
SANDBOX_TIMEOUT否120默认执行超时时间（秒）
DOCKER_HOST_DATA_DIR否（未设置）./data 卷挂载的主机端绝对路径。DooD（Docker-outside-of-Docker）部署需要此项；docker-compose.yml 通过 ${PWD}/data 自动设置。
安全性：local 模式直接在主机上运行 AI 生成的代码。对于面向互联网或多用户部署，始终设置 CODE_EXEC_BACKEND=docker。

​
工具制品

工具执行（代码执行、模板渲染、图像生成）产生的文件的大小限制。
变量必需默认值描述
MAX_ARTIFACT_SIZE否10485760 (10 MB)单个制品文件的最大大小（字节）
MAX_ARTIFACTS_TOTAL否52428800 (50 MB)每个会话的制品总大小上限（字节）

​
文档处理（可选）

控制上传的 PDF/DOCX 文件如何被处理以供 LLM 使用。具有视觉能力的模型（GPT-4o、Claude 3/4、Gemini）可以接收渲染后的 PDF 页面作为图像，以获得更高的保真度。
变量必需默认值描述
DOCUMENT_PROCESSING_MODE否autoauto（如果模型支持则使用视觉），vision（始终渲染页面），text（始终仅提取文本）
DOCUMENT_VISION_DPI否150PDF 页面渲染的 DPI。更高 = 更好的质量，更多 token
DOCUMENT_VISION_MAX_PAGES否20每个 PDF 渲染为图像的最大页数
注意：每个模型的视觉支持通过管理员 → 模型中的 supports_vision 开关进行配置。未明确设置时，系统会从模型名称自动检测视觉能力。

​
图像生成（可选）

变量必需默认值描述
IMAGE_GEN_PROVIDER否googlegoogle（Gemini 原生 API）或 openai（OpenAI 兼容 /v1/images/generations）
IMAGE_GEN_API_KEY否—Google AI Studio 密钥（google）或代理/OpenAI API 密钥（openai）
IMAGE_GEN_MODEL否gemini-3.1-flash-image-preview图像生成模型（例如 dall-e-3、gemini-nano-banana-2）
IMAGE_GEN_BASE_URL否（按提供商）Google：https://generativelanguage.googleapis.com/v1beta；OpenAI：https://api.openai.com/v1

​
电子邮件 (SMTP) (推荐)

当 SMTP_HOST、SMTP_USER 和 SMTP_PASS 都设置时，自动注册 email_send 内置工具。
变量必需默认值描述
SMTP_HOST条件—SMTP 服务器主机名
SMTP_PORT否465SMTP 端口
SMTP_SSL否sslTLS 模式：ssl (端口 465) / tls (STARTTLS，端口 587) / "" (纯文本)
SMTP_USER条件—SMTP 登录用户名
SMTP_PASS条件—SMTP 登录密码
SMTP_FROM否(使用 SMTP_USER)From 头中显示的发件人地址
SMTP_FROM_NAME否—From 头中显示的显示名称
SMTP_REPLY_TO否—Reply-To 地址；回复将发送到此处而不是 SMTP_FROM
SMTP_ALLOWED_DOMAINS否—逗号分隔的域名白名单 (例如 example.com,corp.io)；阻止列出域名之外的收件人
SMTP_ALLOWED_ADDRESSES否—逗号分隔的精确地址白名单；与 SMTP_ALLOWED_DOMAINS 结合使用；两者都未设置时允许任何收件人 (不推荐用于共享邮箱)

​
连接器

变量必需默认值描述
CONNECTOR_RESPONSE_MAX_CHARS否50000非数组 JSON / 纯文本连接器响应的最大字符数
CONNECTOR_RESPONSE_MAX_ITEMS否10当连接器响应为 JSON 数组时保留的最大数组项数
CREDENTIAL_ENCRYPTION_KEY否(未设置)用于连接器凭证 blob 的 Fernet 加密密钥。设置后，存储在 connector_credentials 中的身份验证令牌将被加密存储。如果未设置，凭证将以纯文本 JSON 形式存储（向后兼容）。更改此密钥将使所有现有加密凭证失效。
CONNECTOR_TOOL_MODE否progressive连接器工具如何暴露给智能体。progressive：单个 ConnectorMetaTool，带有 discover/execute 子命令（~30 tokens/连接器）。classic：每个操作一个工具（旧版，~250 tokens/操作）。
DATABASE_TOOL_MODE否progressive数据库连接器工具如何暴露给智能体。progressive：单个 DatabaseMetaTool，带有 list_tables/discover/query 子命令。legacy：每个数据库连接器每个操作一个工具（3 个工具）。
MCP_TOOL_MODE否progressiveMCP 服务器工具如何暴露给智能体。progressive：单个 MCPServerMetaTool，带有 discover/call 子命令。legacy：每个 MCP 服务器操作一个工具（原始单个工具）。

​
平台

变量必需默认值描述
DATABASE_URL否sqlite+aiosqlite:///./data/fim_one.db数据库连接字符串。SQLite（零配置）：sqlite+aiosqlite:///./data/fim_one.db。PostgreSQL（生产环境）：postgresql+asyncpg://user:pass@localhost:5432/fim_one。Docker Compose 自动配置 PostgreSQL。
JWT_SECRET_KEY否CHANGE_MEJWT 令牌签名的密钥。占位符值 CHANGE_ME（或任何旧版默认值）会在首次启动时触发自动生成安全的 256 位随机密钥，该密钥会写回到 .env。在生产环境中明确设置以保持令牌在重启和副本间的有效性。
CORS_ORIGINS否—逗号分隔的额外允许 CORS 源列表，超出默认 localhost 条目。当前端在非 localhost 域上运行时需要（例如 https://app.example.com）。
UPLOADS_DIR否./uploads上传文件的目录
MAX_UPLOAD_SIZE_MB否50最大文件上传大小（以兆字节为单位，后端强制执行）
NEXT_PUBLIC_MAX_UPLOAD_SIZE_MB否50前端 UI 中显示的最大文件上传大小。构建时变量 — 必须与 MAX_UPLOAD_SIZE_MB 匹配。
MCP_SERVERS否—MCP 服务器配置的 JSON 数组（需要 uv sync --extra mcp）
ALLOW_STDIO_MCP否false允许 stdio MCP 服务器。仅对可信的本地部署设置为 true
ALLOWED_STDIO_COMMANDS否npx,uvx,node,python,python3,deno,bunstdio MCP 服务器允许的基础命令的逗号分隔列表。仅在 ALLOW_STDIO_MCP=true 时有效
LOG_LEVEL否INFO日志级别：DEBUG / INFO / WARNING / ERROR / CRITICAL
REDIS_URL否—Redis 连接 URL，用于跨工作进程中断中继。当 WORKERS>1 时必需 — 没有它，中途中断/注入请求可能会命中不同的工作进程并无声地失败。由 Docker Compose 自动配置。
WORKERS否1Uvicorn 工作进程数。1 是安全的，不需要外部服务。对于生产多工作进程，使用 PostgreSQL（SQLite 是单写入器）。SQLite 适用于轻负载的本地开发。身份验证、OAuth 和文件操作完全支持多工作进程（基于 JWT）。Docker Compose 自动配置 PostgreSQL 和 Redis。
多工作进程检查清单（WORKERS>1）：
  • 停止（中止流） — 始终有效，无需额外配置（信号在同一 TCP 连接上传输）。
  • 注入（中途跟进） — 需要 REDIS_URL。没有 Redis，注入请求可能会落在没有正在运行的执行知识的不同工作进程上，导致无声失败。
  • 生产环境：使用 PostgreSQL（DATABASE_URL）。SQLite 的单写入器锁在并发写入下可能导致争用。
  • 本地开发：SQLite + 多工作进程对于轻度使用是可以的；如果使用注入功能，只需添加 REDIS_URL。

​
工作流运行保留

自动清除旧工作流运行的后台清理任务。每个工作流的覆盖设置（在工作流设置 UI 中配置）优先于这些全局默认值。
变量必需默认值描述
WORKFLOW_RUN_MAX_AGE_DAYS否30删除超过此天数的工作流运行
WORKFLOW_RUN_MAX_PER_WORKFLOW否100每个工作流最多保留此数量的运行（最旧的优先删除）
WORKFLOW_RUN_CLEANUP_INTERVAL_HOURS否24后台清理任务运行的频率，单位为小时

​
频道确认请求过期

后台清理程序，将由频道钩子（如 FeishuGateHook 或 Approval Playground）产生的陈旧待批准请求标记为已过期。确保数天后点击被遗忘的卡片不会翻转已被拆除的智能体状态。
变量必需默认值描述
CHANNEL_CONFIRMATION_TTL_MINUTES否1440超过此时间的待确认请求将自动过期（默认：24 小时）
CHANNEL_CONFIRMATION_SWEEP_INTERVAL_SECONDS否600过期清理程序的运行频率（默认：每 10 分钟）

​
OAuth（可选）

当为提供商同时设置 CLIENT_ID 和 CLIENT_SECRET 时，登录页面会自动显示相应的 OAuth 按钮。
变量必需默认值描述
GITHUB_CLIENT_ID否—GitHub OAuth 应用客户端 ID。在 github.com/settings/developers → OAuth Apps 创建
GITHUB_CLIENT_SECRET否—GitHub OAuth 应用客户端密钥
GOOGLE_CLIENT_ID否—Google OAuth 客户端 ID。在 console.cloud.google.com/apis/credentials 创建
GOOGLE_CLIENT_SECRET否—Google OAuth 客户端密钥
DISCORD_CLIENT_ID否—Discord OAuth2 客户端 ID。在 discord.com/developers 创建
DISCORD_CLIENT_SECRET否—Discord OAuth2 客户端密钥
FEISHU_APP_ID否—飞书（Lark）应用 ID。在 open.feishu.cn 创建。需要 contact:user.email:readonly 权限
FEISHU_APP_SECRET否—飞书（Lark）应用密钥
FRONTEND_URL生产环境http://localhost:3000OAuth 完成后浏览器跳转的位置。在生产环境中必须设置（例如 https://yourdomain.com）
API_BASE_URL生产环境http://localhost:8000外部可访问的后端 URL，用于构建 OAuth 回调 URL。在生产环境中必须设置
NEXT_PUBLIC_API_URL生产环境（自动检测为 <hostname>:8000）浏览器端 API 基础 URL，用于 OAuth 重定向。这是前端构建时变量 — 在本地开发时在 frontend/.env.local 中设置，或在自定义生产部署时作为 Docker 构建参数传递。自动检测适用于标准反向代理设置（端口 80/443）。
生产环境 = 本地可选（使用默认值），但对于任何面向互联网的部署都必需。

​
需要向每个提供商注册的 OAuth 回调 URL

后端构造回调 URL 为：{API_BASE_URL}/api/auth/oauth/{provider}/callback
提供商要注册的回调 URL
GitHubhttps://yourdomain.com/api/auth/oauth/github/callback
Googlehttps://yourdomain.com/api/auth/oauth/google/callback
Discordhttps://yourdomain.com/api/auth/oauth/discord/callback

​
Cloudflare Tunnel（可选）

通过 Cloudflare 的网络路由所有流量，而不是直接暴露端口。无需 Nginx、SSL 证书和开放防火墙规则。有关设置说明，请参阅生产部署部分。
中国大陆用户：Cloudflare Free/Pro/Business 计划在中国大陆没有 PoP。流量被路由到海外边缘节点，导致频繁出现 502 错误。除非您拥有带有中国网络的 Cloudflare Enterprise，否则如果您的主要用户在中国大陆，请勿使用此功能。
变量必需默认值描述
CLOUDFLARE_TUNNEL_TOKEN是（如果使用 Tunnel）—来自 Cloudflare Zero Trust → Networks → Tunnels → 您的 tunnel → Configure 的令牌。以 eyJ... 开头。由 docker-compose.tunnel.yml 中的 cloudflared sidecar 所需。

​
分析（可选）

所有分析提供商都是可选的。设置任意组合 — 所有活跃提供商同时加载。全部留空以完全禁用分析（建议用于本地开发）。
变量必需默认值描述
NEXT_PUBLIC_GA_MEASUREMENT_ID否—Google Analytics 4 测量 ID（例如 G-XXXXXXXXXX）。在 analytics.google.com 获取
NEXT_PUBLIC_UMAMI_SCRIPT_URL否—Umami 分析脚本 URL（例如 https://your-umami.com/script.js）。自托管、隐私友好的替代方案 — umami.is
NEXT_PUBLIC_UMAMI_WEBSITE_ID否—Umami 网站 ID。当设置 NEXT_PUBLIC_UMAMI_SCRIPT_URL 时必需
NEXT_PUBLIC_PLAUSIBLE_DOMAIN否—Plausible 分析域名（例如 yourdomain.com）。轻量级、隐私友好 — plausible.io
NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL否https://plausible.io/js/script.js自托管实例的自定义 Plausible 脚本 URL
所有 NEXT_PUBLIC_* 分析变量都是构建时 — 更改需要重新构建前端才能生效。