Environment Variables Reference (中文 (简体))

目录

• 1. 必需密钥
• 2. 存储与数据库
• 3. 网络与端口
• 4. 安全与身份验证
• 5. 输入清理与 PII 保护
• 6. 工具与路由策略
• 7. URL 与云同步
• 8. 出站代理
• 9. CLI 工具集成
• 10. 内部代理与 MCP 集成
• 11. OAuth 提供者凭据
• 12. 提供者 User-Agent 覆盖
• 13. CLI 指纹兼容性
• 14. API 密钥提供者
• 15. 超时设置
• 16. 日志记录
• 17. 内存优化
• 18. 定价同步
• 19. 模型同步（开发）
• 20. 提供者特定设置
• 21. 代理健康状态
• 22. 调试
• 23. GitHub 集成
• 24. Skills 沙箱（v3.8.0+）
• 27. Radar 数据源（自行托管）
• 部署场景
• 审计：已移除/无效的变量

---

1. 必需密钥

这些密钥必须在首次运行前设置。若未设置，应用程序将拒绝启动，或使用不安全的默认配置运行。

变量	是否必需	默认值	源文件	描述
JWT_SECRET	是	（无）	src/lib/auth	用于签名/验证所有仪表板会话 Cookie（JWT）。使用 openssl rand -base64 48 生成。
API_KEY_SECRET	是	（无）	src/lib/db/apiKeys.ts	用于对 SQLite 中静态存储的 API 密钥值进行 AES 加密的密钥。使用 openssl rand -hex 32 生成。
INITIAL_PASSWORD	是	CHANGEME	引导脚本	设置初始管理员仪表板密码（与 .env.example 的默认值一致——刻意保持明显不安全，以强制进行更改）。首次使用前请更改。 登录后，可通过“仪表板 → 设置 → 安全”进行更改。
OMNIROUTE_WS_BRIDGE_SECRET	是（生产环境）	（未设置）	src/app/api/internal/codex-responses-ws/route.ts	内部 Codex Responses WebSocket 桥接器的共享密钥。用于验证 Electron/浏览器 WS 中继与 OmniRoute 之间的桥接请求。⚠️ 生产环境中必需——未设置时，所有 WS 桥接请求都将被拒绝。 使用 openssl rand -base64 32 生成。
OMNIROUTE_SW_BUILD_ID	否	（git SHA）	next.config.mjs, scripts/build/assembleStandalone.mjs	用于 PWA 外壳缓存失效的显式 service worker 构建 ID（#11779）；在解析链中优先级最高。
SOURCE_VERSION	否	（未设置）	next.config.mjs, scripts/build/assembleStandalone.mjs	解析链中的第二项——由 PaaS 构建器（例如 Heroku 风格的构建器）设置为已部署的提交。
NEXT_PUBLIC_SW_BUILD_ID	否	（派生）	src/shared/components/PwaRegister.tsx	客户端用于注册 /sw.js?v=… 的构建时公开值；依次从上述两个值派生，最后回退到 git SHA。
OMNIROUTE_PEER_STAMP_TOKEN	否（自动）	（每次启动时自动生成）	src/server/authz/policies/management.ts	每个进程独有的密钥，用于证明受信任的对等 IP 戳记来自 OmniRoute 自己的 HTTP 服务器（scripts/dev/peer-stamp.mjs）。只有当戳记携带此令牌时，authz 中间件才会信任请求的本地性（对 LOCAL_ONLY 路由进行环回/LAN 限制）。每次启动时自动生成——请保持未设置；仅当必须共享该戳记的多进程部署中才固定设置此值。

生成命令

# 一次生成全部四个密钥：
echo "JWT_SECRET=$(openssl rand -base64 48)"
echo "API_KEY_SECRET=$(openssl rand -hex 32)"
echo "INITIAL_PASSWORD=$(openssl rand -base64 16)"
echo "OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -base64 32)"

[!CAUTION] 切勿将包含真实密钥的 .env 文件提交到版本控制系统中。.gitignore 已排除 .env，但请在推送前进行确认。

---

2. 存储与数据库

OmniRoute 使用 SQLite（通过 better-sqlite3）实现所有持久化。这些变量控制数据位置、加密和生命周期。

变量	默认值	源文件	描述
DATA_DIR	~/.omniroute/	src/lib/db/core.ts	SQLite 数据库、备份和数据文件的根目录。可针对 Docker 卷或自定义路径覆盖此设置。
OMNIROUTE_ALLOW_DEFAULT_DATA_DIR	（未设置）	src/lib/dataPaths.ts	用于绕过测试/求值 DATA_DIR 防护机制的应急开关（#10428）。未设置 DATA_DIR 的测试和 Node 求值/打印探测（-e/--eval/-p/--print，包括 --eval=/--print= 形式）会被重定向到一次性临时目录，因此无法打开运维人员的真实数据库；设置为 1 可重新启用真实目录。
OMNIROUTE_BUILD_SHA	（未设置）	src/lib/monitoring/buildSha.ts	正在运行的构建产物的 Git SHA。由 npm run build:release 写入；对于未包含 dist/BUILD_SHA 哨兵文件的容器，也可以注入。通过 /api/monitoring/health 上的 system.buildSha 公开。
OMNIROUTE_RELEASE_REF	origin/main	scripts/build/buildProvenance.ts	打包产物来源验证门控用于校验构建 SHA 的目标引用（#10427）。
OMNIROUTE_ALLOW_CANARY_BUILD	（未设置）	scripts/build/buildProvenance.ts	设置为 1 可允许打包 SHA 不在发布线上的构建，将其记录为有意部署的金丝雀版本，而不是让门控失败（#10427）。
OMNIROUTE_SMOKE_API_KEY	（未设置）	scripts/ops/deploy-canary.mjs	金丝雀部署冒烟探测使用的 API 密钥，在请求 /v1/chat/completions 时通过 Authorization: Bearer 发送。仅由部署脚本使用（#10429），服务器绝不会使用。此变量与选择启用的 CLI 冒烟测试工具中的 OMNIROUTE_SMOKE_* 变量无关（tests/integration/upstream-cli-smoke.int.test.ts 中的 RUN_CLI_SMOKE=1、OMNIROUTE_SMOKE_BASE_URL/MODEL/API_KEY_ENV/TARGETS/TIMEOUT_MS）— 请参阅 CLI 集成 → 真实冒烟扫描。
OMNIROUTE_BUILDING	（未设置）	src/lib/buildPhase.ts	构建阶段信号（#10060）：由 scripts/build/build-next-isolated.mjs 设置为 1，并由每个衍生的构建工作进程继承，使数据库层返回空操作存根，而不是加载原生 better-sqlite3 插件（该插件会导致工作进程退出时中止）。切勿为正在运行的服务器设置此变量。
OMNIROUTE_SKIP_NATIVE_DEP_CHECK	0	scripts/check/check-native-deps.mjs	设置为 1 可针对特殊的供应商依赖树跳过可选的原生依赖项预构建检查。这并不能使缺少依赖项的项目变得可构建；仅当原生依赖项通过带外方式提供时使用。
OMNIROUTE_DATA_DIR	（未设置）	open-sse/executors/promptql/threadSticky.ts	DATA_DIR 的后备别名，仅在未设置 DATA_DIR 时检查。用于定位 PromptQL 执行器的磁盘线程粘性会话缓存（<dir>/promptql-thread-sessions.json）；如果两个变量均未设置，缓存将仅保留在内存中（重启后不会持久保留）。
OMNIROUTE_PLUGINS_DIR	（未设置）	src/lib/plugins/scanner.ts	运行时插件扫描器读取的目录，也是插件管理器的安装根目录；设置后将覆盖根据主目录推导的默认值（#11827）。在 Docker/K8s 中，应将其指向绑定挂载的插件树，而不是仅为重新定位扫描路径而移动 HOME（HOME 还控制其他所有与主目录相关的行为）。未设置时 = ~/.omniroute/plugins；如果进程根本未导出主目录，则为 /tmp/.omniroute/plugins——此变量消除了由此导致的无提示插件发现失败。解析后的目录会在启动时记录一次，日志事件为 scanner.dir_resolved，并包含最终生效的输入。仅限服务器端：CLI 命令插件继续使用其自己的 OMNIROUTE_PLUGIN_PATH（第 9 节）。
STORAGE_ENCRYPTION_KEY	（空 = 禁用）	src/lib/db/encryption.ts	用于完整 SQLite 数据库静态加密的 AES 密钥。使用 openssl rand -hex 32 生成。
STORAGE_ENCRYPTION_KEY_VERSION	v1	scripts/build/bootstrap-env.mjs, electron/main.js	加密密钥的版本标签。执行密钥轮换时递增，以支持解密旧备份。
DISABLE_SQLITE_AUTO_BACKUP	false	src/lib/db/backup.ts	当为 true 时，跳过常规/写入前的 SQLite 文件备份（models.dev 定价的保存/清除、设置写入）。手动备份和恢复前备份仍会运行。它不会禁用迁移运行器强制执行的持久化安全快照，也不会禁用现有持久化数据库的大规模迁移防护。非手动备份最多每 60 分钟执行一次。仪表板中的设置 → 存储可以独立禁用常规自动备份。
OMNIROUTE_CRYPT_KEY	（未设置）	src/lib/db/encryption.ts	STORAGE_ENCRYPTION_KEY 的旧版别名。当主变量不存在时，接受将其作为回退选项。
OMNIROUTE_API_KEY_BASE64	（未设置）	src/lib/db/encryption.ts	接受将此旧版别名（Base64 编码形式）作为回退选项。使用前会自动解码。
OMNIROUTE_DB_HEALTHCHECK_INTERVAL_MS	（未设置）	src/lib/db/core.ts	覆盖 SQLite 定期健康检查的间隔（毫秒）。未设置时，默认值根据 NODE_ENV 推导。
OMNIROUTE_WAL_TRUNCATE_INTERVAL_MS	（已移除）	src/lib/db/walMaintenance.ts	**已移除。**定期在运行期间执行 wal_checkpoint(TRUNCATE) 可能会使共享的 wal-index 映射失效，并导致进程因 SIGBUS 而崩溃（#13973），因此该调度器已不复存在。此变量不再生效：设置正值时会记录一次弃用警告，而设置为 0 或未设置时则保持静默。WAL 由 PASSIVE 检查点（见下文）维护，并由关机检查点截断。
OMNIROUTE_WAL_PASSIVE_INTERVAL_MS	300000（5 分钟）	src/lib/db/walMaintenance.ts	覆盖频繁执行 wal_checkpoint(PASSIVE) 的间隔（毫秒）。使待处理的 WAL 帧保持较小规模，从而让检查点快速完成，并确保 WAL 文件在两次关机截断之间保持在有限大小。设置为 0 可禁用。
OMNIROUTE_WAL_GUARD_MAX_MB	256	src/lib/db/walMaintenance.ts	当 PASSIVE 定时任务发现 WAL 文件超过此大小时，运行 wal_checkpoint(RESTART)，使 WAL 重新开始，而无需重写已映射的 wal-index。运行期间的 truncate 模式检查点已被移除（请参阅 OMNIROUTE_WAL_TRUNCATE_INTERVAL_MS 行）。
OMNIROUTE_PRESSURE_SELF_RESTART	false	open-sse/utils/resourcePressure.ts	设置为 1/true/yes/on，以便在关键资源压力持续达到 OMNIROUTE_PRESSURE_SELF_RESTART_AFTER_MS 后退出进程，让监督程序（systemd Restart=always、Docker 重启策略）启动一个干净的进程，而不是无限期地返回 503。
OMNIROUTE_PRESSURE_SELF_RESTART_AFTER_MS	120000（2 分钟）	open-sse/utils/resourcePressure.ts	触发自重启退出前，关键资源压力必须持续的时长。
OMNIROUTE_SQLJS_WASM_PATH	（自动检测）	src/lib/db/adapters/sqljsAdapter.ts	使用 sql.js WASM 回退适配器时，指向 sql-wasm.wasm 的显式路径（绝对路径或相对于 cwd 的路径）。未设置时，会通过包依赖项和候选布局自动检测。
OMNIROUTE_BATCH_RETENTION_DAYS	30	src/lib/db/cleanup.ts	自动清理扫描在删除前保留终态（已完成/失败/已取消/已过期）Batch API 作业的检查点、引用的输入/输出/错误文件及对应行的天数。仅在启用 BATCH_AND_FILE_AUTO_CLEANUP_ENABLED 后生效；与 OpenAI 自身的 Batch API 输出保留期一致。不会影响由运维人员触发的 DELETE /api/v1/batches/delete-completed 路由；按照设计，该路由始终无条件执行（不按期限筛选）。
BATCH_AND_FILE_AUTO_CLEANUP_ENABLED	false	src/lib/db/cleanup.ts	当为 true 时，允许自动清理扫描删除超过 OMNIROUTE_BATCH_RETENTION_DAYS 的终态 Batch API 作业（及其检查点），并清除超过各自 expires_at 的已上传文件的 BLOB 内容。默认关闭：在运维人员选择启用前，每个现有安装都将完全按此前方式保留这些数据。这也是一个可在仪表板中编辑的功能标志——请参阅 docs/reference/FEATURE_FLAGS.md → 运行时。
OMNIROUTE_SKIP_DB_HEALTHCHECK	0	src/lib/db/core.ts, src/lib/db/healthCheck.ts	设置为 1 可在启动时完全跳过数据库健康检查。适用于短期运行的任务和集成测试。
OMNIROUTE_FORCE_DB_HEALTHCHECK	0	src/lib/db/core.ts	设置为 1 可强制启用数据库健康检查循环，即使通常会跳过该检查（例如短期运行的任务）。
OMNIROUTE_SKIP_POSTINSTALL	0	scripts/postinstall.mjs	设置为 1 可在 npm install 期间跳过原生运行时预热。适用于已构建 sqlite 的 CI/无头安装环境。
OMNIROUTE_MIGRATIONS_DIR	（自动检测）	src/lib/db/migrationRunner.ts	覆盖迁移运行器扫描的目录。适用于在自定义构建中提供已打包迁移的情况。
OMNIROUTE_EXTRA_MIGRATIONS_DIRS	（未设置）	src/lib/db/migrationRunner/extraDirs.ts	其他迁移目录，以 namespace=dir 条目的形式指定，各条目之间使用平台路径分隔符分隔（例如 ee=/opt/app/enterprise/db/migrations）。在这些目录中找到的文件会记录为 <namespace>-<number>，因此附带自有迁移的发行版绝不会与上游数字槽位冲突。如果条目格式错误、命名空间无效或目录不存在，系统会在启动时抛出错误，而不是静默跳过架构。
OMNIROUTE_MAX_PENDING_MIGRATIONS	50	src/lib/db/migrationRunner.ts	大量待处理迁移的安全阈值（#3416）。如果现有数据库中待处理的迁移数量超过此值，启动将中止（防止跟踪表被清空）。可调高此值以还原较旧的备份；设置为 0 可禁用此检查。
OMNIROUTE_INSTALL_UPGRADE_WORKDIR	（<repo>/.install-upgrade）	scripts/check/check-install-upgrade.mjs	check:install-upgrade 发布门禁的工作目录。它需要大约 12 GB 空间（两个约 3 GB 的安装目录树以及 tarball），因此不得在较小的 tmpfs 上运行——在自托管运行器上，/tmp 是一个 12 GB、由 RAM 支持的 tmpfs，该门禁曾耗尽其空间，导致软件包被截断。
OMNIROUTE_SPEND_FLUSH_INTERVAL_MS	（代码中的默认值）	src/lib/spend/batchWriter.ts	批量支出/成本写入器的刷新间隔（毫秒）。较低的值会减少写入合并；较高的值会减少数据库争用。
OMNIROUTE_SPEND_MAX_BUFFER_SIZE	（代码中的默认值）	src/lib/spend/batchWriter.ts	强制刷新前可缓冲的最大支出条目数。在高 QPS 部署中可调高；当限制内存比其他因素更重要时可调低。
OMNIROUTE_PROXY_FETCH_DEBUG	（未设置）	open-sse/utils/proxyFetch.ts	设置为 "true" 可在 Vercel 中继路径上输出 [ProxyFetch] 调试日志。默认关闭，以避免泄露路由提示信息。
PROXY_LOG_INCLUDE_IPS	false	src/lib/proxyLogger.ts	设置为 "true" 或 "1"，可在详细的 [ProxyEgress] 进程日志行中包含客户端/出口 IP 和账户前缀。默认保持关闭，以免进程日志泄露 IP 或账户前缀。
OMNIROUTE_DEBUG	（未设置）	bin/cli/commands/quota.mjs	设置为 1，可通过 CLI 配额命令将每个请求的计时诊断信息（[omniroute] GET <path> completed in Nms）打印到 stderr。
OMNIROUTE_HEALTHCHECK_PATH	（自动）	scripts/dev/healthcheck.mjs	容器健康检查所探测的显式路径。未设置时，探针会根据 OMNIROUTE_BASE_PATH 推导路径；设置此项会重新启用深度监控端点。
OMNIROUTE_DEBUG_COMPLETION	（未设置）	bin/cli/commands/completion.mjs	设置为任意非空值，可从 CLI shell 补全缓存路径（读取/刷新/写入）输出 [omniroute completion] 诊断信息。默认关闭——这些缓存会静默失败，因此缓存缺失或损坏绝不会破坏 Tab 补全。
BATCH_RETRY_DURATION_MS	86400000（24 小时）	open-sse/services/batchProcessor.ts	单个批处理项的最大重试时间窗口（毫秒）。超过此时长的项目会被标记为失败。
BATCH_BACKOFF_BASE_MS	5000	open-sse/services/batchProcessor.ts	批处理项重试采用指数退避时的基础延迟（毫秒）。
BATCH_BACKOFF_MAX_MS	3600000（1 小时）	open-sse/services/batchProcessor.ts	批处理项重试之间指数退避的上限（毫秒）。
BATCH_MAX_CONCURRENT	1	open-sse/services/batchProcessor.ts	并发处理的最大批次数。提高此值可增加吞吐量；应保持较低值，以避免触发大规模限流。

[!IMPORTANT] 在更改现有的持久化数据库之前，迁移运行程序会在 DATA_DIR/db_backups/ 下发布一个完整的、 按内容寻址的快照。发布过程要求文件系统支持同一文件系统内禁止覆盖的硬链接，以及持久化文件同步。 POSIX 主机还要求进行目录同步；在 Windows 上，Node 可能会拒绝目录句柄，因此 OmniRoute 会刷新 已发布的文件，并将目录项同步作为尽力而为的操作。 如果挂载的 DATA_DIR 无法提供这些保障，启动过程会在应用迁移前以安全关闭方式失败。 请将 DATA_DIR 移至支持这些原语的卷；不要使用 DISABLE_SQLITE_AUTO_BACKUP 绕过迁移安全机制。

场景

场景	配置
本地开发	保留所有默认设置。数据库位于 ~/.omniroute/omniroute.db。
Docker	设置 DATA_DIR=/data，并在 /data 挂载一个卷。
静态加密	设置 STORAGE_ENCRYPTION_KEY 并妥善备份密钥！丢失密钥 = 丢失数据。
CI/测试	DATA_DIR=/tmp/omniroute-test——临时数据，无需加密。

---

3. 网络与端口

变量	默认值	源文件	描述
PORT	20128	src/lib/runtime/ports.ts	Dashboard UI 和 API 端点的主端口（单端口模式）。
OMNIROUTE_BASE_PATH	（空 = 根路径）	next.config.mjs, scripts/docker/ensure-docker-base-path.mjs	在反向代理后通过 URL 子路径提供 OmniRoute 服务（设置 Next.js basePath；身份验证重定向会感知 basePath）。例如 /omniroute。在 Docker 中，该值会在 docker build 期间写入（ARG OMNIROUTE_BASE_PATH）；预构建的根路径镜像可以在容器启动时、Next.js 启动前应用一次不同的运行时值。将 NEXT_PUBLIC_BASE_URL 设置为包含相同子路径的公共源地址。
NEXT_PUBLIC_OMNIROUTE_BASE_PATH	（空 = 根路径）	src/shared/hooks/useDisplayBaseUrl.ts	OMNIROUTE_BASE_PATH 在浏览器端可见的镜像值，在构建时内联，使 Dashboard 端点显示为 https://host/omniroute/v1，而不是 https://host/v1。未设置时回退到 OMNIROUTE_BASE_PATH。更改后需重新构建（Next basePath 是构建时配置）。
DASHBOARD_ALLOW_EMBED	（未设置 = 始终不可嵌入框架）	next.config.mjs, scripts/build/dashboardEmbed.mjs	选择性启用通过 iframe 嵌入 HTML 页面。未设置时，每个路由都会附带 frame-ancestors 'none' + X-Frame-Options: DENY。设置为 vscode 时，将使用 frame-ancestors 'self' vscode-webview: 且不带 X-Frame-Options 来提供页面（Dashboard、登录、文档、落地页），从而使 VS Code Simple Browser 能够渲染这些页面（OmniCopilot 的 dashboardOpen: "editor" 模式）。无论采用哪种设置，API 接口（/api、/v1、/v1beta、/a2a、/healthz、根级别名）都会保留严格的标头。仅识别 vscode——1/true 不会启用该功能。构建时配置：更改后需重新构建（对于镜像，使用 docker build --build-arg DASHBOARD_ALLOW_EMBED=vscode；在预构建安装中设置该值无效）。
API_PORT	（未设置）	src/lib/runtime/ports.ts	设置后，将在此独立端口上提供 /v1/* 代理 API。
API_HOST	0.0.0.0	src/lib/runtime/ports.ts	API 端口的绑定地址。
DASHBOARD_PORT	（未设置）	src/lib/runtime/ports.ts	设置后，将在此独立端口上提供 Dashboard UI。
OMNI_MAX_CONCURRENT_CONNECTIONS	0 （已禁用）	src/sse/utils/backpressure.ts	限制正在处理的并发聊天连接数；超出上限的请求将收到带有 Retry-After 的 503。正整数会启用此保护；未设置或设为 0 时将其禁用。
OMNIROUTE_INSTANCE_ID	（未设置）	src/shared/resilience/peerRouting.ts	在串联 OmniRoute 实例时，此网关所使用的稳定且唯一的 ID。启用入站对等循环检查。允许的字符：字母、数字、.、_、: 和 -；最多 64 个字符。
OMNIROUTE_PEER_URLS	（未设置）	src/shared/resilience/peerRouting.ts, open-sse/executors/base.ts	以逗号分隔的 OmniRoute 基础 URL，可接收 X-OmniRoute-Peer-Trace。只有明确列入允许列表的上游 URL 才会收到对等节点元数据；所有其他提供者均不受影响。
OMNIROUTE_PEER_MAX_HOPS	4	src/shared/resilience/peerRouting.ts	链式请求中允许的先前已访问 OmniRoute 实例的最大数量（1-32）。实例重复或跳数预算耗尽时返回 HTTP 508 Loop Detected。
PROD_DASHBOARD_PORT	20130	docker-compose.prod.yml	Docker 生产模式下 Dashboard 在主机侧发布的端口。
PROD_API_PORT	20131	docker-compose.prod.yml	Docker 生产模式下 API 在主机侧发布的端口。
OMNIROUTE_PORT	（未设置）	src/lib/runtime/ports.ts	在 Electron 或其他封装环境中运行时，优先于 PORT。
LIVE_WS_PORT	20129	src/server/ws/liveServer.ts	实时 WebSocket 监控服务器的端口。
LIVE_WS_HOST	127.0.0.1	src/server/ws/liveServer.ts	实时 WebSocket 服务器的绑定地址。设置为 0.0.0.0 可在局域网中公开（还需配置 LIVE_WS_ALLOWED_ORIGINS）。
LIVE_WS_ALLOWED_ORIGINS	（未设置）	src/server/ws/liveServer.ts	允许打开实时 WebSocket 的额外来源，以逗号分隔。默认已允许本机回环地址上的 Dashboard 来源。
LIVE_WS_ALLOWED_HOSTS	（未设置）	src/server/ws/liveServerAllowList.ts	实时 WebSocket 来源允许使用的额外主机名，以逗号分隔。与 LIVE_WS_ALLOWED_ORIGINS（完整来源 URL）不同，此项仅匹配主机部分——适用于局域网/Tailscale 配置。
NEXT_PUBLIC_LIVE_WS_PUBLIC_URL	（未设置）	src/hooks/useLiveDashboard.ts	实时 Dashboard WebSocket 的公共 URL（浏览器端）。使用反向代理或 Cloudflare Tunnel 作为 WS 服务器前端时设置此项（例如 wss://ws.my-ai.com/live-ws）；浏览器将连接到该地址，而非 ws://hostname:20132。路径名部分也会用作 WebSocket 升级路径（默认值：/live-ws）。
OMNIROUTE_ENABLE_LIVE_WS	true	src/server/ws/liveServer.ts 和 scripts/start-ws-server.mjs	设置为 0 或 false 可禁用实时 WebSocket 服务器（默认启用并绑定到回环地址）。此 CI/测试框架开关会禁用独立的实时 WebSocket 辅助脚本。
RELAY_IP_PER_MINUTE	30	src/app/api/v1/relay/chat/completions/route.ts	每个（令牌、IP）组合的中继速率限制，单位为请求数/分钟。基于内存，按实例独立计算。设置为 0 或负数会禁用 IP 维度的限制（基于数据库的每令牌限制仍然适用）。
NODE_ENV	production	Next.js 核心	控制日志详细程度、缓存、错误详情暴露以及 Next.js 优化。
OMNIROUTE_USE_TURBOPACK	1（Turbopack——代码默认值）	package.json / Next.js 16	Turbopack 是 npm run dev 和 npm run build 的默认打包器（经基准测试，构建速度快 2-3 倍）。在 Windows 上、遇到原生绑定/打包器兼容性问题时，或在内存受限的机器上，将其设置为 0 以回退到 webpack——此 Next.js 版本线（16.2.x）上的 Turbopack 生产构建已知在大型模块图中的内存峰值远高于 webpack（Next 16.3 的 Turbopack 内存逐出修复尚未稳定）；webpack 回退方案的峰值要低得多。参见 #6409。
OMNIROUTE_SKIP_DB_HEALTHCHECK	（未设置）	src/lib/db/core.ts / src/lib/db/healthCheck.ts	设置为 1 可跳过启动时的 SQLite 完整性健康检查。适用于加快大型数据库的启动速度。
NOTIFY_SOCKET	（未设置）	systemd（sd_notify 协议）	当进程在集成了 sd_notify 的服务单元下运行时由 systemd 设置；OmniRoute 会读取它（参见 OMNIROUTE_DISABLE_SD_NOTIFY），以发送 READY/WATCHDOG 通知。用户切勿设置此变量。
OMNIROUTE_DISABLE_SD_NOTIFY	（未设置）	scripts/dev/systemd-notify.mjs	设置为 1 可禁用 systemd sd_notify（Type=notify / WatchdogSec=），即使正在 systemd 单元下运行也是如此。无论如何，通知器在 systemd 之外不会执行任何操作。
CREDENTIAL_HEALTH_CHECK_INTERVAL	300000	open-sse/config/constants.ts / src/lib/credentialHealth/scheduler.ts	后台凭据健康检查调度器的时间间隔（毫秒）。最小值：10000（10 秒）。
CREDENTIAL_HEALTH_CACHE_TTL	300000	open-sse/config/constants.ts / src/lib/credentialHealth/cache.ts	缓存凭据健康状态的 TTL（毫秒）。
OMNIROUTE_DISABLE_CREDENTIAL_HEALTH_CHECK	false	src/lib/credentialHealth/scheduler.ts	设置为 1 或 true 可禁用后台定期测试提供者连接。搜索提供者（src/lib/providers/validation/searchProviders.ts 中的 SEARCH_VALIDATOR_CONFIGS，例如 tavily-search）始终排除在扫描范围之外——其“验证”是会产生实际计费的上游查询，因此绝不会按定时计划对其进行健康检查（#9970）。
HOST	0.0.0.0	scripts/dev/run-next.mjs	Next.js 开发/启动服务器的绑定地址。设置后会覆盖默认值 0.0.0.0。
HOSTNAME	127.0.0.1	scripts/dev/run-next-playwright.mjs	Playwright 运行器启动 Next.js 时使用的绑定地址。默认值为 127.0.0.1，以实现密闭测试。请勿用于 omniroute serve——请改用 OMNIROUTE_SERVER_HOST（POSIX shell 会自动将 HOSTNAME 设置为机器名称；.env 无法覆盖它）。
OMNIROUTE_SERVER_HOST	0.0.0.0	bin/cli/commands/serve.mjs	omniroute serve 的绑定地址。避免与 POSIX shell 的 HOSTNAME 变量冲突（bash/zsh 始终将其设置为机器名称）。未设置时回退到 0.0.0.0。（#6194）

端口模式

┌─────────────────────────── 单端口（默认）────────────────────────────┐
│  PORT=20128                                                                 │
│  → 控制面板：http://localhost:20128                                         │
│  → API：     http://localhost:20128/v1/chat/completions                    │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────── 独立端口 ────────────────────────────────────────┐
│  DASHBOARD_PORT=20128                                                       │
│  API_PORT=20129                                                             │
│  API_HOST=0.0.0.0                                                           │
│  → 控制面板：http://localhost:20128                                         │
│  → API：     http://0.0.0.0:20129/v1/chat/completions                     │
│  使用场景：将 API 暴露至局域网，同时将控制面板限制为仅可从 localhost 访问。 │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────── Docker 生产环境 ────────────────────────────────┐
│  PROD_DASHBOARD_PORT=443   PROD_API_PORT=8443                              │
│  → 在 docker-compose.prod.yml 中将容器端口映射到主机端口。                 │
└─────────────────────────────────────────────────────────────────────────────┘

---

4. 安全与身份验证

变量	默认值	源文件	说明
MACHINE_ID_SALT	endpoint-proxy-salt	src/lib/auth	与硬件标识符组合使用的盐值，用于生成机器指纹。应在每次部署时更改，以实现隔离。
OMNIROUTE_CLI_SALT	（未设置 = 每次安装时随机生成盐值，并持久化至 <DATA_DIR>/cli-token-salt.json）	src/lib/machineToken.ts	用于派生本地 CLI 身份验证令牌的 HMAC 盐值。设置此值会轮换该机器上的所有 CLI 令牌，并且其优先级始终高于持久化的盐值。请参阅 docs/security/CLI_TOKEN.md。
AUTH_COOKIE_SECURE	false	src/lib/auth	设置会话 Cookie 的 Secure 标志。在 HTTPS 后方运行时，必须设为 true。
REQUIRE_API_KEY	false	API 中间件	当设为 true 时，所有 /v1/* 代理请求都必须包含有效的 API 密钥。此标志不控制 GET /v1/models；后者改为遵循仪表板登录策略（requireAuthForModels）——因此，/v1/models 返回 401 并不意味着推理已受到保护。请参阅 docs/security/INFERENCE_AUTH_POSTURE.md（#13695）。
ALLOW_API_KEY_REVEAL	false	src/shared/constants/featureFlagDefinitions.ts	允许在仪表板 UI 中显示完整的 API 密钥值。可通过仪表板的功能标志进行配置；在共享实例上存在安全风险。
NO_LOG_API_KEY_IDS	（空）	src/lib/compliance/index.ts	以逗号分隔的 API 密钥 ID，这些密钥的请求不会被记录（用于 GDPR 合规）。
DEFAULT_RATE_LIMIT_PER_DAY	（未设置 = 无限制）	src/shared/utils/apiKeyPolicy.ts	应用于 rate_limits 列为 null 的 API 密钥的每日备用请求配额。未设置或为空：不设隐式上限（#2289、#11017）。0 同样表示无限制。正整数 N 表示每天 N 次、每周 5N 次、每月 20N 次。格式错误的非空值将回退到旧版限制：每天 1000 次、每周 5000 次、每月 20000 次。
MAX_BODY_SIZE_BYTES	10485760（10 MB）	src/shared/middleware/bodySizeGuard.ts	允许的最大请求正文大小。超过此限制的载荷将被拒绝。
OMNIROUTE_CHAT_LARGE_BODY_BYTES	262144（256 KB）	src/shared/middleware/chatBodyAdmission.ts	实际请求正文达到或超过此阈值时，会在 JSON 解析之前获取原子的、进程本地的重量级准入租约（BYTE 路径，包括 POST /v1/responses）。采用与结构复杂请求相同的 #10437 健康余量逃生机制；同时仍受 OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES / #10110 限制，从而避免 #7849 问题再次出现。
OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES	52428800 (50 MB)	src/shared/middleware/chatBodyAdmission.ts	聊天路由的硬上限，根据受限摄取期间读取的字节数强制执行，包括缺失、无效或虚报 Content-Length 的请求；超出限制时返回 413。
OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT	(未设置 — 无请求数量上限)	src/shared/middleware/chatBodyAdmission.ts	#503 扇出：此旧版请求数量上限现在仅在显式设置时生效。保持未设置（默认值）时，重量级聊天准入改由 OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES 限制——这是在单个进程（单个 V8 堆）中，根据进程的实际内存上限自动推导的字节预算。两个重叠的约 75 万 token 的 /v1/responses 会使约 12 GiB 的堆崩溃（#7849）——这是内存预算警告，并非产品的硬性最大并发数为 2。健康进程（堆低于卸载比率）可通过 OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM 接纳更多并发的长 /v1/responses。数十个长 SSE 客户端（40–50 个）的限制取决于堆 + OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES / #10110，而不是“最多 2 个”。盲目提高此值以“用满主机”会重新引发 #7849。应通过 N 个独立的 DATA_DIR 增加堆的数量（#11024）；切勿让一个 SQLite 文件使用 replicas>1。
OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES	(自动推导)	src/shared/middleware/admissionBudget.ts	**#503 扇出：**用于覆盖自动推导的摄取字节预算（V8/cgroup 两者中较严格的内存上限的 25%，再除以 8 倍的瞬时放大系数）。推导值和显式值均限制在 8 MiB–2 GiB 范围内。大于有效预算的请求体会立即以 413 body_exceeds_budget 失败；各自可被处理的请求体之间发生争用时，仍返回可重试的 503。40–50 个并发长 SSE 客户端的限制取决于此预算 + 堆，而不是硬性的“最多 2 个”。调整前，请在 /api/monitoring/health 中查看 chatAdmission.maxInflightBytes / budgetSource / pressureSeverity。
OMNIROUTE_CHAT_ADMISSION_HEAP_SHED_RATIO	0.75	src/shared/middleware/chatBodyAdmission.ts	用于字节和结构型重量级准入的堆压力卸载比率（heapUsed / heap_size_limit）（#10183、#10268、#10437）。只有当堆同时达到或超过此比率时，超过 OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT 的并发重量级请求才会被卸载，并返回可重试的 503；在堆健康时，则通过健康余量路径接纳。
OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM	OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT（默认值为 1）	src/shared/middleware/chatBodyAdmission.ts	为结构和字节（admitChatRequest，包括请求体 ≥ OMNIROUTE_CHAT_LARGE_BODY_BYTES）两种类型的健康堆快速路径（#10437）提供有界的额外容量。若无此边界，每个繁忙但堆健康的请求都能绕过准入，且没有上限。一旦通过健康堆路径激活的并发租约达到此数量，后续繁忙请求将转入与实际堆压力下相同的有界等待/卸载路径。0 会完全禁用绕过机制。
OMNIROUTE_CHAT_HEAVY_MESSAGE_COUNT	200	src/shared/middleware/chatBodyAdmission.ts	即使请求体低于字节阈值，也会将聊天请求归类为重量级请求的消息数量。
OMNIROUTE_CHAT_HEAVY_TOOL_COUNT	64	src/shared/middleware/chatBodyAdmission.ts	即使请求体低于字节阈值，也会将聊天请求归类为重量级请求的工具数量。
OMNIROUTE_CHAT_HEAVY_ESTIMATED_TOKENS	32000	src/shared/middleware/chatBodyAdmission.ts	用于将请求归类为重量级请求的保守字符串大小 token 估算值；这是准入成本的代理指标，而不是提供者计费用的 token 化方式。
OMNIROUTE_CHAT_HARD_MAX_MESSAGES	0（已禁用）	src/shared/middleware/chatBodyAdmission.ts	可选启用的聊天历史记录上限。默认禁用：消息数量属于部署策略，而不是请求的通用属性；在此处设置上限会在压缩管道能够使对话变得可处理之前，就以终止性的 413 拒绝对话。堆增长由 OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT 和堆压力卸载机制限制。对于需要硬性上限的内存受限部署，可将其设置为正值；超出限制时，将返回结构化的“需要压缩”413。
OMNIROUTE_MAX_NONSTREAMING_RESPONSE_BYTES	67108864 (64 MB)	open-sse/handlers/chatCore/nonStreamingResponseBody.ts	完整缓冲到内存中的非流式上游响应的硬性上限。超过此上限时，将取消上游读取器并使请求快速失败，避免字符串无限增长直至耗尽堆。
OMNIROUTE_FORWARDING_HEADER_BUDGET_BYTES	768	open-sse/handlers/chatCore/responseHeaders.ts	从上游响应标头转发的最大传输字节数。超出预算时，将丢弃优先级较低的标头（例如自定义 x-codex-*、x-oai-request-id），以保持在常见反向代理的标头限制范围内。可将其设置得更高，以转发更多上游元数据，但会增大响应标头的大小。
CORS_ORIGIN	（未设置）	src/server/cors/origins.ts	旧版单源 CORS 允许列表。对于新部署，建议使用 CORS_ALLOWED_ORIGINS。CORS 仅适用于跨源浏览器 API 客户端；经过身份验证的仪表板写入操作改为使用同源请求以及与会话绑定的 CSRF 防护。
CORS_ALLOWED_ORIGINS	（未设置）	src/server/cors/origins.ts	以逗号分隔的 CORS 允许列表。除非明确配置 CORS_ALLOW_ALL=true，否则不会发送通配符。
CORS_ALLOW_ALL	false	src/server/cors/origins.ts	仅用于开发环境的应急选项，可回显任何浏览器 Origin。请勿在共享部署或生产部署中启用。
OUTBOUND_SSRF_GUARD_ENABLED	true	src/shared/network/outboundUrlGuard.ts	阻止以私有、环回或链路本地 IP 范围为目标的提供者调用。仅可在隔离的测试环境中禁用。
OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS	false	src/shared/network/outboundUrlGuard.ts	允许指向私有/本地网络（localhost、192.168.x.x、10.x.x.x 等）的提供者 URL。自托管提供者必须启用此项（LM Studio、Ollama、vLLM、Llamafile、Triton、SearXNG）。当值为 false 时，仪表板会拒绝验证本地 URL。
OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS	true	src/shared/network/outboundUrlGuard.ts	允许添加/验证位于本地/私有地址（127.0.0.1、localhost、LAN、私有地址范围）的提供者——仅限提供者验证路径。默认值为 true（本地优先）；设置为 false 可强制执行仅允许公共地址的严格阻止策略。无论如何，云元数据端点（169.254.169.254、metadata.google.internal）始终会被阻止。 (#5066)
AUDIO_REMOTE_PROVIDER_NODES	false	src/app/api/v1/_shared/audioProviderNodes.ts	允许 /v1/audio/* 路由（转录、语音、翻译）使用托管在 localhost 之外且兼容 OpenAI 的提供者节点。默认关闭——将音频路由到远程主机会改变出站身份，因此必须由运维人员明确决定是否启用。环回/私有节点（localhost、127.0.0.1、172.16-31.x）始终允许使用且不受影响。 (#3963)
RERANK_REMOTE_PROVIDER_NODES	false	src/app/api/v1/_shared/rerankProviderNodes.ts	允许 POST /v1/rerank（以及内存引擎的环回重排序步骤）使用托管在 localhost 之外且兼容 OpenAI 的提供者节点——例如运行 TEI、Infinity、vLLM 等的 LAN 主机或 Tailscale 对等节点。默认关闭——路由到远程主机会改变出站身份，因此必须由运维人员明确决定是否启用。环回节点（localhost、127.0.0.1、172.16-31.x）始终允许使用且不受影响。远程节点还必须通过提供者出站 URL 策略（OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS）；请求绝不会被路由到云元数据主机。
OMNIROUTE_OIDC_DISABLE_PASSWORD_LOGIN	false	src/app/api/auth/login/route.ts	启用 OIDC 后，禁用密码登录，使用户只能通过 OIDC 单点登录进行身份验证。也接受简短别名 OIDC_DISABLE_PASSWORD_LOGIN；同名的仪表板功能标志具有更高优先级。 (#10889)
OIDC_DISABLE_PASSWORD_LOGIN	false	src/app/api/auth/login/route.ts	OMNIROUTE_OIDC_DISABLE_PASSWORD_LOGIN 的简短别名 (#10889)。

加固检查清单

# 生产环境最低安全要求：
AUTH_COOKIE_SECURE=true        # 需要 HTTPS
REQUIRE_API_KEY=true           # 对所有代理调用进行身份验证
ALLOW_API_KEY_REVEAL=false     # 切勿在 UI 中暴露密钥
CORS_ALLOWED_ORIGINS=https://your.domain.com
MAX_BODY_SIZE_BYTES=5242880    # 5 MB 限制

---

5. 输入净化与 PII 保护

OmniRoute 提供双层防护：请求侧注入扫描和响应侧 PII 移除。

**⚠️ 局限性：**这些防护措施采用的是尽力而为的启发式检测，并非完整的提示词注入防火墙或 PII DLP 系统。它们可能产生误报（将无害的人设/RPG 提示词标记为风险）和漏报（如 leetspeak、插入空格、非英语模式）。仅依靠这些措施不足以满足合规要求。请根据需要调整模式，并针对实际流量进行测试后再依赖这些功能。

请求侧：提示词注入防护

变量	默认值	源文件	描述
INPUT_SANITIZER_ENABLED	true	src/middleware/promptInjectionGuard.ts	启用对传入消息中的提示词注入模式进行扫描。
INPUT_SANITIZER_MODE	warn	src/middleware/promptInjectionGuard.ts	注入策略：warn = 仅记录日志，block = 拒绝请求并返回 400。旧版 redact 不会移除注入文本；如需重写请求中的 PII，请使用 PII_REDACTION_ENABLED。
INJECTION_GUARD_MODE	(未设置)	src/middleware/promptInjectionGuard.ts	INPUT_SANITIZER_MODE 的旧版别名，行为相同。
INPUT_SANITIZER_BLOCK_THRESHOLD	high	src/shared/utils/injectionSeverity.ts	MODE=block 拒绝请求的最低严重级别：high（默认）、medium 或 low。除非降低此阈值，否则中等级别模式仅用于观察。
INJECTION_GUARD_BLOCK_THRESHOLD	(未设置)	src/shared/utils/injectionSeverity.ts	INPUT_SANITIZER_BLOCK_THRESHOLD 的旧版别名，行为相同。
PII_REDACTION_ENABLED	false	src/lib/guardrails/piiMasker.ts	设为 true 时，对传入请求中的 PII 进行脱敏处理（独立于注入模式）。
CREDENTIAL_REDACTION_ENABLED	false	src/lib/guardrails/credentialMasker.ts	从请求/响应负载中移除常见的 API 密钥/秘密令牌模式。需主动启用；行为与 PII_REDACTION_ENABLED 一致。

响应侧：PII 净化器

变量	默认值	源文件	描述
PII_RESPONSE_SANITIZATION	false	src/lib/piiSanitizer.ts	在将 LLM 响应返回给客户端之前，扫描其中是否泄露 PII。
PII_RESPONSE_SANITIZATION_MODE	redact	src/lib/piiSanitizer.ts	redact = 遮盖 PII，warn = 仅记录日志，block = 丢弃整个响应。

VS Code 令牌化路由上下文净化器

变量	默认值	源文件	描述
OMNIROUTE_VSCODE_SANITIZE_CONTEXT	1	src/app/api/v1/vscode/contextSanitizer.ts	从 /v1/vscode/[token]/* 请求中移除隐式的活动编辑器上下文（editorContext、activeEditor、currentFile、selection、openTabs……），并对明确附加的敏感文件内容进行脱敏。默认安全；设为 0 可禁用。

场景

场景	配置
企业合规	INPUT_SANITIZER_ENABLED=true、INPUT_SANITIZER_MODE=block、PII_REDACTION_ENABLED=true、PII_RESPONSE_SANITIZATION=true（阻止注入并对请求/响应中的 PII 进行脱敏；各模式相互独立）
仅监控	INPUT_SANITIZER_ENABLED=true、INPUT_SANITIZER_MODE=warn — 记录日志，但绝不阻止请求
个人使用	保持全部禁用 — 零开销

---

6. 工具与路由策略

变量	默认值	源文件	描述
TOOL_POLICY_MODE	disabled	src/lib/toolPolicy.ts	控制 LLM 对工具/函数调用的访问权限。allowlist = 仅允许列出的工具，denylist = 允许除列出工具之外的所有工具，disabled = 无限制。
OMNIROUTE_PAYLOAD_RULES_PATH	./config/payloadRules.json	open-sse/services/payloadRules.ts	载荷操作规则 JSON 文件的路径（针对各模型/协议的上游调整）。
OMNIROUTE_PAYLOAD_RULES_RELOAD_MS	5000	open-sse/services/payloadRules.ts	热重载载荷规则文件的时间间隔（毫秒）。最小值为 1000。
OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS	false	open-sse/services/model.ts	可选启用：将来自 Claude Code 客户端且不含提供者前缀的 claude-* 模型 ID 路由到 Claude Code OAuth 账户，而不是要求提供者前缀。显式提供者前缀仍然优先。也可通过 Claude 提供者页面上的仪表板开关进行配置。
COMBO_CONCURRENCY_PER_MODEL	3	open-sse/services/comboConfig.ts	轮询组合中每个模型的并发上限（#9100）。轮询组合信号量此前硬编码为每个模型最多 3 个并发请求且无法覆盖，导致更高并发的流量在该上限之后被串行处理。该值会验证为 >= 1，并限制为 <= 32。
DISABLE_CONTEXT_WINDOW_CHECKS	false	open-sse/handlers/chatCore.ts	危险的可选设置，用于跳过 OmniRoute 针对直接单模型请求执行的本地上下文窗口/最大输入令牌检查。上游提供者仍会强制执行其实际限制；提示词压缩和模型自身的输出令牌上限仍然有效。生效优先级为功能标志数据库覆盖 > 环境变量 > 默认值；无需重启。
OMNIROUTE_SELF_HOSTED_PROVIDERS	(未设置)	open-sse/services/selfHostedEntry.ts	内联 YAML providers: 文档（RIC-738、D4）。设置后（无论是否包含 strategy: 块），/v1/chat/completions 都会转到自托管的统一 OpenAI 兼容入口，而不是云端管线。未设置（默认值）时：该路由会直接进入现有云端管线。请参阅 docs/routing/SELF_HOSTED_OPENAI_ENTRY.md。
OMNIROUTE_SELF_HOSTED_PROVIDERS_FILE	(未设置)	open-sse/services/selfHostedEntry.ts	YAML 文件的路径，该文件包含与 OMNIROUTE_SELF_HOSTED_PROVIDERS 相同的 providers: 文档，适用于偏好使用文件而非内联环境变量的部署。设置其中任意一个都会激活自托管入口。
OMNIROUTE_SELF_HOSTED_API_KEY	(未设置 — 开放路由)	open-sse/services/selfHostedEntry.ts	统一自托管入口的可选共享 API 密钥（D5 脚手架，为按密钥配额系统预留）。设置后，请求必须包含 Authorization: Bearer &lt;key&gt;。未设置时：路由保持开放，与现有自托管本地提供者模式一致（环回地址/可信网络部署）。
OMNIROUTE_SELF_HOSTED_STRATEGY	(未设置)	open-sse/services/routingStrategies.ts	确定性路由引擎的内联 YAML strategy: 文档（M2/RIC-740、D3）— 黑名单/白名单、冷却断路器、成本优先、延迟感知、回退链。按密钥覆盖嵌套在 OMNIROUTE_SELF_HOSTED_PROVIDERS 内的内联 strategy: 块。请参阅 docs/routing/DETERMINISTIC_ROUTING.md。
OMNIROUTE_SELF_HOSTED_STRATEGY_FILE	(未设置)	open-sse/services/routingStrategies.ts	YAML 文件的路径，该文件包含与 OMNIROUTE_SELF_HOSTED_STRATEGY 相同的 strategy: 文档，适用于偏好使用文件而非内联环境变量的部署。
OMNIROUTE_DISABLE_CONVERSATION_TRACKING	（未设置）	open-sse/services/conversationTracker.ts	设置为 1 可停止收集对话历史记录。resolveConversationId() 会在读取 SQLite 或解析消息历史记录之前返回未跟踪结果，客户端提供的会话 ID 也包括在内。路由会话的处理方式保持不变，现有记录不会被删除。适用于不使用仪表板对话视图，并希望回合表停止增长的部署。

---

7. URL 与云同步

变量	默认值	源文件	说明
BASE_URL	http://localhost:20128	src/lib/cloudSync.ts	供服务器端内部同步任务调用 /api/sync/cloud 的 URL。即使应用通过公共代理对外提供服务，也应将其保留为环回地址/容器 URL。
CLOUD_URL	（空）	src/lib/cloudSync.ts	云中继端点 URL（高级功能）。
CLOUD_SYNC_TIMEOUT_MS	12000	src/lib/cloudSync.ts	云同步请求的 HTTP 超时时间。
OMNIROUTE_BUILD_PROFILE	full	Webpack 构建配置	构建时配置文件（设置为 minimal 可从 bundle 中实际排除特权模块）。
OMNIROUTE_STANDALONE_DIR	.build/ 独立输出	scripts/build/colocate-standalone.mjs	对构建后共置步骤所使用的独立输出目录进行构建时覆盖。并非运行时设置。
OMNIROUTE_CLOUD_SYNC_SECRET	（空）	src/lib/cloudSync.ts	用于验证云同步响应的 HMAC-SHA256 签名的共享密钥。
OMNIROUTE_CLOUD_SYNC_SECRETS	false	src/lib/cloudSync.ts	设置为 true，允许云同步端点覆盖本地凭据。默认值为 false。
OMNIROUTE_CLOUD_SYNC_ENFORCE_SIGNATURE	false	src/lib/cloudSync.ts	设置为 true，可在未配置本地密钥时拒绝未签名的云同步响应（#13679）。无论此标志如何，只要响应中存在签名，就始终会对其进行验证；当未设置 OMNIROUTE_CLOUD_SYNC_SECRET 时，该响应也始终会被拒绝。从 v3.9 开始，默认行为将改为强制执行签名验证。
OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP	false	src/app/api/providers/zed/import/route.ts	设置为 true，可在未经用户确认的情况下回退到 v3.8.5 的一步式“导入所有内容”行为。
NEXT_PUBLIC_BASE_URL	http://localhost:20128	OAuth、仪表板、同步	用于 OAuth redirect_uri、仪表板链接和生成的公共 URL 的对外 URL。当 OAuth 回调或生成的浏览器链接必须使用规范的反向代理主机时，请将其设置为稳定的公共 URL。
NEXT_PUBLIC_CLOUD_URL	（空）	客户端	CLOUD_URL 的客户端镜像。
NEXT_PUBLIC_APP_URL	（未设置）	src/shared/services/cloudSyncScheduler.ts	NEXT_PUBLIC_BASE_URL 的旧版回退项。
NEXT_PUBLIC_PORT	（未设置——回退到 PORT）	src/shared/hooks/useDisplayBaseUrl.ts	未知来源（SSR/测试）时，用于显示 URL 的客户端回退端口；读取优先级高于 PORT。
OMNIROUTE_PUBLIC_BASE_URL	（未设置）	公共来源解析器、图像 URL	面向浏览器的 OmniRoute 来源，具有最高优先级，用于生成公共 URL 和非仪表板浏览器来源验证。当 OpenWebUI 或其他中继通过内部 URL 访问 OmniRoute，但用户浏览器必须从局域网、隧道或公共来源获取生成的媒体时，请设置此项。请勿包含 /v1。
OMNIROUTE_PROVIDER_MANIFEST_URL	（未设置）	open-sse/config/providerPluginManifestUrl.ts	向 sidecar 客户端公布的提供者插件清单绝对 URL。未设置时，OmniRoute 会根据请求来源或 HOST/PORT 派生 /api/v1/provider-plugin-manifest。
OMNIROUTE_PUBLIC_PROTOCOL	http	open-sse/config/providerPluginManifestUrl.ts	在没有请求来源的情况下根据 HOST/PORT 派生提供者插件清单 URL 时使用的协议。如果位于终止 TLS 的公共代理后方，且未显式设置 OMNIROUTE_PROVIDER_MANIFEST_URL，请将其设置为 https。
OMNIROUTE_TRUST_PROXY	（未设置）	src/server/origin/publicOrigin.ts	转发公共来源标头的可选信任模式。未设置 = 不信任 Forwarded / X-Forwarded-*，不将其用于安全决策。true / loopback 仅信任来自带令牌标记的回环代理所转发的主机/协议。private / lan 还信任私有局域网代理对等方。生产环境中建议显式设置 NEXT_PUBLIC_BASE_URL。
KIE_CALLBACK_URL	（未设置）	open-sse/utils/kieTask.ts	异步 kie.ai 作业的公共回调 URL。优先级最高，高于 OMNIROUTE_KIE_CALLBACK_URL 和 OMNIROUTE_PUBLIC_URL。
OMNIROUTE_KIE_CALLBACK_URL	（未设置）	open-sse/utils/kieTask.ts	KIE_CALLBACK_URL 的另一种写法。主变量未设置时回退到此项。
OMNIROUTE_PUBLIC_URL	（未设置）	open-sse/utils/kieTask.ts	用于构建异步回调 URL 的公共来源。kie.ai 回调的最低优先级回退项；也用作其他中继的通用公共 URL。
OMNIROUTE_CROF_USAGE_URL	https://crof.ai/usage_api/	open-sse/services/usage.ts	“用量”页面使用的 CrofAI 配额查询端点。可针对中继/测试固件进行覆盖。
OMNIROUTE_OPENCODE_QUOTA_URL	https://opencode.ai/zen/go/v1/usage	open-sse/services/opencodeQuotaFetcher.ts	“用量”页面使用的、通过 API 密钥认证的官方 OpenCode Go 用量端点。可针对中继/测试固件进行覆盖。
OPENCODE_SYNTHESIZE_CLI_HEADERS	true	open-sse/executors/opencode.ts	对于客户端未发送相关标头的 opencode-go/zen 上游请求，合成 OpenCode CLI 身份标头（User-Agent、x-opencode-client/project、请求/会话 UUID），以便 VPS 出口处的 Cloudflare 接受这些请求（#6210/#5997）。自 #10571 起默认启用；可使用 false/0/no/off 选择退出。
OPENCODE_USER_AGENT	opencode/1.18.31	open-sse/utils/opencodeHeaders.ts	当 OPENCODE_SYNTHESIZE_CLI_HEADERS 启用且未设置每个提供者的 <PROVIDER>_USER_AGENT 覆盖项时使用的默认 User-Agent。仅应用于 opencode 执行器。对于被上游网关拦截的无密钥请求，如果配置的值不包含 opencode/<version >= 1.17>，则会将其替换为此默认值，而不是拒绝请求。
OPENCODE_CLIENT	desktop	open-sse/executors/opencode.ts	启用 OPENCODE_SYNTHESIZE_CLI_HEADERS 时，为合成的 x-opencode-client 标头指定的值。
OPENCODE_PROJECT	global	open-sse/executors/opencode.ts	启用 OPENCODE_SYNTHESIZE_CLI_HEADERS 时，为合成的 x-opencode-project 标头指定的值。
OPENCODE_FREE_TIER_REQUEST_CONTRACT	(未设置)	open-sse/executors/opencodeFreeTierContract.ts	设置为 off 可停止调整无密钥 OpenCode 请求的正文（流式传输标志和工具列表）。仍会应用标头。此变量按请求读取，因此更改会立即生效。
OPENCODE_FREE_TIER_PLACEHOLDER_TOOLS	(未设置)	open-sse/executors/opencodeFreeTierContract.ts	当无密钥 OpenCode 请求未携带任何工具，且尚未观察到该模型使用过任何工具时，用于声明工具名称的逗号分隔列表。空值会回退为一个占位工具，并告知模型不要调用它。最多 32 项，格式为 [A-Za-z_][A-Za-z0-9_-]{0,63}；无效项会被忽略。
OMNIROUTE_OLLAMA_CLOUD_USAGE_URL	https://ollama.com/settings	open-sse/services/usage.ts	用于抓取配额信息的 Ollama Cloud 设置 URL。可针对中继服务或测试夹具进行覆盖。
OLLAMA_USAGE_COOKIE	(未设置)	open-sse/services/usage.ts	用于从设置页面抓取配额信息的 Ollama Cloud __Secure-session cookie。此信息敏感；配置多个账户时，建议优先使用每个连接对应的控制面板字段。
OLLAMA_CLOUD_USAGE_COOKIE	(未设置)	open-sse/services/usage.ts	Ollama Cloud __Secure-session cookie 的备用环境变量。此信息敏感；配置多个账户时，建议优先使用每个连接对应的控制面板字段。
OMNIROUTE_OLLAMA_USAGE_COOKIE	(未设置)	open-sse/services/usage.ts	在较短别名之前使用的 Ollama Cloud __Secure-session cookie 备用环境变量。此信息敏感；配置多个账户时，建议优先使用每个连接对应的控制面板字段。
OMNIROUTE_CODEWHISPERER_BASE_URL	https://codewhisperer.us-east-1.amazonaws.com	open-sse/services/usage.ts	CodeWhisperer（AWS Kiro）用量限制端点。可针对中继服务或测试夹具进行覆盖。

[!IMPORTANT] 在反向代理（nginx、Caddy）后部署时，如果 OAuth 回调或生成的公开链接必须使用该主机名，请将 NEXT_PUBLIC_BASE_URL 设置为稳定的公开 URL（例如 https://omniroute.example.com）。否则，OAuth 回调可能会因 redirect_uri 不匹配而失败，生成的公开链接也可能指向容器内部源。

对于服务器到服务器的任务，请将 BASE_URL 保持为内部回环/容器 URL。不要将浏览器 Origin 或公开主机名用于携带凭据的内部自获取请求。

已认证的控制面板写入操作不需要静态公开基础 URL：控制面板会发送带有会话绑定 CSRF 令牌的同源非安全请求。OmniRoute 仍会集中验证非控制面板浏览器集成的公开源：首先信任显式配置的公开 URL 环境变量；除非启用了 OMNIROUTE_TRUST_PROXY，且直接代理对等方通过令牌标记为可信，否则会忽略原始 Forwarded / X-Forwarded-* 标头。不要使用 CORS 设置来修复同源控制面板请求；CORS 仅适用于跨源浏览器客户端。

---

8. 出站代理

通过 HTTP 或 SOCKS5 代理路由上游 LLM 提供者调用，以实现出站流量控制、地理路由或 IP 隐藏。

变量	默认值	源文件	描述
ENABLE_SOCKS5_PROXY	true	open-sse/executors	为上游调用启用 SOCKS5 代理。设置为 false 可选择停用。
NEXT_PUBLIC_ENABLE_SOCKS5_PROXY	true	客户端	让客户端感知 SOCKS5 的可用性。
PROXY_SKIP_RECENTLY_FAILED	false	src/shared/utils/featureFlags.ts	可选择启用的功能标志（参见 FEATURE_FLAGS.md；控制面板数据库中的覆盖配置优先）。代理池和按账户轮换机制会在一段时间内停止再次提供刚刚失败的成员（TCP 探测被拒绝，或通过该成员时收到 429）；每次重复失败时，该时间段都会翻倍，直至达到上限。设置为 true（或 1、yes）可启用。
HTTP_PROXY	（未设置）	Node.js 标准	用于上游调用的 HTTP 代理。
HTTPS_PROXY	（未设置）	Node.js 标准	用于上游调用的 HTTPS 代理。
ALL_PROXY	（未设置）	Node.js 标准	通用代理（支持 socks5://）。
OMNIROUTE_PROXY_ECHO_URL	（未设置）	src/lib/proxyEchoTarget.ts	将代理出站探测使用的回显 IP 目标固定为单个 URL。未设置时，探测会依次尝试 api64.ipify.org 和 api4.ipify.org，以免将仅支持 IPv4 的隧道误报为不可用（#9694）。
NO_PROXY	（未设置）	Node.js 标准	绕过代理的主机名/IP 列表，以逗号分隔。
OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS	32	open-sse/utils/proxyDispatcher.ts	每个缓存的 HTTP/SOCKS 代理调度器允许的最大并发套接字数。当多个请求共享同一个账户级代理时，Codex /v1/responses 等长连接 SSE 流需要多个连接。超过 256 的值会被限制为 256。
SOCKS_HANDSHAKE_TIMEOUT_MS	10000	open-sse/utils/socksConnectorWithFamily.ts	SOCKS5 握手（连接）超时时间，单位为毫秒。当单个住宅网关主机承受高并发时（例如 100 个并发请求），请增大此值——即使代理可达，在池已饱和的情况下，实际握手也可能超过 10 秒，否则会错误地显示为 [Proxy Fast-Fail] Proxy unreachable。最大值限制为 120000。
PROXY_FAIL_OPEN	false	src/sse/handlers/chatHelpers.ts	当设置为 false（默认值）时，已分配代理但代理解析失败的请求会被拒绝（故障关闭），而不是回退到直接连接，从而防止真实 IP 泄露。设置为 true 可恢复旧版的 DIRECT 回退行为。
ENABLE_TLS_FINGERPRINT	false	open-sse/executors	使用 wreq-js 伪装 TLS 指纹（模拟 Chrome 124）。用于应对 JA3/JA4 封锁。
TLS_FINGERPRINT_PROVIDERS	（未设置）	open-sse/utils/proxyFetch.ts	用于新代理 TLS 路由（open-sse/utils/proxyFetch.ts）的逗号分隔提供者允许列表。未设置时，直连 TLS 保持其旧有行为；只有这些提供者会通过 Chrome-124 指纹桥接器进行路由。
OMNIROUTE_TURNSTILE_IGNORE_TLS_ERRORS	false	open-sse/services/claudeTurnstileSolver.ts	允许 Claude Turnstile Playwright 浏览器上下文忽略 HTTPS 证书错误。

场景

场景	配置
通过 SSH 隧道使用 SOCKS5	ALL_PROXY=socks5://127.0.0.1:7890, ENABLE_SOCKS5_PROXY=true
企业 HTTP 代理	HTTP_PROXY=http://proxy.corp.com:3128, HTTPS_PROXY=http://proxy.corp.com:3128, NO_PROXY=localhost,internal.corp.com
反指纹识别	ENABLE_TLS_FINGERPRINT=true — 需要 wreq-js（已包含）
出口受控／禁止直接访问	保持 PROXY_FAIL_OPEN=false（默认值）。代理不可用时，请求会直接失败，而不会通过直连泄露。
旧版／开发环境 — 允许直连回退	PROXY_FAIL_OPEN=true。恢复强化前的行为：代理解析失败时使用直接连接。

注意（NVIDIA 验证绕过 — #3226）： NVIDIA 的 API 密钥验证端点 通过全局代理／TLS 补丁后的 fetch 路由时会停滞（undici dispatcher → 504）。 src/lib/providers/validation.ts::directHttpsRequest() 有意使用 safeOutboundFetch({ bypassProxyPatch: true }) 绕过该单次验证调用的代理补丁。 这是一个已有文档记录且范围受限的例外——它不会影响聊天／用量流出流量。 tests/unit/proxy-bypass-scope-guard-3226.test.ts 对该绕过的作用域进行了固定限制。

---

9. CLI 工具集成

控制 OmniRoute 如何发现和启动 CLI 边车（Claude Code、Codex 等）。

变量	默认值	源文件	描述
CLI_MODE	auto	src/shared/services/cliRuntime.ts	auto = 搜索系统 PATH；manual = 仅使用显式路径。
CLI_EXTRA_PATHS	（未设置）	src/shared/services/cliRuntime.ts	用于发现 CLI 二进制文件的额外 PATH 条目（以冒号分隔）。
CLI_CONFIG_HOME	（未设置）	src/shared/services/cliRuntime.ts	覆盖用于读取 CLI 配置（~/.claude、~/.codex）的主目录。该路径必须是绝对路径且位于进程主目录内——或者，在容器中是一个绑定挂载路径（/host-home 正是以这种方式工作）。其他任何路径都会回退到主目录。
CLI_ALLOW_CONFIG_WRITES	true	src/shared/services/cliRuntime.ts	允许 OmniRoute 写入 CLI 配置文件（令牌刷新、会话数据）。设置为 false 后，每次写入 CLI 配置都会失败，并显示明确的“已禁用写入”错误。
CLI_CLAUDE_BIN	claude	src/shared/services/cliRuntime.ts	Claude CLI 二进制文件的自定义路径。
CLI_CODEX_BIN	codex	src/shared/services/cliRuntime.ts	Codex CLI 二进制文件的自定义路径。
CLI_DROID_BIN	droid	src/shared/services/cliRuntime.ts	Droid CLI 二进制文件的自定义路径。
CLI_OPENCLAW_BIN	openclaw	src/shared/services/cliRuntime.ts	OpenClaw CLI 二进制文件的自定义路径。
CLI_CURSOR_BIN	agent，然后是 cursor	src/shared/services/cliRuntime.ts	Cursor agent 二进制文件的自定义路径。如果未指定，检测时会先尝试 agent，失败后回退到 cursor。
CLI_CLINE_BIN	cline	src/shared/services/cliRuntime.ts	Cline CLI 二进制文件的自定义路径。
CLI_5DIVE_BIN	5dive	src/shared/services/cliRuntime.ts	5dive CLI 二进制文件的自定义路径。
CLI_5DIVE_STATE_DIR	/var/lib/5dive	src/shared/services/cliRuntime.ts	5dive 的系统状态目录（由 root 所有的身份验证配置文件）；与 5dive 自身的 STATE_DIR 默认值一致。
CLI_CONTINUE_BIN	cn	src/shared/services/cliRuntime.ts	Continue CLI 二进制文件的自定义路径。
CLI_QODER_BIN	qodercli	src/shared/services/cliRuntime.ts	Qoder CLI 二进制文件的自定义路径。
CLI_QWEN_BIN	qwen	src/shared/services/cliRuntime.ts	Qwen Code CLI 二进制文件的自定义路径。
CLI_AIDER_BIN	aider	src/shared/services/cliRuntime.ts	Aider CLI 二进制文件的自定义路径。
CLI_GOOSE_BIN	goose	src/shared/services/cliRuntime.ts	Goose CLI 二进制文件的自定义路径。
CLI_GEMINI_BIN	gemini	src/shared/services/cliRuntime.ts	Google Gemini CLI 二进制文件的自定义路径——仅用于服务端检测/健康检查；omniroute run gemini 会从系统 PATH 中解析 gemini 二进制文件。
CLI_KILO_BIN	kilocode	src/shared/services/cliRuntime.ts	Kilo Code CLI 二进制文件的自定义路径。
CLI_OPENCODE_BIN	opencode	src/shared/services/cliRuntime.ts	OpenCode CLI 二进制文件的自定义路径。
CLI_HERMES_BIN	hermes	src/shared/services/cliRuntime.ts	Hermes 二进制文件的自定义路径。由两个目录条目（hermes 和 hermes-agent）共享。
CLI_FORGE_BIN	forge	src/shared/services/cliRuntime.ts	ForgeCode CLI 二进制文件的自定义路径。
CLI_JCODE_BIN	jcode	src/shared/services/cliRuntime.ts	jcode CLI 二进制文件的自定义路径。
CLI_DEEPSEEK_TUI_BIN	deepseek-tui	src/shared/services/cliRuntime.ts	DeepSeek TUI 二进制文件的自定义路径。
CLI_CODEWHALE_BIN	codewhale	src/shared/services/cliRuntime.ts	CodeWhale CLI 二进制文件的自定义路径。
CLI_SMELT_BIN	smelt	src/shared/services/cliRuntime.ts	Smelt CLI 二进制文件的自定义路径。
CLI_PI_BIN	pi	src/shared/services/cliRuntime.ts	Pi（pi-coding-agent）二进制文件的自定义路径。
CLI_CRUSH_BIN	crush	src/shared/services/cliRuntime.ts	Crush CLI 二进制文件的自定义路径。
CLI_OMP_BIN	omp	src/shared/services/cliRuntime.ts	Oh My Pi（omp）代理二进制文件的自定义路径。
CLI_LETTA_BIN	letta	src/shared/services/cliRuntime.ts	Letta CLI 二进制文件的自定义路径。
CLI_PRIME_AGENT_BIN	prime-agent	src/shared/services/cliRuntime.ts	Prime Agent（Prime Intellect）二进制文件的自定义路径。
CLI_WINDSURF_BIN	（无）	src/shared/services/cliRuntime.ts	Windsurf 二进制文件的自定义路径。Windsurf 不提供默认命令——在设置此项之前，二进制文件检测将保持禁用状态。
CLI_DEVIN_BIN	devin	open-sse/executors/devin-cli.ts	Devin CLI 二进制文件（v3.8.0）的自定义路径。由 Windsurf/Devin 执行器使用。
DEVIN_DESKTOP_VERSION	3.6.27	open-sse/executors/devin-desktop.ts	Devin Desktop 的 ide_version。覆盖值必须使用 x.y.z 格式；无效值将回退到经过验证的默认值。
DEVIN_DESKTOP_EXTENSION_VERSION	1.48.2	open-sse/executors/devin-desktop.ts	内置 Codeium/language-server 的 extension_version，与 Desktop 的 ide_version 不同。覆盖值必须使用 x.y.z；无效值将使用内置默认值。
CLI_DEVIN_AGENTIC_BIN	devin	open-sse/executors/devin-cli-agentic.ts	仅限智能体桥接器使用的 Devin CLI 覆盖值。该执行器仅接受本地 ACP stdio 上游。
DEVIN_AGENTIC_HOME	（必需）	open-sse/executors/devin-cli-agentic.ts	智能体 Devin 子进程使用的绝对隔离主目录；可接受的桥接路径为 /home/bridge 和任务本地的 .sandbox 路径（在 Windows 上为 C:\...\.sandbox\...）。
DEVIN_AGENTIC_ACP_TIMEOUT_MS	120000	open-sse/executors/devin-cli-agentic.ts	单次 Devin ACP 轮次的最长持续时间；超时后，桥接器将终止子进程并返回明确的超时信息。
DEVIN_BRIDGE_MODEL	devin-cli-agentic/swe-1-7	docker/devin-bridge/compose.yml	隔离桥接器的主要 Claude Code 模型别名。实时测试工具会将该示例替换为当前 Devin 账户返回的模型。
DEVIN_BRIDGE_SONNET_MODEL	DEVIN_BRIDGE_MODEL	docker/devin-bridge/compose.yml	Claude Code 请求其默认 Sonnet 模型时使用的隔离桥接器别名。
DEVIN_BRIDGE_OPUS_MODEL	DEVIN_BRIDGE_MODEL	docker/devin-bridge/compose.yml	Claude Code 请求其默认 Opus 模型时使用的隔离桥接器别名。
DEVIN_BRIDGE_HAIKU_MODEL	DEVIN_BRIDGE_MODEL	docker/devin-bridge/compose.yml	Claude Code 请求其默认 Haiku 模型时使用的隔离桥接器别名。
DEVIN_BRIDGE_SUBAGENT_MODEL	DEVIN_BRIDGE_MODEL	docker/devin-bridge/compose.yml	用于 Claude Code 子智能体的隔离桥接器别名。
DEVIN_SEAT_API_URL	https://server.codeium.com	open-sse/services/usage/devinCli.ts	Devin CLI 配额所使用的 Codeium 席位管理 API（GetUserStatus）的可选覆盖值。
AUGGIE_BIN	auggie	open-sse/executors/auggie.ts	本地 auggie 提供者所使用的 Augment（Auggie）CLI 二进制文件的绝对路径覆盖值。若未设置，则依次回退到 CLI_AUGGIE_BIN 和 PATH 查找。
CLI_AUGGIE_BIN	auggie	open-sse/executors/auggie.ts	Augment（Auggie）CLI 二进制文件路径的别名覆盖值（在 AUGGIE_BIN 之后检查）。
ZCODE_BIN	zcode	open-sse/executors/zcode.ts	本地 zcode 提供者的 stdio 客户端所使用的二进制文件。若未设置，则回退到 PATH 中的 zcode。
ZCODE_ARGS	—	open-sse/executors/zcode.ts	通过 cliTools 启动时传递给 zcode 二进制文件的额外参数 JSON 数组（不超过 16 个字符串）。
ZCODE_CWD	process.cwd()	open-sse/executors/zcode.ts	ZCode 应用服务器子进程的工作目录。
ZCODE_PROVIDER_ID	builtin:zai-coding-plan	open-sse/executors/zcode.ts	发送到应用服务器的提供者 ID 的覆盖值。
ZCODE_SERVER_RUNTIME_ROOT	~/.zcode/server	open-sse/executors/zcode.ts	ZCode 应用服务器运行时的根目录（内含捆绑的 node 和 zcode-server.cjs）。
ZCODE_SERVER_NODE	<runtimeRoot>/node	open-sse/executors/zcode.ts	用于托管 ZCode 应用服务器的 Node 可执行文件。
ZCODE_SERVER_ENTRY	<runtimeRoot>/zcode-server.cjs	open-sse/executors/zcode.ts	用于托管 ZCode 服务器的应用服务器入口脚本。
ZCODE_STARTUP_TIMEOUT_MS	10000	open-sse/executors/zcode.ts	ZCode 应用服务器启动被视为失败前的启动超时时间（毫秒）。
ZCODE_RPC_TIMEOUT_MS	30000	open-sse/executors/zcode.ts	ZCode 应用服务器调用的单请求 RPC 超时时间（毫秒）。
ZCODE_TURN_TIMEOUT_MS	120000	open-sse/executors/zcode.ts	单次 ZCode 轮次在被监督器判定超时前的最长持续时间（毫秒）。
ZCODE_POLL_INTERVAL_MS	250	open-sse/executors/zcode.ts	轮询 ZCode 轮次是否完成的时间间隔（毫秒）。
HERMES_HOME	~/.hermes	src/lib/cli-helper/config-generator/hermesHome.ts	OmniRoute 读写 Hermes CLI 配置的 Hermes Agent 主目录。与 Hermes PowerShell 安装程序在 Windows 上设置的环境变量一致（%LOCALAPPDATA%\hermes）。

CLI 配置文件自动同步

这些功能标志需要主动启用，默认关闭。也可以从 CLI Code 仪表板中切换它们。

变量	默认值	源文件	描述
OMNIROUTE_AUTO_SYNC_CODEX_PROFILES	false	src/shared/constants/featureFlagDefinitions.ts	同步提供者模型后，自动根据实时目录重写 ~/.codex/*.config.toml 配置文件。需要启用 CLI_ALLOW_CONFIG_WRITES；绝不会更改当前/默认 Codex 配置、身份验证、Codex-lb 设置或提供者选择。
OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES	false	src/shared/constants/featureFlagDefinitions.ts	同步提供者模型后，自动根据实时目录重写 ~/.claude/profiles/<name>/settings.json Claude Code 配置文件。需要启用 CLI_ALLOW_CONFIG_WRITES；绝不会更改当前/默认 Claude 配置、身份验证或提供者选择。

Docker 示例

# 将主机二进制文件挂载到容器中，并告知 OmniRoute 它们的位置：
CLI_EXTRA_PATHS=/host-cli/bin
CLI_CONFIG_HOME=/host-home
CLI_ALLOW_CONFIG_WRITES=true
CLI_CLAUDE_BIN=/host-cli/bin/claude

CLI_CONFIG_HOME 仅在该路径实际从主机进行绑定挂载时生效——请将其与类似 ~/.codex:/host-home/.codex:rw 的挂载配置配合使用（请参阅 docker-compose.yml 中的 host 配置文件）。如果路径既不位于容器用户的主目录中，也不是绑定挂载路径，则会被忽略，因为写入其中的内容会在容器重新创建时丢失。

镜像以 USER node 身份运行，因此未挂载的 /root 不是有效的覆盖路径。

变量	默认值	源文件	说明
OMNIROUTE_CONTAINER	（自动）	src/shared/utils/containerEnv.ts	强制开启（1/true）或关闭（0/false）容器检测。仅在自动检测无法识别的运行时中需要。
OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE	false	src/shared/services/cliRuntime.ts	仍然允许将 CLI 工具配置写入容器中未挂载的路径。对应的 CLI 选项为 --allow-container-write。

CLI 二进制程序（omniroute）辅助变量

这些变量用于调整 omniroute CLI 二进制程序自身的行为（而非上述边车检测）。

变量	默认值	源文件	说明
OMNIROUTE_LANG	（系统）	bin/cli/i18n.mjs	强制指定 CLI 输出语言。使用 BCP-47 区域设置（例如 en、pt-BR）。覆盖系统区域设置环境变量（LC_ALL、LC_MESSAGES）。
OMNIROUTE_SHOW_LOG	（未设置）	bin/cli/runtime/processSupervisor.mjs	设置为 1，以便在监督模式下将服务器的 stdout/stderr 转发到终端。等同于 omniroute serve 的 --log 选项。
OMNIROUTE_CLI_TOKEN	（未设置）	bin/cli/api.mjs	作为 x-omniroute-cli-token 请求头注入的机器身份验证令牌。在任务 8.12 中自动生成。
OMNIROUTE_HTTP_TIMEOUT_MS	30000	bin/cli/api.mjs	CLI → 服务器请求的单次尝试 HTTP 超时时间（毫秒）。
OMNIROUTE_READY_TIMEOUT_MS	60000	bin/cli/utils/pid.mjs	CLI 在输出超时警告之前等待服务器健康检查端点的最长时间（毫秒）。适用于缓慢的冷启动（例如 Windows）。也可通过 --ready-timeout 设置。
OMNIROUTE_VERBOSE	0	bin/cli/api.mjs	设置为 1，以便在执行 CLI 命令期间将重试/退避诊断信息输出到 stderr。
OMNIROUTE_PLUGIN_PATH	（未设置）	bin/cli/plugins.mjs	用于发现 CLI 插件（omniroute-cmd-* 包）的自定义目录。未设置时默认为 ~/.omniroute/plugins/。仅限 CLI 使用——它永远不会传递到服务器端插件扫描器；后者由 OMNIROUTE_PLUGINS_DIR（第 2 节）指定。

---

10. 内部 Agent 与 MCP 集成

变量	默认值	源文件	描述
OMNIROUTE_BASE_URL	自动检测	open-sse/mcp-server/server.ts	MCP/A2A 工具访问 OmniRoute 时使用的显式 URL。覆盖 localhost 自动检测。
OMNIROUTE_API_KEY	（未设置）	MCP/A2A 模块	用于内部 MCP 工具和 A2A 技能调用的 API 密钥。
OMNIROUTE_API_KEY_ID	（未设置）	open-sse/mcp-server/audit.ts	用于 MCP 审计日志归属的密钥 ID。
ROUTER_API_KEY	（未设置）	旧版	OMNIROUTE_API_KEY 的旧版别名。
OMNIROUTE_A2A_HISTORY_RETENTION_DAYS	30	src/lib/a2a/taskManager.ts	A2A 任务历史记录在本地数据库中保留的天数，超过后每日清理任务将删除相应行。未设置、非数值或 <= 0 时回退为 30。
OMNIROUTE_A2A_MEMORY_HITS	1	src/lib/a2a/taskExecution.ts	A2A 内存命中可观测性功能的终止开关。设为 0 可完全跳过任务的内存召回查询；任何其他值（包括未设置）均保持启用。
OMNIROUTE_ISSUE_AGENT_ENABLED	false	src/app/api/issue-agent/runs/route.ts	启用离线/本地 Issue Agent 记录式分诊端点。除非明确运行本地记录式分诊工作流，否则请保持禁用。
OMNIROUTE_ISSUE_AGENT_TIMEOUT_MS	（未设置）	src/lib/issueAgent/execution.ts	单次 Issue Agent 记录式分诊运行的超时时间（毫秒）。该值受内部最大值限制；未设置或无效时回退为内置默认值。
OMNIROUTE_CONTEXT	（当前上下文）	bin/cli/program.mjs, bin/cli/api.mjs	omniroute 命令在 CLI 远程模式下使用的上下文/配置文件；覆盖本地上下文存储中的当前上下文。等同于 --context &lt;name&gt;。
OMNIROUTE_CONTEXT_KEYCHAIN_DISABLED	0	bin/cli/contexts.mjs	禁用用于 CLI 上下文凭据的可选 keytar 操作系统密钥链后端。启用后，凭据将继续存储在权限模式为 0600 的 config.json 中，并且 CLI 会发出一次性回退警告；适用于有意采用的无头/容器化运行环境。
OMNIROUTE_MCP_ENFORCE_SCOPES	false	open-sse/mcp-server/server.ts	对 MCP 工具调用强制实施基于作用域的访问控制。
OMNIROUTE_MCP_SCOPES	（全部）	open-sse/mcp-server/server.ts	逗号分隔的作用域：admin、combos、health、models、routing、budget、metrics、pricing、memory、skills。
OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS	false	open-sse/mcp-server/descriptionCompressor.ts	在序列化清单之前压缩 MCP 工具描述。启用值：1、true、on。
OMNIROUTE_MCP_DESCRIPTION_COMPRESSION	rtk	open-sse/mcp-server/descriptionCompressor.ts	压缩算法/配置。禁用值：0、false、off。
OMNIROUTE_MCP_FETCH_TIMEOUT_MS	10000	open-sse/mcp-server/fetchTimeout.ts	MCP 服务器内部管理读取操作（健康状态、弹性、组合、配额、用量）的中止时限（毫秒）。
OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS	60000	open-sse/mcp-server/fetchTimeout.ts	等待提供者响应的 MCP 跳转（route_request、web_search、web_fetch）的中止超时（毫秒）。
OMNIROUTE_CORPUS_CACHE_SIZE	5	src/lib/localCorpus/configured.ts	内存中缓存的本地语料库索引实例的最大数量（LRU，每个已索引的根目录对应一个实例）。最小限制为 1。
MODEL_SYNC_INTERVAL_HOURS	24	src/shared/services/modelSyncScheduler.ts	模型目录同步间隔（小时）。
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	src/lib/usage/providerLimits.ts	提供者速率限制和配额的轮询间隔。
PROVIDER_LIMITS_SYNC_SPACING_MS	1500	src/lib/usage/providerLimits.ts	批量同步期间连续 OAuth 配额获取之间的间隔（毫秒）；OAuth 连接会逐个获取，以避免对上游产生突发请求。设为 0 可停用间隔（并发获取）。
OMNIROUTE_QUOTA_FETCH_MIN_INTERVAL_MS	250	open-sse/services/quotaFetchThrottle.ts	每次请求的预检/监控路径中，连续上游配额获取之间的最小间隔（毫秒）；错开并发网络调用，使同一 IP 上的大量账户不会向上游发出突发请求。已接入 Codex（/wham/usage）、DeepSeek、Bailian（两个获取位置）、OpenCode 和 Crof 的配额获取器（#6009、#6911）。通用的 usage.ts::getUsageForProvider 分发路径（github/glm/minimax/nanogpt/xai/等）尚未覆盖——已另行跟踪。缓存命中不受影响。0 表示禁用；限制在 0..5000 范围内。
PROVIDER_LIMITS_POST_USAGE_REFRESH_DELAY_MS	5000	src/lib/usage/providerLimits.ts	实际发生用量事件后，刷新提供者限制前的延迟（毫秒），以便上游配额 API 有时间记录消耗量。
OMNIROUTE_LOGIN_BROWSER_PATH	自动检测	open-sse/services/adobeFireflyBrowserLogin.ts	用于 Adobe Firefly 交互式登录和后台续期的系统 Chrome 或 Edge 可执行文件的绝对路径。
ADOBE_FIREFLY_BROWSER_REFRESH	已启用	open-sse/services/adobeFireflySession.ts	通过账户级 Chrome CDP 会话保持 IMS 和浏览器风险状态为最新。设为 0 可禁用浏览器续期。
ADOBE_FIREFLY_SESSION_DISK	已启用	open-sse/services/adobeFireflySession.ts	将修复后的 Adobe 会话持久化到 DATA_DIR 下，以便在进程重启后继续使用。设为 0 可仅在内存中保留会话。
ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS	12000	open-sse/services/adobeFireflySession.ts	Adobe Firefly 生成请求提交之间的最小间隔（毫秒）；0 表示禁用间隔。
ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS	15000	open-sse/services/adobeFireflySession.ts	Adobe 每成功提交三次后的额外静默期（毫秒）。
ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS	8000	open-sse/services/adobeFireflyClient.ts	Adobe 暂时性 408 响应后的基础退避时间（毫秒）；在最多五次尝试中与提交间隔结合使用。
OMNIROUTE_DISABLE_BACKGROUND_SERVICES	false	src/instrumentation-node.ts	禁用所有后台服务（同步、定价、模型刷新）。适用于 CI/测试。
OMNIROUTE_ENABLE_RUNTIME_BACKGROUND_TASKS	（未设置）	src/lib/config/runtimeSettings.ts	在检测到自动化测试时强制启用后台任务。设为 1 可覆盖测试启发式判断。
OMNIROUTE_BUDGET_RESET_JOB_INTERVAL_MS	600000	src/lib/jobs/budgetResetJob.ts	预算重置检查周期（毫秒）。下限为 10000。
OMNIROUTE_CONNECTION_RECOVERY_INTERVAL_MS	60000	src/lib/quota/connectionRecovery.ts	主动连接冷却恢复周期（毫秒）：在请求热路径之外，重新验证瞬态 rate_limited_until 已过期的连接。下限为 5000。
OMNIROUTE_DISABLE_CONNECTION_RECOVERY	false	src/lib/quota/connectionRecovery.ts	禁用主动连接冷却恢复调度器（getProviderCredentials 中的惰性恢复仍然适用）。
OMNIROUTE_REASONING_CACHE_CLEANUP_INTERVAL_MS	1800000	src/lib/jobs/reasoningCacheCleanupJob.ts	推理缓存清理周期（毫秒）。下限为 60000。
OMNIROUTE_REASONING_MIN_BUDGET	未设置（禁用）	open-sse/services/reasoningTokenBuffer.ts	思考模型输出预算的可选下限：调用方的 max_tokens 若在 [256, floor) 范围内，则会提升至该下限（但不超过模型输出上限）。未设置 = 永不扩大客户端预算（#9507）。
OMNIROUTE_LOG_EXPORT_CRON	0 * * * *	src/lib/jobs/logExportJob.ts	调用日志导出任务的 Cron 表达式（UTC）；该任务会处理每个已启用的日志导出目标。
OMNIROUTE_CONFIG_HOT_RELOAD_MS	5000	src/lib/config/hotReload.ts	配置热重载的轮询间隔（毫秒）。低于 1000 的值会被拒绝。
OMNIROUTE_DISABLE_REDIS_AUTH_CACHE	（已启用）	src/lib/db/apiKeys.ts	设置为 1 可绕过基于 Redis 的 API 密钥身份验证缓存（强制从数据库读取）。
OMNIROUTE_RTK_TRUST_PROJECT_FILTERS	0	open-sse/services/compression/engines/rtk/filterLoader.ts	信任用户管理的 RTK 项目筛选规则，不执行严格的签名检查。
OMNIROUTE_LITE_MAX_TOOL_LENGTH	2000	open-sse/services/compression/lite.ts	未设置 lite.maxToolLength 时，Lite 主动截断工具结果的字符数上限。范围为 256–1000000。控制面板设置优先于此环境变量。
OMNI_COMPRESSION_WORKERS	2	open-sse/services/compression/compressionWorkerPool.ts	同步 RTK/Caveman 工作线程的最大并发数；超出的任务按 FIFO 顺序等待。
OMNI_COMPRESSION_WORKER_TIMEOUT_MS	120000	open-sse/services/compression/compressionWorkerPool.ts	每个任务的超时时间（毫秒）。超时的工作线程会被终止，请求则以开放失败方式返回，内容保持不变。
OMNI_COMPRESSION_WORKER_IDLE_MS	60000	open-sse/services/compression/compressionWorkerPool.ts	未使用的压缩工作线程被终止前的空闲生存时间（毫秒）。
COMPRESSION_PIPELINE_BREAKER_ENABLED	false	open-sse/services/compression/pipelineEngineBreaker.ts	T02 堆叠流水线中每个引擎的断路器总开关。选择启用（默认关闭）——启用后，跨请求反复抛出异常的引擎将在冷却期间被跳过（开放失败）；关闭 = 与旧版行为逐字节完全一致。
COMPRESSION_PIPELINE_BREAKER_THRESHOLD	3	open-sse/services/compression/pipelineEngineBreaker.ts	引擎断路器打开前，跨请求连续失败的次数。
COMPRESSION_PIPELINE_BREAKER_COOLDOWN_MS	30000	open-sse/services/compression/pipelineEngineBreaker.ts	已打开的引擎在进行半开探测前保持跳过状态的毫秒数。
COMPRESSION_CCR_RETRIEVAL_RAMP_FACTOR	2	open-sse/services/compression/engines/ccr/index.ts	T08/H8 CCR 检索反馈斜升系数：已存储块此前每被检索一次，其有效 minChars 就会线性提高（频繁检索的内容压缩程度更低；检索次数 >=3 = 永不压缩）。设为 1 可禁用斜升机制（仅在达到阈值时进行二元跳过）。
COMPRESSION_CCR_DURABLE_STORE	true	open-sse/services/compression/engines/ccr/index.ts	CCR 持久化块存储 (#9061)。使用 SQLite 作为内存存储的后端，使块在被 LRU 淘汰、TTL 到期、服务重启或检索请求落到其他实例后仍能保留。设置为 false 时，块仅保存在内存中。超过 512KB 的块以及云运行时中的块无论如何都仅保存在内存中。
COMPRESSION_PREFIX_FREEZE_ENABLED	false	open-sse/services/compression/prefixFreeze.ts	T08/H5 基于使用情况观测的前缀冻结总开关。选择启用（默认关闭） — 启用后，观测次数 >= 阈值的系统提示词将被视为稳定且可缓存的前缀，并在压缩过程中予以保留，即使提供者未被静态缓存启发式规则识别也是如此（冻结仅会保留，绝不会修改）。
COMPRESSION_PREFIX_FREEZE_THRESHOLD	3	open-sse/services/compression/prefixFreeze.ts	系统提示词在被视为已冻结的稳定前缀之前所需的观测次数。
OMNIROUTE_BOOTSTRAPPED	false	src/app/(dashboard)/dashboard/page.tsx	初始设置完成后由引导脚本设为 true。控制设置向导的可见性。
OMNIROUTE_ALLOW_BODY_PROJECT_OVERRIDE	0	open-sse/executors/antigravity.ts	应急开关：允许请求正文覆盖 Antigravity 项目字段。
ANTIGRAVITY_CREDITS	off	open-sse/services/antigravityCredits.ts	Google One AI 点数策略：off 表示从不注入点数，retry 表示在符合条件的配额 429 错误后注入一次，always 表示在首次请求时注入。
ANTIGRAVITY_ALLOW_SIGNATURE_BYPASS	0	open-sse/translator/request/openai-to-gemini.ts	当上游拒绝真实签名时，允许 Antigravity 请求转换器跳过其严格的 CLI 请求签名验证（调试/过时 CLI 模式）。非零值将启用绕过。
AGY_TOKEN_FILE	~/.gemini/antigravity-cli/antigravity-oauth-token	src/app/api/providers/agy-auth/apply-local/route.ts	覆盖 Antigravity CLI (agy) 的令牌文件路径，以用于自动检测本地登录导入。

OAuth CLI 桥接（内部）

变量	默认值	源文件	描述
OMNIROUTE_SERVER	自动检测	src/lib/oauth/config/index.ts	CLI↔OmniRoute 身份验证桥接的服务器 URL。
OMNIROUTE_TOKEN	（未设置）	src/lib/oauth/config/index.ts	CLI 桥接的身份验证令牌。
OMNIROUTE_USER_ID	cli	src/lib/oauth/config/index.ts	CLI 桥接会话的用户 ID。
SERVER_URL	（未设置）	src/lib/oauth/config/index.ts	OMNIROUTE_SERVER 的旧版别名。
CLI_TOKEN	（未设置）	src/lib/oauth/config/index.ts	OMNIROUTE_TOKEN 的旧版别名。
CLI_USER_ID	（未设置）	src/lib/oauth/config/index.ts	OMNIROUTE_USER_ID 的旧版别名。

---

11. OAuth 提供者凭据

本地开发的内置凭据。对于远程部署，请在每个提供者的开发者控制台中注册您自己的凭据。

变量	提供者	备注
CLAUDE_OAUTH_CLIENT_ID	Claude Code (Anthropic)	公共客户端 — 无需密钥。
CLAUDE_CODE_REDIRECT_URI	Claude Code	覆盖重定向 URI。默认值：https://platform.claude.com/oauth/code/callback
CODEX_OAUTH_CLIENT_ID	Codex / OpenAI	公共客户端。
GEMINI_OAUTH_CLIENT_ID	Gemini (Google)	需要匹配的 _SECRET。
GEMINI_OAUTH_CLIENT_SECRET	Gemini (Google)	—
KIMI_CODING_OAUTH_CLIENT_ID	Kimi Coding (Moonshot)	公共客户端。
MUSE_CODE_OAUTH_CLIENT_ID	Muse Code (Meta)	公共 Muse CLI 设备流客户端 ID 的可选覆盖。留空以使用内置的公共客户端。
ANTIGRAVITY_OAUTH_CLIENT_ID	Antigravity (Google)	需要匹配的 _SECRET。
ANTIGRAVITY_OAUTH_CLIENT_SECRET	Antigravity (Google)	—
GITHUB_OAUTH_CLIENT_ID	GitHub Copilot	公共客户端。
GHE_COPILOT_OAUTH_CLIENT_ID	GHE Copilot	GitHub Enterprise Copilot 的 OAuth 客户端 ID 的可选覆盖。未设置时，回退到 GITHUB_OAUTH_CLIENT_ID 的公共默认值。
COPILOT_INTEGRATION_ID	GitHub Copilot	在 Copilot-Integration-Id 和 Editor-Plugin-Version 头中发送的 GitHub Copilot 客户端集成 ID 的可选覆盖。默认为 copilot-developer-cli。
WINDSURF_API_KEY	Windsurf / Devin (v3.8)	当没有可用的每个连接凭据时，open-sse/executors/devin-cli.ts 使用的 API 密钥回退。可选。
CLI_DEVIN_BIN	Devin CLI (v3.8)	Devin CLI 二进制文件 (devin) 的自定义路径。由 open-sse/executors/devin-cli.ts 解析。
GITLAB_DUO_OAUTH_CLIENT_ID	GitLab Duo (v3.8)	GitLab Duo 的 OAuth 客户端 ID。在 https://gitlab.com/-/profile/applications 注册一个应用程序，重定向 URI 为 <NEXT_PUBLIC_BASE_URL>/callback，范围为 api, read_user, openid, profile, email。回退到 GITLAB_OAUTH_CLIENT_ID。
GITLAB_DUO_OAUTH_CLIENT_SECRET	GitLab Duo (v3.8)	GitLab Duo 的 OAuth 客户端密钥。可选 — PKCE 流程不需要密钥。回退到 GITLAB_OAUTH_CLIENT_SECRET。
GITLAB_DUO_BASE_URL	GitLab Duo (v3.8)	覆盖 GitLab 基本 URL（自托管 GitLab）。默认为 https://gitlab.com。回退到 GITLAB_BASE_URL。
GITLAB_BASE_URL	GitLab Duo (v3.8)	GITLAB_DUO_BASE_URL 的旧版备用方案。当 _DUO_ 变体未设置时使用。
GITLAB_OAUTH_CLIENT_ID	GitLab Duo (v3.8)	GITLAB_DUO_OAUTH_CLIENT_ID 的旧版备用方案，由 src/lib/oauth/constants/oauth.ts 使用。
GITLAB_OAUTH_CLIENT_SECRET	GitLab Duo (v3.8)	GITLAB_DUO_OAUTH_CLIENT_SECRET 的旧版备用方案，由 src/lib/oauth/constants/oauth.ts 使用。
QODER_OAUTH_CLIENT_SECRET	Qoder	—
QODER_OAUTH_AUTHORIZE_URL	Qoder	设置此项以启用 Qoder OAuth。
QODER_OAUTH_TOKEN_URL	Qoder	—
QODER_OAUTH_USERINFO_URL	Qoder	—
QODER_OAUTH_CLIENT_ID	Qoder	—
QODER_PERSONAL_ACCESS_TOKEN	Qoder	直接 API 密钥备用方案（绕过 OAuth）。
QODER_CLI_WORKSPACE	Qoder	Qoder CLI 的工作区 ID。
OMNIROUTE_QODER_WORKSPACE	Qoder	QODER_CLI_WORKSPACE 的别名。
QODER_CLI_CONFIG_DIR	Qoder	覆盖 Qoder CLI 配置目录（隔离的 PAT 会话，避免覆盖浏览器登录）。
BLACKBOX_WEB_VALIDATED_TOKEN	Blackbox Web	前端 tk 令牌，在 /api/chat 上作为 validated 发送。当 Blackbox 强制执行令牌匹配时需要；否则 OmniRoute 会回退到随机 UUID。参见问题 #2252。
VISION_BRIDGE_BASE_URL	Vision Bridge guardrail	用于非 Anthropic 视觉桥接调用的 OpenAI 兼容基础 URL。默认为旧版 OpenAI URL 环境变量或 api.openai.com。指向 OmniRoute 的 /v1 自循环或任何 OpenAI 兼容端点（Gemini OpenAI 兼容、OpenRouter）。问题 #2232。当 URL 是 OmniRoute 自己的 /v1 时，描述子请求会发送 x-omniroute-admission-bypass: internal 并使用已解析的自循环凭据（本地模式下的 sk_omniroute 哨兵，或 OMNIROUTE_API_KEY / ROUTER_API_KEY — #1350）进行身份验证，以便 REQUIRE_API_KEY=true 部署能够正常工作。
VISION_BRIDGE_API_KEY	Vision Bridge guardrail	上述 URL 的 API 密钥。覆盖每个提供者的 OpenAI / Google 环境变量，用于非 Anthropic 视觉桥接调用。Anthropic 模型保留其专用的 Anthropic 密钥路径。问题 #2232。
OMNIROUTE_VISION_BRIDGE_NEGATIVE_CACHE_MS	Vision Bridge guardrail	“无可用候选”路由结果的缓存时长，单位为毫秒（默认 30000）。无效或负值将回退到默认值；0 会禁用负缓存。来源：src/lib/guardrails/visionBridgeRouter.ts。

[!WARNING]

1. 前往 Google Cloud Console → Credentials
2. 创建一个 OAuth 2.0 客户端 ID（类型：“Web 应用程序”）
3. 将您的服务器 URL 添加为授权重定向 URI
4. 替换 .env 中的凭据值。

---

12. 提供者 User-Agent 覆盖

覆盖发送给每个上游提供者的 User-Agent 标头。执行器基类会在运行时动态解析此值：

process.env[`${PROVIDER_ID}_USER_AGENT`]

来源： open-sse/executors/base.ts → buildHeaders()

| 变量 | 默认值 | 何时更新 | | –––––––––––––––– | ——————————————— | ———————————————————————————————— | —————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————— | | CLAUDE_USER_AGENT | claude-cli/2.1.258 (external, cli) | 当 Anthropic 发布新的 CLI 版本时 | | CLAUDE_DISABLE_TOOL_NAME_CLOAK | false | executors/base.ts + executors/cliproxyapi.ts | 设置为 1/true，以便在两个发往 Anthropic 的路径（原生 OAuth 和 CLIProxyAPI）上，将第三方工具框架的工具名称原样转发给 Anthropic。默认情况下，执行器会确定性地为非 Claude Code 工具名称创建别名（如果存在 Claude Code 规范映射，则使用该映射；否则使用 PascalCase），并通过响应中的 _toolNameMap 将其还原，因此使用 snake_case 工具的框架不会因被识别为带有指纹特征的第三方客户端而遭到拒绝。仅用于调试。 | | CODEX_USER_AGENT | codex-cli/0.155.0 (Windows 10.0.26200; x64) | 当 OpenAI 更新 Codex CLI 时 | | CODEX_CLIENT_VERSION | 0.155.0 | 独立于完整 UA 字符串覆盖 Codex 客户端版本 | | CLAUDE_CODE_CLIENT_VERSION | 2.1.258 | 独立于 CLAUDE_USER_AGENT 覆盖所声明的 Claude Code 版本。Anthropic 会根据此值限制某些模型的访问（#12417）。 | | GITHUB_COPILOT_CLI_VERSION | 1.0.81-6 | 独立于 GITHUB_USER_AGENT 覆盖所声明的 Copilot CLI 版本 | | GITHUB_USER_AGENT | GitHubCopilotChat/0.54.0 | 当 GitHub Copilot Chat 更新时 | | ANTIGRAVITY_USER_AGENT | antigravity/2.0.1 darwin/arm64 | 当 Antigravity IDE 更新时 | | KIRO_USER_AGENT | AWS-SDK-JS/3.0.0 kiro-ide/1.0.0 | 当 Kiro IDE 更新时 | | KIRO_OAUTH_CLIENT_ID | kiro-cli | 覆盖 Kiro 社交设备代码的 clientId（公共 ID） | | KIRO_VERIFY_FULL_CRC | false | 选择启用：对 Kiro 事件流执行完整的逐帧消息 CRC 验证（用于调试损坏的流） | | QODER_USER_AGENT | Qoder-Cli | 当 Qoder CLI 更新时 | | CURSOR_USER_AGENT | Cursor/3.3 | 当 Cursor 更新时 |

[!TIP] 你可以使用 {PROVIDER_ID}_USER_AGENT 模式为任何提供者添加 User-Agent 覆盖。执行器会动态构造环境变量名称。

---

13. CLI 指纹兼容性

启用后，OmniRoute 会重新排列 HTTP 请求头和 JSON 正文字段，以匹配官方 CLI 工具的确切签名。这样既能保留您的代理 IP，又能降低账户被标记的风险。

源文件： open-sse/config/cliFingerprints.ts、open-sse/executors/base.ts

按提供者配置

变量	启用方式	效果
CLI_COMPAT_CODEX	=1	模拟 Codex CLI 请求签名
CLI_COMPAT_CLAUDE	=1	模拟 Claude Code 请求签名
CLI_COMPAT_GITHUB	=1	模拟 GitHub Copilot 请求签名
CLI_COMPAT_ANTIGRAVITY	=1	模拟 Antigravity 请求签名
CLI_COMPAT_CURSOR	=1	模拟 Cursor 请求签名
CLI_COMPAT_KIMI_CODING	=1	模拟 Kimi Coding 请求签名
CLI_COMPAT_KILOCODE	=1	模拟 Kilo Code 请求签名
CLI_COMPAT_CLINE	=1	模拟 Cline 请求签名

全局配置

变量	启用方式	效果
CLI_COMPAT_ALL	=1	一次性为所有提供者启用指纹兼容性。

Kimi Coding CLI 身份覆盖

变量	默认值	源文件	描述
KIMI_CLI_VERSION	1.36.0	src/lib/oauth/providers/kimi-coding.ts	覆盖 OAuth/API 调用期间发送的 Kimi CLI 版本。
KIMI_CODING_DEVICE_ID	（捕获的默认值）	src/lib/oauth/providers/kimi-coding.ts	覆盖客户端请求头中使用的已捕获 Kimi 设备 ID。

[!NOTE] 此功能可与 User-Agent 覆盖（§12）配合使用。指纹系统负责请求头排序和正文字段排序，而 User-Agent 覆盖负责具体的 UA 字符串。两者均可独立启用。

---

14. API 密钥提供者

用于采用直接身份验证的提供者的 API 密钥。首选设置方式： 控制面板 → 提供者 → 添加 API 密钥。

对于 Docker 或无头部署，也可以通过环境变量进行设置。

可识别的模式：{PROVIDER_ID}_API_KEY

变量	提供者
DEEPSEEK_API_KEY	DeepSeek
NVIDIA_API_KEY	NVIDIA NIM
JINA_AI_API_KEY	Jina AI（Foundation API + Reader 回退）
JINA_API_KEY	Jina AI（JINA_AI_API_KEY 的别名）
GEMINI_API_KEY	Gemini（Google AI Studio）嵌入 + 聊天回退
GOOGLE_API_KEY	Gemini（GEMINI_API_KEY 的别名）

[!NOTE] Groq、xAI、Mistral、Perplexity、Together AI、Fireworks、Cerebras、Cohere、Nebius 和 Qianfan 的静态 ${PROVIDER}_API_KEY 条目已在 v3.8.0 中移除，因为运行时不再读取这些条目——这些提供者仅依赖控制面板 / data/provider-credentials.json / 加密数据库。有关迁移路径，请参阅本文档底部的 审计：已移除/失效的变量 部分。

[!TIP] 通过控制面板设置的密钥会以加密形式存储在 SQLite 中，并且优先级高于环境变量。

Jina： 当存在控制面板中的 jina-ai（或共享的 jina-reader）连接时，jina-ai/… 嵌入、重排序、分类、分段以及 jina-search 不会计费到集群环境密钥，因为 getProviderCredentials 采用优先填充策略。仅当不存在可用的控制面板密钥时，才会使用 JINA_AI_API_KEY / JINA_API_KEY。调用日志会将环境变量回退来源记录为 connection_id=env:JINA_AI_API_KEY。Reader 卡片（jina-reader、r.jina.ai）绝不会为 /v1/embeddings 或 /v1/rerank 提供服务。

Gemini： gemini/gemini-embedding-2（别名 google/gemini-embedding-2）会优先使用控制面板中的 gemini 连接。仅当不存在可用的控制面板密钥时，才会使用 GEMINI_API_KEY / GOOGLE_API_KEY。调用日志会将环境变量回退来源记录为 connection_id=env:GEMINI_API_KEY。原生多模态流量通过 x-goog-api-key 访问 :embedContent / :batchEmbedContents——N 个 OpenAI input 项会生成 N 个向量。

---

15. 超时设置

所有值均以毫秒为单位。在 src/shared/utils/runtimeTimeouts.ts 中集中解析。

超时层级

REQUEST_TIMEOUT_MS（全局覆盖）
├─→ FETCH_TIMEOUT_MS（上游提供者调用，默认值：600000）
│   ├─→ FETCH_HEADERS_TIMEOUT_MS（继承自 FETCH_TIMEOUT_MS）
│   ├─→ FETCH_BODY_TIMEOUT_MS（继承自 FETCH_TIMEOUT_MS）
│   ├─→ TLS_CLIENT_TIMEOUT_MS（继承自 FETCH_TIMEOUT_MS）
│   │   └── TLS_FIRST_BYTE_WATCHDOG_MS（独立，默认值：10000）
│   ├── RESPONSES_FIRST_BYTE_TIMEOUT_MS（独立，默认值：15000）
│   ├── FETCH_CONNECT_TIMEOUT_MS（独立，默认值：30000）
│   └── FETCH_KEEPALIVE_TIMEOUT_MS（独立，默认值：4000）
├─→ STREAM_IDLE_TIMEOUT_MS（继承自 REQUEST_TIMEOUT_MS，默认值：600000）
├─→ STREAM_ACTIVE_TIMEOUT_MS（独立，默认值：1260000；设置为 0 时禁用）
├─→ STREAM_READINESS_TIMEOUT_MS（继承自 REQUEST_TIMEOUT_MS，默认值：80000）
├─→ STREAM_READINESS_MAX_TIMEOUT_MS（限制自适应就绪超时扩展，默认值：180000）
└─→ API_BRIDGE_PROXY_TIMEOUT_MS（继承自 REQUEST_TIMEOUT_MS，默认值：30000）
    ├─→ API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS（派生值，默认值：300000）
    ├── API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS（默认值：60000）
    ├── API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS（默认值：5000）
    └── API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS（默认值：0 = 禁用）

变量	默认值	描述
REQUEST_TIMEOUT_MS	（未设置）	全局快捷设置——覆盖 FETCH_TIMEOUT_MS 和 STREAM_IDLE_TIMEOUT_MS 的默认值。
FETCH_TIMEOUT_MS	600000	调用上游提供者时 HTTP 请求的总超时时间。
STREAM_IDLE_TIMEOUT_MS	600000	中止前允许上游原始字节之间保持静默的最长时间。扩展思考模型很少暂停超过 90 秒。
STREAM_ACTIVE_TIMEOUT_MS	1260000	活跃 SSE 流的最长总生命周期；不会因收到上游字节而重置，且独立于 REQUEST_TIMEOUT_MS。该值根据注册表中最大的单模型 timeoutMs（1200000，Codex）加上 60000 的余量得出，因此允许模型用完其完整时间预算，而不会在回答途中被终止。设置为 0 可禁用。
OMNIROUTE_SSE_COMMENTS	（已禁用）	OmniRoute 是否可以发出 SSE : 注释行（例如 : keepalive 心跳和 x-omniroute-* 元数据尾部信息）。默认禁用（#10524），因为严格兼容 OpenAI 的客户端会对每个 SSE 行执行 JSON.parse，并在遇到 : 注释时崩溃；data: 心跳不受影响。设置为 on/true/1/yes 可重新启用。由 open-sse/utils/sseHeartbeat.ts 使用。
STREAM_READINESS_TIMEOUT_MS	80000	接收首个非 ping SSE 事件的等待时间。设置 REQUEST_TIMEOUT_MS 时会继承其值。
STREAM_READINESS_MAX_TIMEOUT_MS	180000	对于大型、重度使用工具或高推理强度的流式请求，首个事件自适应就绪窗口的最大值。
OMNIROUTE_AGENT_GOAL_POLICY_ENABLED	true	/goal 启发式检测的终止开关。设置为 false/0/off 可完全禁用检测——就绪超时和流恢复永远不会因请求正文或标头而提高，从而缓解由客户端控制的超时放大问题。
OMNIROUTE_AGENT_GOAL_READINESS_MAX_TIMEOUT_MS	600000	检测到的 /goal 代理运行或通过 x-omniroute-agent-goal 强制指定的请求，其首个事件就绪窗口的最大值。
OMNIROUTE_AGENT_GOAL_STREAM_RECOVERY	true	为检测到的 /goal 代理运行自动启用早期流恢复。设置为 false/0/off 可禁用此目标特定的选择加入。此设置只能在运维人员默认配置的基础上添加恢复功能——绝不会覆盖通过 STREAM_RECOVERY_ENABLED/数据库设置明确选择停用的配置。
OMNIROUTE_CODEX_DROP_NONSTANDARD_EVENTS	true	移除会导致 OpenAI SDK 的 responses.stream() 返回 502 的非标准 codex.* SSE 事件（例如 codex.rate_limits）。默认开启（#11014）。设置为 0/false/no/off 可转发这些事件。
OMNIROUTE_CODEX_APPSERVER_WS	（未设置）	选择启用 Codex app-server 传输。该值为本地 codex app-server 边车的 WebSocket 端点（ws:///wss://）。同时设置端点和令牌后，Codex 请求将通过 JSON-RPC 路由到边车，而不是使用 HTTP Responses API。也可通过 providerSpecificData.codexAppServerUrl 为每个连接单独设置。由 open-sse/executors/codex/appServerConfig.ts 使用。
OMNIROUTE_CODEX_APPSERVER_WS_TOKEN	（未设置）	提供给 app-server 的内联能力/持有者令牌。每个连接的覆盖项：providerSpecificData.codexAppServerToken。
OMNIROUTE_CODEX_APPSERVER_WS_TOKEN_FILE	（未设置）	保存 app-server 能力令牌的文件路径（来自 codex app-server --ws-token-file）。未设置 OMNIROUTE_CODEX_APPSERVER_WS_TOKEN 时使用。每个连接的覆盖项：providerSpecificData.codexAppServerTokenFile。
OMNIROUTE_CODEX_APPSERVER_CWD	/tmp	app-server 执行轮次时所处的工作目录。每个连接的覆盖项：providerSpecificData.codexAppServerCwd。
OMNIROUTE_CODEX_APPSERVER_APPROVAL	（未设置）	传递给 app-server 执行轮次的审批策略（例如 never、on-request）。每个连接的覆盖项：providerSpecificData.codexAppServerApprovalPolicy。
OMNIROUTE_CODEX_APPSERVER_SANDBOX	（未设置）	传递给 app-server 执行轮次的沙箱策略（例如 read-only、workspace-write、danger-full-access）。未设置时，执行器默认为 workspace-write（已强化；之前为 danger-full-access）。每个连接的覆盖项：providerSpecificData.codexAppServerSandbox。
OMNIROUTE_CODEX_APPSERVER_AUTO_APPROVE	false	自动批准 app-server 自身的审批提示（在主机上执行命令/文件/权限操作）。默认关闭——提示会被自动拒绝；工具执行框架的工具调用不受影响（它们通过单独的 item/tool/call 透传）。接受 true/1/yes。每个连接的覆盖项：providerSpecificData.codexAppServerAutoApprove。
FETCH_HEADERS_TIMEOUT_MS	= FETCH_TIMEOUT_MS	接收响应标头的等待时间。
OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS	30000（30 秒）	每次不使用代理的直接连接尝试等待响应开始的最长时间（毫秒）。超时后会使用新套接字重试一次；设置为 0 可禁用此限制并保留之前的行为。
OMNIROUTE_DIRECT_RESPONSE_RETRY_TIMEOUT_MS	600000（10 分钟）	在上述使用连接池的尝试等待响应开始超时后，使用新套接字进行 RETRY 尝试的时限（毫秒）（#13703）。仅当调用方已附加自己的截止时间信号（由连接/model/provider/FETCH_TIMEOUT_MS 逐级解析所得）时适用；该信号才是真正的限制，并会在预期路径中率先触发，因此此项是一个宽松的后备限制，而非固定上限——如果没有此项，重试会复用与连接池尝试相同的短 OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS 时间窗口，导致健康但 TTFB 较慢的推理模型返回 504。绝不允许低于上述固定下限；当调用方完全未提供截止时间信号时，重试仍保持该固定下限不变。
FETCH_BODY_TIMEOUT_MS	= FETCH_TIMEOUT_MS	接收完整响应正文的时间。
FETCH_CONNECT_TIMEOUT_MS	30000	TCP 连接建立超时时间。
FETCH_KEEPALIVE_TIMEOUT_MS	4000	Keep-alive 套接字空闲超时时间。
TLS_CLIENT_TIMEOUT_MS	= FETCH_TIMEOUT_MS	TLS 指纹代理（wreq-js）超时时间。
TLS_FIRST_BYTE_WATCHDOG_MS	10000	专门限制 wreq-js TLS 指纹传输正文的首字节响应时间；仅使用 TLS_CLIENT_TIMEOUT_MS 无法捕获正文停滞，因为它会在响应头到达后立即完成（#12656）。超时会取消 wreq 读取器，并回退到直接/代理调度器；设置为 0 可禁用此看门狗。
RESPONSES_FIRST_BYTE_TIMEOUT_MS	15000	仅适用于 OpenCode 执行器，且仅在 OPENCODE_RESPONSES_STALL_ROTATION 功能标志开启时（默认关闭）：限制流式 Responses 回复在响应头之后等待首个正文字节的时间（#13484）。Responses 流以 response.created 开始，因此超过此时间窗口仍无数据即视为停滞：该账户会进入冷却状态，并将请求轮换到下一个账户一次；若再次停滞则快速失败。即使该标志已开启，设置为 0 也会禁用此保护机制。
OPENCODE_PARK_AND_RESUME	false	仅适用于 OpenCode 执行器：在反复出现临时性 429（或存在新的池压力标记）后，通过心跳机制暂存请求，然后重放一个有上限的阶段，最多依次尝试 3 个账户，而不是向整个账户池并发分发（#13924）。默认关闭：每次出现 429 时，仍会完全按照之前的行为轮换到下一个账户。
OPENCODE_POOL_STRAIN_MARKER_PATH	（未设置）	仅适用于 OpenCode 执行器：覆盖暂存前读取的池压力标记路径（{since, reason, ttl_s}，默认为 /tmp/opencode-pool-strain.json，#13924）。若标记仍然有效，则直接暂存而不重新计数；若标记不存在或已过期，则回退到突发计数器。
API_BRIDGE_PROXY_TIMEOUT_MS	30000	/v1 桥接请求的代理跃点超时时间。
FIRECRAWL_BASE_URL	https://api.firecrawl.dev	将 Firecrawl Web 获取执行器指向自托管实例（非云端环境下 API 密钥可选）。
FIRECRAWL_TIMEOUT_MS	30000	Firecrawl Web 获取执行器的单次请求超时时间。
API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS	300000	桥接器的整体服务器请求超时时间。
API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS	60000	通过桥接器发送响应头的时间。
API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS	5000	桥接器 Keep-alive 空闲超时时间。
API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS	0	原始套接字超时时间（0 = 禁用）。
SHUTDOWN_TIMEOUT_MS	30000	收到 SIGTERM/SIGINT 后强制退出前的宽限期。
OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS	120000	当 FETCH_TIMEOUT_MS 未设置时，由 src/shared/utils/fetchTimeout.ts 使用的回退值。
OMNIROUTE_PROVIDER_PROBE_TIMEOUT_MS	8000	src/shared/network/safeOutboundFetch.ts 中 validationRead 和 modelsProbe 预设的超时时间（毫秒）。对于响应缓慢的端点（Cerebras、Cloudflare AI、Groq），可调高此值，以防止仪表板中的状态在 active/error 之间反复切换。对于无效值（<1000）或非数字值，回退到 8000ms。
OMNIROUTE_RELAY_FETCH_TIMEOUT_MS	25000	open-sse/utils/proxyFetch.ts 中继专用的 fetch 超时（#9158）。挂起的中继必须在客户端/代理超时（约 30 秒）之前失败，以便调用方看到中继特定的失败，而不是通用的上游超时。上限为 29000，确保它始终先触发。
OMNIROUTE_RETRY_BACKOFF_MS	10	open-sse/utils/proxyFetch.ts 中 direct/relay/proxy 单次重试路径共享的重试退避时间（#9158）。0 = 立即重试。
OMNIROUTE_CLAUDE_TLS_TIMEOUT_MS	60000	原生 wreq-js 请求超时（claudeTlsClient.ts）。
OMNIROUTE_CLAUDE_TLS_GRACE_MS	10000	在原生超时基础上增加的绝对 JS 硬截止时间宽限期。
OMNIROUTE_PPLX_TLS_TIMEOUT_MS	30000	原生 wreq-js 请求超时（perplexityTlsClient.ts）。
OMNIROUTE_PPLX_TLS_GRACE_MS	10000	在原生超时基础上增加的绝对 JS 硬截止时间宽限期。
OMNIROUTE_PPLX_SEARCH_HINT	0（关闭）	将“You have built-in web search. Answer questions directly using search results.”追加到调用方的系统消息中（perplexity-web/protocol.ts）。默认关闭——Perplexity 无论如何都会搜索，而且该句子会以元评论的形式泄漏到面向编码客户端的回复中。设置为 1/true/yes/on 可恢复。
OMNIROUTE_GROK_TLS_TIMEOUT_MS	60000	原生 wreq-js 请求超时（grokTlsClient.ts）。
OMNIROUTE_GROK_TLS_GRACE_MS	10000	在原生超时基础上增加的绝对 JS 硬截止时间宽限期。
OMNIROUTE_NOTION_TLS_TIMEOUT_MS	30000	原生 wreq-js 请求超时（notionTlsClient.ts）；对于耗时较长的生成，notion-web 会在每次请求时将其提高至 180000。
OMNIROUTE_NOTION_TLS_GRACE_MS	10000	在原生超时基础上增加的绝对 JS 硬截止时间宽限期。
OMNIROUTE_BROWSER_POOL	on	用于浏览器支持的 Web Cookie 聊天的共享 Playwright 浏览器池（browserPool.ts）；设置为 off 可禁用。
OBSCURA_BIN	auto-detect	浏览器池和 Cloudflare Playground 执行器所使用的主引擎 obscura 二进制文件的路径（open-sse/services/obscura.ts）；未设置时从系统 PATH 中自动检测。
OBSCURA_CDP_ENDPOINT	（未设置）	指向已在运行的 Obscura（http://host:port），而不是启动一个新实例；该模块不管理此进程（open-sse/services/obscura.ts）。
OBSCURA_PORT	随机空闲端口	为启动的 obscura serve 指定显式端口；未设置时会自动选择一个空闲端口（open-sse/services/obscura.ts）。
WEB_COOKIE_USE_BROWSER	0	选择让 Web Cookie 聊天请求使用浏览器支持的路径（browserBackedChat.ts）；设置为 1 可启用。
KIMI_WEB_BASE_URL	https://www.kimi.ai	Kimi Web（国际版 kimi.ai Connect-RPC）执行器的基础 URL（kimi-web.ts）；仅针对镜像/代理端点进行覆盖。
KIMI_WEB_CHAT_URL	<KIMI_WEB_BASE_URL>/apiv2/kimi.gateway.chat.v1.ChatService/Chat	Kimi Web 执行器的完整聊天端点（kimi-web.ts）。
OMNIROUTE_LOGIN_BROWSER_PATH	（自动检测）	用于 Adobe Firefly 交互式浏览器登录的系统 Chrome/Edge 可执行文件路径（adobeFireflyBrowserLogin.ts）；覆盖各操作系统的自动检测。
OMNIROUTE_STANDALONE_DIR	.build/ 独立输出	构建后同目录放置步骤所使用的独立输出目录的构建时覆盖值（scripts/build/colocate-standalone.mjs）；属于构建工具配置，而非运行时配置。

组合目标尝试会继承解析后的上游请求超时（FETCH_TIMEOUT_MS，或在 REQUEST_TIMEOUT_MS 提供 fetch 默认值时使用后者）。仅在希望加快组合回退时，才应在组合、组合默认值或提供者覆盖配置中设置 targetTimeoutMs；高于当前上游超时的值将被限制为上游超时。

comboTimeoutMs 是一个独立的、涵盖所有故障转移目标的整个组合挂钟时间预算。将其留空或设为 0 可保持不限次数的迭代（comboPredicates.ts 中硬编码的 10 分钟防挂起停止机制仍然适用）。正值会替代该组合的安全机制。应确保 comboTimeoutMs 长于 targetTimeoutMs，以便第一个目标响应缓慢后仍有时间进行故障转移。

熔断器阈值

提供者级别的熔断器调优。默认值反映了自 v3.6 起用于 500+ 个连接的缩放值。

变量	默认值	源文件	说明
OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD	8	open-sse/config/constants.ts	OAuth 提供者触发熔断器前的连续失败次数阈值。
OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS	60000	open-sse/config/constants.ts	OAuth 提供者熔断器的重置窗口（毫秒）。
OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD	12	open-sse/config/constants.ts	API 密钥提供者的连续失败次数阈值。
OMNIROUTE_CIRCUIT_BREAKER_API_KEY_RESET_MS	30000	open-sse/config/constants.ts	API 密钥提供者熔断器的重置窗口（毫秒）。
OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD	2	open-sse/config/constants.ts	本地提供者（Ollama、LM Studio 等）的连续失败次数阈值。
OMNIROUTE_CIRCUIT_BREAKER_LOCAL_RESET_MS	15000	open-sse/config/constants.ts	本地提供者熔断器的重置窗口（毫秒）。
OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_THRESHOLD	10	open-sse/config/constants.ts	提供者级熔断器：整个 OAuth 提供者进入冷却状态前，窗口内的失败次数阈值。
OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_WINDOW_MS	900000	open-sse/config/constants.ts	提供者级熔断器：OAuth 提供者的滚动失败计数窗口（毫秒）。
OMNIROUTE_PROVIDER_BREAKER_OAUTH_COOLDOWN_MS	300000	open-sse/config/constants.ts	提供者级熔断器：OAuth 提供者达到阈值后的冷却时间（毫秒）。
OMNIROUTE_PROVIDER_BREAKER_OAUTH_DEGRADATION_THRESHOLD	5	open-sse/config/constants.ts	OAuth 提供者在达到此失败次数时进入 DEGRADED 状态。
OMNIROUTE_PROVIDER_BREAKER_OAUTH_MAX_BACKOFF_MULTIPLIER	8	open-sse/config/constants.ts	OAuth 提供者的最大 resetTimeout 递增倍数。
OMNIROUTE_PROVIDER_BREAKER_OAUTH_BACKOFF_ESCALATION_COUNT	2	open-sse/config/constants.ts	OAuth 提供者在经历此数量的开启周期后提升退避级别。
OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_THRESHOLD	15	open-sse/config/constants.ts	提供者级熔断器：整个 API 密钥提供者进入冷却状态前，窗口内的失败次数阈值。
OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_WINDOW_MS	1800000	open-sse/config/constants.ts	提供者级熔断器：API 密钥提供者的滚动失败计数窗口（毫秒）。
OMNIROUTE_PROVIDER_BREAKER_API_KEY_COOLDOWN_MS	600000	open-sse/config/constants.ts	提供者级熔断器：API 密钥提供者达到阈值后的冷却时间（毫秒）。
OMNIROUTE_PROVIDER_BREAKER_API_KEY_DEGRADATION_THRESHOLD	7	open-sse/config/constants.ts	API 密钥提供者在达到此失败次数时进入 DEGRADED 状态。
OMNIROUTE_PROVIDER_BREAKER_API_KEY_MAX_BACKOFF_MULTIPLIER	4	open-sse/config/constants.ts	API 密钥提供者的最大 resetTimeout 递增倍数。
OMNIROUTE_PROVIDER_BREAKER_API_KEY_BACKOFF_ESCALATION_COUNT	3	open-sse/config/constants.ts	API 密钥提供者在经历此数量的开启周期后提升退避级别。
OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_THRESHOLD	2	open-sse/config/constants.ts	提供者级熔断器：整个本地提供者进入冷却状态前的失败次数阈值。
OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_WINDOW_MS	300000	open-sse/config/constants.ts	提供者级熔断器：本地提供者的滚动失败计数窗口（毫秒）。
OMNIROUTE_PROVIDER_BREAKER_LOCAL_COOLDOWN_MS	60000	open-sse/config/constants.ts	提供者级熔断器：本地提供者达到阈值后的冷却时间（毫秒）。
PIN_DROP_BACKOFF_LEVEL	2	open-sse/services/combo.ts	达到此退避深度时，上下文缓存固定项的提供者将被视为持续不健康，并丢弃该固定项以进行故障转移。
PIN_DROP_GRACE_MS	20000	open-sse/services/combo.ts	防抖窗口（毫秒），用于在丢弃上下文缓存固定项之前容忍短暂的临时冷却。

场景

场景	配置
长时间运行的代码生成	REQUEST_TIMEOUT_MS=900000（15 分钟）
限制流的总生命周期	STREAM_ACTIVE_TIMEOUT_MS=1260000（21 分钟）
生产 API 快速失败	API_BRIDGE_PROXY_TIMEOUT_MS=10000
扩展思考模型	STREAM_IDLE_TIMEOUT_MS=300000（数据块之间 5 分钟）

---

16. 日志

日志系统同时写入 stdout 和轮转日志文件。所有配置均由 src/lib/logEnv.ts 读取。

变量	默认值	说明
APP_LOG_LEVEL	info	最低日志级别：debug、info、warn、error。
APP_LOG_FORMAT	text	输出格式：text（人类可读）或 json（结构化）。
APP_LOG_TO_FILE	true	除 stdout 外，还将日志写入文件。
APP_LOG_FILE_PATH	logs/application/app.log	日志文件路径（相对于项目根目录或 DATA_DIR）。
APP_LOG_MAX_FILE_SIZE	50M	轮转前的最大文件大小。接受：50M、1G、512K 或纯字节数。
APP_LOG_RETENTION_DAYS	7	轮转后的应用程序日志文件保留天数。
APP_LOG_MAX_FILES	20	轮转日志文件的最大备份数量。
CALL_LOG_RETENTION_DAYS	7	数据库中的请求/调用日志条目的保留天数。
CALL_LOG_MAX_ENTRIES	10000	内存缓冲区中的最大调用日志条目数。
CALL_LOGS_TABLE_MAX_ROWS	100000	清理前 call_logs SQLite 表中的最大行数。
ENABLE_REQUEST_LOGS	（未设置）	强制开启或关闭详细请求日志，覆盖仪表板设置。
MAX_PENDING_REQUEST_AGE_MS	3600000（1 小时）	在从内存中清理之前，孤立的活动请求日志条目所允许的最长存在时间。
CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS	false	当 call_log_pipeline_enabled=true 时，在流水线制品中存储流数据块。选择启用（true）——默认关闭以节省磁盘空间。
CALL_LOG_PIPELINE_MAX_SIZE_KB	512	当 call_log_pipeline_enabled=true 时，流水线调用日志制品的最大大小（KB）。
PROXY_LOGS_TABLE_MAX_ROWS	100000	清理前 proxy_logs SQLite 表中的最大行数。
PROXY_LOG_INCLUDE_IPS	false	在 [ProxyEgress] 控制台日志中包含客户端/出口 IP 和账户前缀。仪表板/数据库中的代理日志记录会保留完整详细信息。
APP_LOG_ROTATION_CHECK_INTERVAL_MS	60000（1 分钟）	src/lib/logRotation.ts 重新检查活动日志文件大小的频率。
CHAT_LOG_TEXT_LIMIT	65536	聊天日志制品中保留的最大字符串长度（默认 64 KB）。
CHAT_LOG_ARRAY_TAIL_ITEMS	128	截断聊天日志载荷时，从数组尾部保留的元素数量。
CHAT_LOG_MAX_DEPTH	6	聊天日志载荷被截断前允许的最大嵌套深度。
CHAT_LOG_MAX_OBJECT_KEYS	80	聊天日志载荷中保留的最大对象键数量（0 = 无限制）。
CHAT_LOG_MAX_BODY_KB	1024	整个请求/响应正文在被替换为简要摘要而非完整副本前允许的大小（KB）。如果长时间运行的智能体对话在仪表板中显示占位符而非实际消息，请提高此值。
CHAT_DEBUG_FILE	false	为 true 时，serializeArtifactForStorage 会跳过基于大小的截断。仅用于调试。

---

17. 内存优化

变量	默认值	说明
OMNIROUTE_MEMORY_MB	自动（裸机）；Docker 镜像中为 1024	推荐的 Docker/独立运行模式 V8 堆限制（MB）。未设置时，会动态校准（约为系统 RAM 的 35%，并限制在 [512, 4096] 范围内）；仅当无法读取总内存时，才使用 512 作为下限。在 run-standalone.mjs（Docker CMD）中，显式值会作为 --max-old-space-size 追加，并且会优先于冲突的 NODE_OPTIONS 堆标志（V8 采用最后一个标志）。omniroute serve 仍优先使用现有的 NODE_OPTIONS 堆设置（#5238）。不要将两者设置为不同的数值——进程会记录一条警告，指出这两个值以及最终采用的值。官方 Docker 镜像始终将其设置为 1024，因此不会在其中运行校准。 编码代理的 /v1/responses 需要 8192–12288，并需为 cgroup 预留余量——请参阅 Docker 指南 — 运行时 RAM。
PROMPT_CACHE_MAX_SIZE	50	缓存的系统提示词条目数上限。
PROMPT_CACHE_MAX_BYTES	2097152（2 MB）	提示词缓存总大小上限。
PROMPT_CACHE_TTL_MS	300000（5 分钟）	提示词缓存条目的 TTL。
SEMANTIC_CACHE_MAX_SIZE	100	缓存的 temperature=0 响应数上限。
SEMANTIC_CACHE_MAX_BYTES	4194304（4 MB）	语义缓存总大小上限。
SEMANTIC_CACHE_TTL_MS	1800000（30 分钟）	语义缓存条目的 TTL。
OMNIROUTE_CORPUS_CACHE_SIZE	5	可同时保留活动内存索引的本地语料库根目录数（src/lib/localCorpus/configured.ts）。采用 LRU：达到上限时，会驱逐最近最少使用的根目录索引，并在下次查询时重建。最小值限制为 1；非数值将回退到默认值。
STREAM_HISTORY_MAX	50	Dashboard 实时视图缓冲区中的近期流事件数上限。
CONTEXT_LENGTH_DEFAULT	128000	对于没有显式配置的模型，全局回退最大上下文长度。
USAGE_TOKEN_BUFFER	100	跟踪使用配额时预留的额外 token 余量。

压缩

变量	默认值	说明
OMNIROUTE_RTK_TRUST_PROJECT_FILTERS	未设置	无需 .rtk/trust.json 哈希即可信任项目的 .rtk/filters.json。仅限在受控的本地开发环境中使用。

内存引擎（计划 21）

内存、技能和 token 刷新的事件循环开销（#10349）

OmniRoute 是一个单 Node 进程。内存提取/检索、技能注入和提供者 token 刷新与 GET /healthz 及 Dashboard 运行在同一个事件循环上。它们并非工作线程。

工作项	代码	默认值	操作员控制方式
内存提取/检索	src/lib/memory/	控制面板中的 memoryEnabled（默认开启）	关闭 设置 → 内存。除了在设置中禁用该功能外，没有单独的环境变量总开关。
技能注入	src/lib/skills/injection.ts	控制面板中的 skillsEnabled（默认开启）	关闭 设置 → 内存/技能（skillsEnabled）。下方的沙箱参数只能在注入已开启后限制执行。
令牌刷新	src/sse/services/tokenRefresh.ts	对已连接的 OAuth/Web 提供者开启	断开提供者连接或让令牌保持有效；目前没有 TOKEN_REFRESH=0 环境变量。

如果 /healthz 在空闲机器上响应缓慢，请先禁用内存和技能，然后检查目录/压缩负载（#10303、#9685）。这些功能会在 await 点让出执行权，但仍会争用唯一的线程。

持久化内存子系统（src/lib/memory/）的嵌入层、向量存储和重排序参数。

变量	默认值	说明
MEMORY_EMBEDDING_CACHE_TTL_MS	300000（5 分钟）	内存中嵌入缓存的 TTL（按来源/模型/维度签名区分）。
MEMORY_EMBEDDING_CACHE_MAX	1000	嵌入缓存中保留的最大 LRU 条目数。
MEMORY_TRANSFORMERS_MODEL	Xenova/all-MiniLM-L6-v2	可选启用的 @huggingface/transformers 本地 MiniLM 管线所使用的 HF 仓库 ID（约 23 MB int8、约 400 MB RAM）。
MEMORY_STATIC_MODEL	minishlab/potion-base-8M	静态 potion/Model2Vec 查找表嵌入器所使用的 HF 仓库 ID。按需延迟下载到缓存目录中。
MEMORY_STATIC_CACHE_DIR	<DATA_DIR>/embeddings	用于缓存静态 potion 模型文件的目录。未设置时，默认位于 DATA_DIR 下。
HF_HUB_ENDPOINT	https://huggingface.co	覆盖 staticPotion.ts 使用的 Hugging Face Hub 基础 URL（例如，用于气隙环境的镜像端点）。
MEMORY_VEC_TOP_K	20	src/lib/memory/vectorStore.ts 中 sqlite-vec 暴力向量搜索使用的默认 top-K 值。
MEMORY_RRF_K	60	混合 FTS5 + 向量检索使用的倒数排名融合常量 k（sqlite-vec 方案）。
VECTOR_STORE_DISABLE_VEC	false	getVectorStore()（src/lib/memory/vectorStore.ts）中的测试/诊断接缝：设为 true 时，强制向量存储为 null（模拟没有 sqlite-vec 的云端/WASM 环境），使内存检索降级为 FTS5 关键词搜索。生产环境中请勿设置。
NOTION_API_KEY	（未设置）	Notion 后端的 API 密钥（由 genericBackend.ts 的已知后端预设使用）。
NOTION_API_URL	https://api.notion.com/v1	Notion API 的基础 URL（可针对自托管的 Notion 替代方案进行覆盖）。
OBSIDIAN_API_KEY	（未设置）	Obsidian Vault 后端的 API 密钥（由 genericBackend.ts 的已知后端预设使用）。
OBSIDIAN_API_URL	http://localhost:27123	Obsidian Vault API 的基础 URL（可针对远程 Vault 进行覆盖）。
MEMORY_TYPED_DECAY_ENABLED	false	TV6 类型化内存衰减总开关。选择启用（默认关闭）——清理操作会删除已衰减的内存。关闭时，access_count/last_accessed_at 仅用于遥测，绝不会删除任何内容。
MEMORY_TYPED_DECAY_EPISODIC_DAYS	30	未使用的 episodic 内存发生衰减前的 TTL（天）。0 也会使 episodic 免于衰减。持久类型（factual/procedural/semantic）始终免于衰减。衰减计时会基于 last_accessed_at 重新起算。
MEMORY_TYPED_DECAY_ACCESS_IMMUNITY	3	内存被注入次数达到 >= 此值后，无论其类型如何，都将免于衰减。0 会禁用访问免疫。
MEMORY_TYPED_DECAY_SWEEP_INTERVAL	0（已禁用）	src/lib/memory/typedDecay.ts 中可选定期衰减清理的间隔（秒）。0/未设置 = 不执行定期清理。需要双重选择启用：还必须设置 MEMORY_TYPED_DECAY_ENABLED=true。
OMNIROUTE_STRICT_SYSTEM_PROVIDERS	（未设置）	以逗号分隔的提供者 ID（不区分大小写），这些提供者仅允许在索引 0 处接收 system 消息（src/lib/memory/injection.ts）。对于这些提供者，在数组中部拼接内存这一缓存安全做法在多轮对话中并不安全，因此内存会被合并/前置为首条 system 消息。默认仅包括 xiaomi-mimo/mimo；可为自托管的 OpenAI 兼容端点（例如 Qwen3.5+/3.6）扩展此列表，因为其聊天模板会强制执行相同的单一前置 system 消息约束。

低内存 Docker 示例

128 仅适用于控制面板。编程智能体在此堆大小下执行长时间的 /v1/responses 时会出现 FATAL ERROR。请勿将此示例用作 Claude/Codex/Grok 网关。

OMNIROUTE_MEMORY_MB=128
PROMPT_CACHE_MAX_SIZE=20
PROMPT_CACHE_MAX_BYTES=524288        # 512 KB
SEMANTIC_CACHE_MAX_SIZE=25
SEMANTIC_CACHE_MAX_BYTES=1048576     # 1 MB
STREAM_HISTORY_MAX=10

---

18. 定价同步

自动从外部来源同步模型定价数据。

变量	默认值	源文件	说明
PRICING_SYNC_ENABLED	false	src/lib/pricingSync.ts	选择启用定期定价同步。
PRICING_SYNC_INTERVAL	86400 (24h)	src/lib/pricingSync.ts	同步间隔（秒）。
PRICING_SYNC_SOURCES	litellm	src/lib/pricingSync.ts	以逗号分隔的数据源。

---

Arena ELO 同步

变量	默认值	源文件	说明
ARENA_ELO_SYNC_ENABLED	true	src/shared/constants/featureFlagDefinitions.ts	定期同步 Arena AI 排行榜 ELO，可通过控制面板中的功能标志进行配置，或设为 false 以选择退出。
MODELS_CATALOG_PREFIX_MODE	dual	src/shared/constants/featureFlagDefinitions.ts, src/app/api/v1/models/catalog.ts	GET /v1/models 中模型 ID 使用的前缀形式。dual 会为每个模型同时公布短别名前缀和规范提供者前缀（用于向后兼容——目录大小大致翻倍）；alias 每个模型仅输出一个 ID；canonical 仅输出完整的提供者 ID 前缀（别名已经是规范 ID 的提供者仍保留其单一条目）。客户端可通过 ?prefix=alias 为每个请求覆盖此设置。请参阅 API_REFERENCE。
ARENA_ELO_SYNC_INTERVAL	86400 (24h)	src/lib/arenaEloSync.ts	同步间隔（秒）。

---

PromptQL Playground 提供者（非官方/实验性）

用于 prompt.ql.app 的逆向工程 GraphQL 会话桥接器（src/shared/constants/providers/web-cookie.ts）。所有配置均为可选——默认指向公共 Playground 端点；仅在使用自托管或替代的 PromptQL 部署时才需覆盖。

变量	默认值	源文件	说明
PROMPTQL_GRAPHQL_ENDPOINT	https://data.prompt.ql.app/promptql/playground-v2-hge/v1/graphql	open-sse/executors/promptql.ts	用于聊天/会话操作的 GraphQL 端点。
PROMPTQL_CREDITS_ENDPOINT	https://data.pro.ql.app/v1/graphql	open-sse/executors/promptql.ts, open-sse/services/usage/promptql.ts	用于查询点数余额/使用量的 GraphQL 端点。
PROMPTQL_TOKEN_REFRESH_URL	https://auth.pro.ql.app/ddn/project/token	open-sse/executors/promptql.ts	用于尽力刷新令牌的端点。
PROMPTQL_POLL_TIMEOUT_MS	180000	open-sse/executors/promptql.ts	在超时前轮询 thread_events 的最长时间（毫秒）。

---

HyperAgent Web 提供者（非官方/实验性）

为 hyperagent.com 逆向工程实现的会话桥接器（src/shared/constants/providers/web-cookie.ts）。可选配置——默认指向公共计费/用量端点；仅在使用自托管或替代的 HyperAgent 部署时覆盖。

变量	默认值	源文件	说明
HYPERAGENT_USAGE_URL	https://hyperagent.com/api/settings/billing/usage	open-sse/services/usage/hyperagent.ts	用于获取计费/用量额度块的端点。

---

Kilo Code 用量配额

查询 Kilo Code 提供者的个人美元余额和 Kilo Pass 用量。可选配置——默认指向公共 Kilo API；仅在使用中继或测试夹具时覆盖。身份验证使用现有连接的 OAuth 访问令牌。

变量	默认值	源文件	说明
KILO_API_URL	https://api.kilo.ai	open-sse/services/usage/kilocode.ts	用于获取个人 Kilo Code 余额和 Kilo Pass 用量的基础 URL。

---

Adobe Firefly Web 提供者（非官方/实验性）

Adobe Firefly Web 提供者的浏览器驱动会话刷新 （open-sse/services/adobeFireflyBrowserLogin.ts、open-sse/services/adobeFireflySession.ts、 open-sse/services/adobeFireflyClient.ts）。可选配置——所有默认值均针对普通 桌面安装进行了优化。

已在 #9255 中移除。 旧的 CDP 附加式 Chrome 运行时（adobeFireflyChromeRuntime.ts）已 替换为 Playwright 浏览器登录服务，其配置项已不复存在。 ADOBE_FIREFLY_CHROME_ CDP_PORT / VISIBLE / HEADED / PING / FORCE_RESTART 变量，以及 ADOBE_FIREFLY_LOGIN_WAIT_MS 和 ADOBE_FIREFLY_FORTER_WAIT_MS，在 代码库中均未被读取——设置它们不会产生任何效果。

变量	默认值	源文件	说明
ADOBE_FIREFLY_CHROME_HEADLESS	0	open-sse/services/adobeFireflyBrowserLogin.ts	设置为 1 可启用真正的无头 Chrome（已知无法用于生成；仅限调试）。
ADOBE_FIREFLY_BROWSER_REFRESH	1	open-sse/services/adobeFireflySession.ts	主动浏览器预热的启用/禁用开关。0 禁用主动预热（批处理中途的 408 恢复仍然适用）。
ADOBE_FIREFLY_SESSION_DISK	1	open-sse/services/adobeFireflySession.ts	设置为 0 可禁止将 Adobe Firefly 会话持久化到磁盘。
ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS	（未设置）	open-sse/services/adobeFireflySession.ts	连续提交之间强制执行的最小间隔（毫秒），覆盖内置默认值。
ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS	（未设置）	open-sse/services/adobeFireflySession.ts	成功完成一个批次后增加的额外间隔（毫秒），覆盖内置默认值。
ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS	（未设置）	open-sse/services/adobeFireflyClient.ts	提交生成请求前的基础延迟（毫秒），覆盖内置默认值。

---

19. 模型同步（开发）

变量	默认值	源文件	描述
MODELS_DEV_SYNC_ENABLED	（未设置）	src/lib/modelsDevSync.ts	models.dev 定价同步的强制覆盖设置。未设置 = 遵循“设置 > AI”中的配置（modelsDevSyncEnabled）。0/false/off/no 优先于数据库设置，并跳过定期同步以及 getModelsDevPricing() SQL/JSON 扫描（用于仪表板因同一事件循环阻塞时的恢复）。1/true/on/yes 强制启用同步。保存/清除定价时仍会调用 backupDbFile("pre-write")，但在 60 分钟限流期间或设置了 DISABLE_SQLITE_AUTO_BACKUP 时，该调用不会执行任何操作。
MODELS_DEV_SYNC_INTERVAL	86400（24 小时）	src/lib/modelsDevSync.ts	开发期间模型目录的同步间隔，单位为秒。
CONTEXT_WINDOW_RECONCILE_INTERVAL	86400（24 小时）	src/lib/contextWindowResolver.ts	自校正上下文窗口协调器（5004）的运行间隔（秒）：当通过 /models 发现的提供者声明窗口与目录不一致时，将其固定为 auto:discovery 覆盖值。设置为 0 可禁用。复用已同步的数据（不会发起新的获取请求）；绝不会覆盖 manual 覆盖值。

---

20. 提供者特定设置

变量	默认值	源文件	描述
OPENROUTER_CATALOG_TTL_MS	86400000（24 小时）	src/lib/catalog/openrouterCatalog.ts	OpenRouter 模型目录缓存的 TTL。
MODEL_CATALOG_INCLUDE_NAMES	true	src/shared/constants/featureFlagDefinitions.ts	在 /v1/models 响应中包含便于显示的 name 字段。对于仅接受 ID 的客户端，请禁用此项。
CATALOG_BUILD_TIMEOUT_MS	8000（8 秒）	src/app/api/v1/models/catalogCache.ts	合并执行的 GET /v1/models 目录重建在冷路径上的等待上限（#12627）。超时后，如果存在上次成功的结果，则返回该结果并保持 200 状态码。
OMNIROUTE_SYNCED_CATALOG_STALE_AFTER_MS	2592000000（30 天）	src/lib/db/models/activeSyncedCatalog.ts	超过此时长后，连接同步的模型列表将不再被视为路由的权威依据，并以故障开放方式回退到注册表（#12849）。从未记录时间戳的行视为已过期。
NANOBANANA_POLL_TIMEOUT_MS	120000	open-sse/handlers/imageGeneration.ts	NanoBanana 图像生成任务的最长等待时间。
NANOBANANA_POLL_INTERVAL_MS	2500	open-sse/handlers/imageGeneration.ts	NanoBanana 任务的轮询频率。
ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS	8000	open-sse/services/adobeFireflyUpscale.ts	Adobe Firefly 放大提交重试采用指数退避时的基础延迟。
AWS_REGION	（未设置）	src/lib/providers/validation.ts, open-sse/handlers/audioSpeech.ts	用于构建 AWS Bedrock 端点（Kiro、音频）的区域。
AWS_DEFAULT_REGION	（未设置）	src/lib/providers/validation.ts, open-sse/handlers/audioSpeech.ts	未设置 AWS_REGION 时使用的回退区域。
CLOUDFLARE_ACCOUNT_ID	（未设置）	open-sse/executors/cloudflare-ai.ts	Cloudflare Workers AI 的账户 ID。
CLOUDFLARE_PLAYGROUND_CHROME_PATH	（未设置）	open-sse/executors/cloudflare-playground.ts	Cloudflare AI Playground 执行器所使用的完整桌面版 Chrome 二进制文件路径；当无头浏览器指纹检查阻止 Playwright 捆绑的 Chromium 时使用。
CLOUDFLARE_API_BASE	https://api.cloudflare.com/client/v4	src/app/api/settings/proxy/cloudflare-deploy/route.ts	覆盖代理池 Workers 中继部署器使用的 Cloudflare REST API 基础地址（#4640 / 9router#1360）。
NEXT_PUBLIC_CLOUDFLARE_RELAY_DEFAULT_PROJECT	omniroute-relay	src/app/(dashboard)/dashboard/settings/components/proxy/CloudflareRelayModal.tsx	代理池“部署中继”模态框中建议的默认 Worker 项目名称。
NEXT_PUBLIC_CLOUDFLARE_RELAY_ENABLED	true	src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx	设置为 false 可在“代理池”选项卡中隐藏 Cloudflare Workers 中继选项。
CLOUDFLARED_BIN	自动检测	src/lib/cloudflaredTunnel.ts	cloudflared 二进制文件的自定义路径。
CLOUDFLARED_PROTOCOL	http2	src/lib/cloudflaredTunnel.ts	隧道传输协议：http2（默认）、quic 或 auto。
CLOUDFLARED_CONFIG	（未设置）	src/lib/cloudflaredTunnel.ts	本地管理的 cloudflared config.yml 路径（包含 tunnel:、credentials-file:、ingress:）。设置后，OmniRoute 将运行 tunnel --config <path> run（命名隧道），而不是临时快速隧道。
CLOUDFLARED_HOSTNAME	（来自配置中的 ingress）	src/lib/cloudflaredTunnel.ts	覆盖命名隧道的公共主机名（例如 ai.example.com），该名称将报告为 publicUrl/apiUrl。未设置时，将从配置的第一个 ingress 主机名中读取。
DENO_DEPLOY_API_BASE	https://api.deno.com/v2	src/app/api/settings/proxy/deno-deploy/route.ts	覆盖代理池中继部署器使用的 Deno Deploy REST API 基础地址（#4643 / 9router#1437）。
NEXT_PUBLIC_DENO_RELAY_DEFAULT_PROJECT	omniroute-deno-relay	src/app/(dashboard)/dashboard/settings/components/proxy/DenoRelayModal.tsx	代理池“部署中继”模态框中建议的默认 Deno Deploy 应用名称。
NEXT_PUBLIC_DENO_RELAY_ENABLED	true	src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx	设置为 false 可在“代理池”选项卡中隐藏 Deno Deploy 中继选项。
SEARCH_CACHE_TTL_MS	300000（5 分钟）	open-sse/services/searchCache.ts	搜索 API（Perplexity、Brave 等）响应缓存的 TTL。
ENABLE_CC_COMPATIBLE_PROVIDER	false	src/shared/utils/featureFlags.ts	显示实验性的 CC 兼容提供者 UI，用于仅支持 Claude Code 的中继。
NINEROUTER_HOST	127.0.0.1	open-sse/executors/ninerouter.ts	覆盖嵌入式 9router 实例监听的主机。
NINEROUTER_PORT	20130	open-sse/executors/ninerouter.ts	覆盖嵌入式 9router 实例监听的端口。
EMBED_WS_PROXY_HOST	127.0.0.1	src/lib/services/embedWsProxy.ts	嵌入式服务 WebSocket 代理的绑定主机（默认仅限环回地址）。
EMBED_WS_PROXY_PORT	20131	src/lib/services/embedWsProxy.ts	嵌入式服务 WebSocket 代理服务器的端口。
CLIPROXYAPI_HOST	127.0.0.1	open-sse/executors/cliproxyapi.ts	CLIProxyAPI 桥接主机（旧版集成）。
CLIPROXYAPI_PORT	5544	open-sse/executors/cliproxyapi.ts	CLIProxyAPI 桥接端口。
CLIPROXYAPI_API_KEY	（空）	open-sse/handlers/chatCore/cliproxyapiCredentials.ts	当缺少 cliproxyapi_api_key 设置时使用的数据平面密钥回退值。
CLIPROXYAPI_MANAGEMENT_KEY	（空）	src/lib/services/cliproxyAccountHealth.ts	用于从外部管理的 CLIProxyAPI 实例读取账户健康状态的管理密钥。
CLIPROXYAPI_CONFIG_DIR	~/.cli-proxy-api	src/lib/versionManager/processManager.ts	CLIProxyAPI 配置目录。
CLIPROXY_BIND_HOST	127.0.0.1	docker-compose.yml	docker-compose 在其上发布 cliproxyapi sidecar 的主机接口（#12578）。其数据卷保存提供者 OAuth/API 凭据，且固定版本的镜像不支持通过环境变量覆盖数据平面 api-keys（仅支持挂载的 config.yaml），因此设置为 0.0.0.0 会将携带凭据的服务暴露给整个局域网。
MUX_SERVICE_PORT	8322	src/lib/services/bootstrap.ts	覆盖嵌入式 Mux（coder/mux）代理编排守护进程监听的端口（始终为 127.0.0.1）。
OPENWA_SERVICE_PORT	8323	src/lib/services/bootstrap.ts	覆盖嵌入式 open-wa（WhatsApp Web 自动化）守护进程监听的端口（始终为 127.0.0.1）。
DARIO_HOST	127.0.0.1	open-sse/executors/dario.ts	Dario 嵌入式服务的绑定/连接主机（默认仅限环回地址）。
DARIO_PORT	3456	open-sse/executors/dario.ts	Dario 嵌入式服务端口。
DARIO_HOST	127.0.0.1	open-sse/executors/dario.ts	Dario 嵌入式服务的绑定/连接主机（默认仅限环回地址）。
DARIO_PORT	3456	open-sse/executors/dario.ts	Dario 嵌入式服务端口。
LOCAL_HOSTNAMES	(空)	open-sse/config/providerRegistry.ts	以逗号分隔的其他视为“本地”的主机名（Docker 服务名称等）。

ENABLE_CC_COMPATIBLE_PROVIDER 仅适用于只接受 Claude Code 客户端的第三方中继。 OmniRoute 会重写请求，使这些中继能够接受它们。如果你只想使用 Claude Code CLI，或者不确定这些中继是什么，请保持禁用此选项，并改为添加常规的 Anthropic 兼容提供者。

---

21. 代理健康状态

变量	默认值	源文件	描述
PROXY_FAST_FAIL_TIMEOUT_MS	2000	src/lib/proxyHealth.ts	快速失败健康检查超时时间。
PROXY_LATENCY_WINDOW_HOURS	3	src/lib/db/proxies.ts	在延迟优化的代理池策略中，用于计算候选代理平均延迟的时间窗口（小时）。
PROXY_HEALTH_CACHE_TTL_MS	30000	src/lib/proxyHealth.ts	健康检查结果缓存的 TTL。
PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS	2000	src/lib/proxyHealth.ts	代理健康探测失败结果的缓存 TTL。该值应短于 PROXY_HEALTH_CACHE_TTL_MS，以便高并发情况下发生的临时代理超时能够快速重试，同时仍对真正失效的代理启用快速失败机制。
PROXY_HEALTH_ENABLED	true	src/lib/proxyHealth/scheduler.ts	设置为 false 可禁用定期探测已注册代理的后台代理健康状态调度器。
PROXY_HEALTH_INTERVAL_MS	600000	src/lib/proxyHealth/scheduler.ts	后台健康状态调度器的扫描间隔，以毫秒为单位（最小值为 60000）。
PROXY_HEALTH_RECOVERY_INTERVAL_MS	600000	src/lib/proxyHealth/scheduler.ts	后台恢复检查间隔（毫秒）：对先前不健康的代理进行重新探测的频率，使已恢复的代理无需重启即可重新加入轮换。低于 60000 的值将回退到默认值。
PROXY_HEALTH_TEST_URL	https://httpbin.org/ip	src/lib/proxyHealth/probeTarget.ts	调度器和 /api/settings/proxies/auto-test 端点使用的可达性探测目标。请将其指向内部/自托管 URL，以避免使用公共默认目标。
PROXY_HEALTH_TEST_CONCURRENCY	10	src/lib/proxyHealth/probeTarget.ts	每批同时启动的探测数，由调度器和 /api/settings/proxies/auto-test 端点共享。下限为 1，上限为 50。
PROXY_HEALTH_TEST_STAGGER_MS	100	src/lib/proxyHealth/probeTarget.ts	同一批次中两次探测发出之间的延迟（毫秒）。如果没有此延迟，整个批次会同时发出，而共享的出口 IP 可能会触发目标的速率限制。设为 0 可禁用间隔；上限为 5000。
PROXY_HEALTH_USE_PROVIDER_TARGET	true	src/lib/proxyHealth/providerProbeTarget.ts	设为 “false” 可停止探测代理所分配提供者的实际主机（GET /models，无 API 密钥），并始终改用 PROXY_HEALTH_TEST_URL。
PROXY_HEALTH_AUTO_DEACTIVATE	false	src/lib/proxyHealth/statusPolicy.ts	当为 false（默认值）时，自动可达性探测（调度器 + /api/settings/proxies/auto-test 的“全部测试”按钮）为只读，绝不会写入代理状态——只有操作员可将其设为活动/非活动，因此不稳定的探测不会导致已分配的代理无法使用（#6246）。设为 true 可恢复旧版的测试并设置状态行为。
FLUSH_EMPTY_RETRY_ENABLED	false	src/shared/utils/featureFlags.ts	可选启用的功能标志（参见 FEATURE_FLAGS.md；控制面板中的数据库覆盖值优先）。设为 true（或 1、yes）时，会通过正常凭据路径重试翻译后为空的流式轮次（最多重试 STREAM_RECOVERY.EMPTY_TURN_RETRY_MAX 次），而不是返回内容为空的 200 或内容为空的 502。
PROXY_POOL_EGRESS_OBSERVATION	false	src/shared/utils/featureFlags.ts	可选启用的功能标志（参见 FEATURE_FLAGS.md；控制面板中的数据库覆盖值优先）。设为 true（或 1、yes）时，会在控制面板的代理池下显示只读的出口观测信息（来自代理日志中过去 24 小时内的不同出口 IP、连接数，以及单个 IP 后方的最大连接数）。绝不用于路由。
PROXY_AUTO_REMOVE	false	src/lib/proxyHealth/scheduler.ts	设置为 true，允许调度器在代理连续多次失败后自动移除该代理。
PROXY_AUTO_REMOVE_AFTER	3	src/lib/proxyHealth/scheduler.ts	调度器自动移除代理前允许的连续失败次数（当 PROXY_AUTO_REMOVE=true 时）。
PROXY_AUTO_DISABLE	false	src/lib/proxyHealth/scheduler.ts	设置为 true，允许调度器在代理连续多次失败后将其软禁用（状态为 dead，但绝不删除），而不是将其移除。这是 PROXY_AUTO_REMOVE 的非破坏性替代方案：该代理会立即从代理池/轮换解析中排除（作用域代理池解析所使用的存活状态过滤器已会将其排除），并在重新通过探测后自动恢复启用。与 PROXY_AUTO_REMOVE_AFTER 共用同一阈值。如果两个标志均为 true，则以 PROXY_AUTO_REMOVE 为准。
OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK	false	src/shared/constants/featureFlagDefinitions.ts	当代理可达性预检查失败时，允许 OAuth 和提供者验证流程绕过固定代理并直接连接。实际优先级为：功能标志数据库覆盖值 > 环境变量 > 默认值。
RATE_LIMIT_MAX_WAIT_MS	30000（30 秒）	src/lib/resilience/settings.ts	默认的队列等待预算：请求在被拒绝且从未到达上游之前，等待提供者槽位并在队列中停留的最长时间。作业开始执行后，计时器即被清除——执行时间由 RATE_LIMIT_EXECUTION_MAX_WAIT_MS 单独限制。环境变量仅设置默认值：持久化的 resilienceSettings.requestQueue.maxWaitMs 优先于该默认值，而每个连接的 rateLimitOverrides.maxWaitMs 又具有更高优先级。
RATE_LIMIT_EXECUTION_MAX_WAIT_MS	600000（10 分钟）	open-sse/services/rateLimitManager.ts	已准入请求在其速率限制预留过期前可保持执行状态的最长时间上限——与队列等待预算解耦，以避免非增量网关上缓慢的提取启动发生超时（#12027）。
RATE_LIMIT_MAX_QUEUE_DEPTH	0（已禁用）	open-sse/services/rateLimitManager.ts	队列准入上限：当已有这么多请求排队时，返回 429 queue_full 并拒绝请求。0 = 无上限（默认值）。
RATE_LIMIT_AUTO_ENABLE	（未设置）	open-sse/services/rateLimitManager.ts	无论持久化的仪表板设置为何，均强制开启或关闭自动启用速率限制的安全机制。接受 true/1/on 以强制开启，接受 false/0/off 以强制关闭。
PROVIDER_COOLDOWN_ENABLED	（未设置 → 关闭）	open-sse/services/providerCooldownTracker.ts	选择性启用全局跨请求的提供者/连接冷却跟踪。默认关闭（与连接冷却 / 提供者断路器功能重叠）。接受 true/1/on 以启用。
PROVIDER_COOLDOWN_MIN_MS	5000	open-sse/services/providerCooldownTracker.ts	重试失败的提供者/连接前的最短冷却时间（毫秒）。冷却时间会随连续失败次数呈指数增长。仅在启用 PROVIDER_COOLDOWN_ENABLED 时使用。
PROVIDER_COOLDOWN_MAX_MS	300000（5 分钟）	open-sse/services/providerCooldownTracker.ts	重试失败的提供者/连接前的最大冷却时间上限（毫秒），达到此上限后无论如何都会重试。仅在启用 PROVIDER_COOLDOWN_ENABLED 时使用。
STREAM_RECOVERY_ENABLED	（未设置 → 关闭）	src/lib/resilience/settings.ts（初始值）→ open-sse/services/streamRecovery.ts（逻辑）	**功能：**透明恢复被上游截断的流（移植自 free-claude-code）。将初始 SSE 窗口最多保留至 STREAM_RECOVERY.HOLDBACK_MS（750 毫秒），以便在任何字节到达客户端之前发生的_提交前_截断能够被重新打开并以不可见方式重试。**何时启用：**上游不稳定或经常在流开始时以 0 字节截断；如果无法接受每个流的首个 token 等待时间最多增加 750 毫秒，请保持关闭。接受 true/1/on。用于设置持久化韧性配置的初始值；一旦通过仪表板设置，将优先采用仪表板中的设置。
STREAM_RECOVERY_MIDSTREAM_ENABLED	（未设置 → 关闭）	src/lib/resilience/settings.ts（初始值）→ open-sse/services/streamRecovery.ts（逻辑）	**功能：**流中途续传（阶段 4.4）——发生_提交后_截断（字节已到达客户端）时，使用部分文本作为助手预填充内容重新发起请求，并拼接缺失的后缀。仅适用于兼容 OpenAI 的纯文本流；有工具调用正在进行时绝不会触发。**何时启用：**长文本生成在回答中途被截断，并且你可以接受恢复后的尾部内容一次性成批到达，而非逐 token 到达。独立于 STREAM_RECOVERY_ENABLED（风险特征不同）。接受 true/1/on。
STREAM_THROUGHPUT_WATCHDOG_ENABLED	（未设置 → 关闭）	src/lib/resilience/settings.ts → open-sse/services/throughputWatchdog.ts	选择性启用活动流有效输出看门狗。检测持续发送数据块、但助手输出速率仍低于配置值的流；心跳、用量事件、空增量以及工具/推理阶段不会被误判为进展。与空闲超时和硬截止时间超时相互独立。
STREAM_THROUGHPUT_WATCHDOG_WARMUP_MS	30000	src/lib/resilience/settings/normalize.ts	开始评估吞吐量前的宽限期，限制在 0–600000 毫秒范围内。
STREAM_THROUGHPUT_WATCHDOG_WINDOW_MS	30000	src/lib/resilience/settings/normalize.ts	有效输出的滚动窗口，限制在 1000–600000 毫秒范围内；必须经过一个完整窗口后才会中止。
STREAM_THROUGHPUT_WATCHDOG_MIN_BYTES_PER_SECOND	4	src/lib/resilience/settings/normalize.ts	助手 UTF-8 输出的最低字节速率（保守的 token 代理指标），限制在 1–1000000 范围内。
STREAM_THROUGHPUT_WATCHDOG_MIN_USEFUL_BYTES	1	src/lib/resilience/settings/normalize.ts	被视为可测量的非零有效输出样本的最小值，限制在 1–1000000 字节范围内。
HEALTHCHECK_STAGGER_MS	3000	src/lib/tokenHealthCheck.ts	启动时各提供者 token 健康检查之间的错开间隔（毫秒）。
HEALTHCHECK_JITTER_MIN_MS	500	src/lib/tokenHealthCheck.ts	在提供者令牌健康检查之间，叠加到 HEALTHCHECK_STAGGER_MS 之上的最小随机抖动（毫秒），用于防止突发请求（Issue #1220）。
HEALTHCHECK_JITTER_MAX_MS	5000	src/lib/tokenHealthCheck.ts	在提供者令牌健康检查之间，叠加到 HEALTHCHECK_STAGGER_MS 之上的最大随机抖动（毫秒），用于防止突发请求（Issue #1220）。
HEALTHCHECK_BATCH_SIZE	20	src/lib/tokenHealthCheck.ts	启动时令牌健康检查扫描的并发检查批次大小；值越大，并行检查的连接越多，值越小，则可降低突发负载（Issue #7875，#7719 的回归问题）。
REQUEST_RETRY	2	src/sse/services/cooldownAwareRetry.ts	收到模型范围的冷却响应后，在向客户端返回错误之前自动重试的次数。
MAX_RETRY_INTERVAL_SEC	30	src/sse/services/cooldownAwareRetry.ts	冷却重试之间的最大退避间隔（秒）。无论上游 Retry-After 的值是多少，都以此值为上限。
HEADROOM_URL	http://localhost:8787	src/lib/headroom/detect.ts	Headroom 令牌节省代理 URL。默认情况下，仪表板生命周期（api/headroom/*）会在环回地址上启动本地 headroom-ai CLI；仅在需要指向外部 Docker 边车代理时覆盖此值。

流恢复调优常量

恢复延迟提交行为由 open-sse/config/constants.ts（STREAM_RECOVERY）中的硬编码常量进行调优，以下列出这些常量供参考 — 更改它们需要编辑代码，而不能通过环境变量完成：

• STREAM_RECOVERY.HOLDBACK_MS = 750 — 保持初始 SSE 窗口暂不提交的时长， 以便在任何字节提交给客户端之前重试发生的早期截断。
• STREAM_RECOVERY.BUFFER_MAX_BYTES = 65536 — 暂存窗口的硬性上限；一旦累积到 此字节数，无论计时器状态如何，都会立即提交（刷新并直通传输）。
• STREAM_RECOVERY.EARLY_RETRY_MAX = 4 — 在延迟提交窗口仍未提交时，透明地重新打开上游 流的最大次数。

每个提供者的滑动窗口速率限制（无环境变量）： 从 FCC 移植的 每个提供者滑动窗口速率限制_回退机制_已存在于代码中 （open-sse/services/providerDefaultRateLimit.ts，通过 open-sse/services/rateLimitManager.ts 接入），但发布时使用空的默认映射， 且目前没有供运维人员使用的环境变量 — 只能通过测试钩子 / 编辑代码来启用。因此，它有意未列在上表中。确实提供配置项的每个 (token, IP) 中继限制器是 RELAY_IP_PER_MINUTE（§3 网络与端口）。

---

22. 调试

[!CAUTION] 这些变量会产生详细输出，并可能泄露敏感数据。切勿在生产环境中启用。

变量	默认值	源文件	说明
CURSOR_DEBUG	（未设置）	open-sse/executors/cursor.ts	设置为 1 可启用详细的 Cursor 执行器日志（已解码的 SSE 数据块等）。
CURSOR_STREAM_DEBUG	（未设置）	open-sse/executors/cursor.ts	CURSOR_DEBUG 的向后兼容别名。
CURSOR_DUMP_FILE	（未设置）	open-sse/executors/cursor.ts	可选文件路径；当 CURSOR_DEBUG=1 时，用于接收原始的已解码 Cursor 数据块。
CURSOR_STREAM_TIMEOUT_MS	300000	open-sse/executors/cursor.ts	Cursor 执行器的流空闲超时时间（毫秒）。
CURSOR_KV_GRACE_MS	2000	open-sse/executors/cursor.ts	composer kv_after_text 软终止符出现后，若仍有字节处于缓冲状态，则采用此宽限窗口（毫秒）——让尾随的 exec_mcp 工具调用有时间完成其帧。
CURSOR_TOOL_DIRECTIVE	已启用（!== "0"）	open-sse/executors/cursor.ts	使 composer-2.5 能可靠发出工具调用的工具提交指令。设置为 0 可禁用。
OMNIROUTE_SYSTEM_INSTRUCTION_APPEND	（未设置）	open-sse/translator/request/claude-to-openai.ts, open-sse/translator/response/openai-to-claude.ts	在转换之后附加到系统消息中的运维方定义系统提示文本（转换后注入），会传递至 codex/Responses 和 /v1/messages 路径。它还会用作从回显的系统前言块中移除的指令前缀。保持未设置即可禁用。
OMNIROUTE_STRIP_SYSTEM_PREAMBLE	0（关闭）	open-sse/translator/response/openai-to-claude.ts, open-sse/utils/directivePreambleStripper.ts	设置为 1 可从 openai→claude 流的开头移除回显的系统提示前言块。默认关闭——这些启发式规则基于英文散文的形式，并且会修改响应载荷，因此，如果回复确实以此类部分开头，该部分将会丢失。
CURSOR_IMAGE_FETCH_TIMEOUT_MS	15000	open-sse/utils/cursorImages.ts	远程 image_url 视觉输入的单图获取超时时间（毫秒）。
CURSOR_STATE_DB_PATH	（探测）	open-sse/utils/cursorVersionDetector.ts	覆盖用于检测 IDE 版本的 Cursor IDE 状态数据库查找路径。
CURSOR_AGENT_CLI_VERSION	（检测 / 固定）	open-sse/utils/cursorAgentCliVersion.ts	Agent Run 中用于 x-cursor-client-version: cli-… 的 Agent CLI 构建 ID（YYYY.MM.DD-<hash>）。
CURSOR_AGENT_BIN	（未设置）	open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts	用于图像生成的 Cursor Agent 二进制文件路径。未设置时，处理程序会依次使用 providerSpecificData.agentBin 和 PATH。
CURSOR_IMG_TIMEOUT_MS	210000	open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts	Cursor Agent 图像任务的单图实际耗时上限（毫秒）。
CURSOR_IMG_MAX_CONCURRENT	2	open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts	Cursor 图像任务的共享席位并发限制。
CURSOR_IMG_MODEL	请求值 / auto	open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts	覆盖图像任务的 Cursor CLI --model。
UC_IMAGE_POLL_INTERVAL_MS	2000	open-sse/handlers/imageGeneration/providers/ucImage.ts	UC（uncensored.com）图像生成结果的轮询间隔（毫秒）。
UC_IMAGE_POLL_TIMEOUT_MS	60000	open-sse/handlers/imageGeneration/providers/ucImage.ts	UC 图像生成结果轮询的实际耗时上限（毫秒）。
UC_VIDEO_POLL_INTERVAL_MS	3000	open-sse/handlers/videoGeneration/providers/ucVideo.ts	UC（uncensored.com）视频生成结果的轮询间隔（毫秒）。
UC_VIDEO_POLL_TIMEOUT_MS	300000	open-sse/handlers/videoGeneration/providers/ucVideo.ts	UC 视频生成结果轮询的实际耗时上限（毫秒）。
CURSOR_DATA_DIR	（探测）	open-sse/utils/cursorAgentCliVersion.ts	覆盖 Cursor Agent CLI 数据目录（…/versions/<id>）；与官方 Agent 使用的变量相同。
CURSOR_TOKEN	（未设置）	scripts/ad-hoc/cursor-tap.cjs	开发者工具使用的直接 Cursor bearer 令牌。
OMNIROUTE_LOG_REQUEST_SHAPE	已禁用（通过 "1" 选择启用）	src/app/api/v1/chat/completions/route.ts	设置为 "1" 时，记录大型聊天载荷的内容类型/长度标记。默认关闭，以减少日志噪声。
DEBUG_RESPONSES_SSE_TO_JSON	（未设置）	open-sse/handlers/responseTranslator.ts	设置为 true 可记录 Responses API SSE→JSON 转换详情。
DEBUG_CLAUDE_NONSTREAM	（未设置）	open-sse/handlers/responseTranslator.ts	设置为 true 可在 Claude 响应转换路径中呈现空的 textContent 数据块（仅用于调试）。
NEXT_PUBLIC_OMNIROUTE_E2E_MODE	（未设置）	E2E 测试工具	设置为 true 可启用 E2E 测试模式（宽松身份验证、测试钩子）。

---

23. GitHub 集成

允许用户直接从仪表板报告问题。

变量	默认值	源文件	描述
GITHUB_ISSUES_REPO	（未设置）	src/app/api/v1/issues/report/route.ts	采用 owner/repo 格式的仓库。
GITHUB_ISSUES_TOKEN	（未设置）	src/app/api/v1/issues/report/route.ts	具有 issues:write 权限范围的 GitHub 个人访问令牌。
GITHUB_TOKEN	（未设置）	问题分类处理/云代理辅助工具	通用 GitHub 访问令牌，用作 GITHUB_ISSUES_TOKEN 的回退选项，并由 src/lib/cloudAgent/* 中的云代理辅助工具使用。

---

部署场景

有关中继后端 SRE 指南（ts/bifrost/auto 行为、9router 与 CLIProxyAPI 的放置，以及高吞吐量回退策略），请参阅中继后端策略。

最小化本地开发

JWT_SECRET=$(openssl rand -base64 48)
API_KEY_SECRET=$(openssl rand -hex 32)
INITIAL_PASSWORD=dev123
PORT=20128
NODE_ENV=development

Docker 生产环境

JWT_SECRET=<generated>
API_KEY_SECRET=<generated>
INITIAL_PASSWORD=<generated>
STORAGE_ENCRYPTION_KEY=<generated>
DATA_DIR=/data
PORT=20128
API_PORT=20129
NODE_ENV=production
AUTH_COOKIE_SECURE=true
REQUIRE_API_KEY=true
NEXT_PUBLIC_BASE_URL=https://omniroute.example.com
BASE_URL=http://localhost:20128
OMNIROUTE_MEMORY_MB=8192
CORS_ORIGIN=https://your-frontend.example.com

气隙环境 / CI

JWT_SECRET=test-jwt-secret-for-ci
API_KEY_SECRET=test-api-key-secret-for-ci
INITIAL_PASSWORD=testpass
NODE_ENV=production
OMNIROUTE_DISABLE_BACKGROUND_SERVICES=true
APP_LOG_TO_FILE=false

带反向代理的 VPS (nginx + Cloudflare)

JWT_SECRET=<generated>
API_KEY_SECRET=<generated>
STORAGE_ENCRYPTION_KEY=<generated>
PORT=20128
AUTH_COOKIE_SECURE=true
REQUIRE_API_KEY=true
NEXT_PUBLIC_BASE_URL=https://omniroute.example.com
BASE_URL=http://127.0.0.1:20128
CORS_ORIGIN=https://omniroute.example.com
ENABLE_TLS_FINGERPRINT=true
CLI_COMPAT_ALL=1

---

24. Skills 沙箱（v3.8.0+）

当 Skills 框架（src/lib/skills/）在沙箱环境中执行用户定义的自动化任务时所应用的限制和安全控制项。

变量	默认值	源文件	描述
SKILLS_SANDBOX_TIMEOUT_MS	10000（10 秒）	src/lib/skills/builtins.ts	沙箱化技能代码每次执行的墙上时钟超时时间。此为硬性上限；任何超出该时限的执行都会被终止。
SKILLS_EXECUTION_TIMEOUT_MS	（回退至 SKILLS_SANDBOX_TIMEOUT_MS）	src/lib/skills/	高级技能编排超时时间。应将其设置为高于 SKILLS_SANDBOX_TIMEOUT_MS，以允许执行多步骤工作流。
SKILLS_MAX_FILE_BYTES	1048576（1 MB）	src/lib/skills/builtins.ts	技能可从任一沙箱文件中读取的最大字节数。
SKILLS_MAX_HTTP_RESPONSE_BYTES	256000（250 KB）	src/lib/skills/builtins.ts	技能内部可从任一 HTTP 响应中捕获的最大字节数。
SKILLS_MAX_SANDBOX_OUTPUT_CHARS	100000	src/lib/skills/builtins.ts	一次沙箱调用所返回的 stdout/stderr 字符数硬性上限。
SKILLS_SANDBOX_NETWORK_ENABLED	false	src/lib/skills/builtins.ts	设置为 1/true 以允许沙箱内部访问外部网络。出于安全考虑，默认为隔离状态。
SKILLS_ALLOWED_SANDBOX_IMAGES	（空）	src/lib/skills/builtins.ts	允许用于沙箱执行的容器镜像白名单，以逗号分隔。为空表示仅允许内置默认镜像。
SKILLS_SANDBOX_DOCKER_IMAGE	（内置默认值）	src/lib/skills/	创建由 Docker 支持的沙箱时所使用的容器镜像。可覆盖此设置，以固定使用自定义的强化基础镜像。
SKILLS_SANDBOX_RUNTIME	auto	src/lib/skills/sandbox.ts, src/lib/skills/containerProvider.ts	用于技能沙箱化的容器运行时：auto | docker | apple | wsl | orbstack | podman。auto 会根据宿主操作系统选择已安装的最佳运行时（macOS 上为 Apple Container/OrbStack，Windows 上为 WSL Container，Linux 上为 Podman），并以 Docker 作为回退选项。

[!CAUTION] 启用 SKILLS_SANDBOX_NETWORK_ENABLED=true 会为任意技能代码开放出站路径。在共享部署中，应同时启用 OUTBOUND_SSRF_GUARD_ENABLED=true，并配置严格的 CORS_ORIGIN/代理策略。

---

25. 提供者配额、隧道、备份及其他运行时配置

提供者配额端点、网络隧道（Tailscale、Ngrok、MITM 调试代理）、1Proxy 出站池、数据库备份，以及执行器层或脚本引用的各功能小型覆盖配置。

变量	默认值	源文件	描述
REDIS_URL	redis://localhost:6379	src/shared/utils/rateLimiter.ts	限流器后端的 Redis 连接字符串。
ALIBABA_CODING_PLAN_HOST	（生产环境主机）	open-sse/services/bailianQuotaFetcher.ts	覆盖用于获取阿里云百炼编码套餐配额的主机。
ALIBABA_CODING_PLAN_QUOTA_URL	由主机派生	open-sse/services/bailianQuotaFetcher.ts	覆盖阿里云百炼的完整配额 URL。
QWEN_CLOUD_COOKIE	（未设置）	open-sse/services/qwenTokenPlanQuotaFetcher.ts	用于 Qwen Cloud / Model Studio 个人 Token Plan 配额网关的控制台会话 Cookie（推理 API 密钥无法读取该配额）。从 home.qwencloud.com › 计费 › 订阅（F12 › 网络）中任意一个向 cs-data.qwencloud.com 发出的 api.json 调用复制完整的 Cookie 请求标头，其中包含 login_qwencloud_ticket。该信息敏感且仅限当前会话；建议优先使用每个连接的 qwenCloudCookie 仪表板字段。
QWEN_CLOUD_SEC_TOKEN	（未设置）	open-sse/services/qwenTokenPlanQuotaFetcher.ts	手动覆盖 Token Plan 控制台网关的 sec_token。该信息敏感；未设置时，获取器会使用 Cookie 从仪表板 HTML 中解析该值。
QWEN_TOKEN_PLAN_HOST	https://cs-data.qwencloud.com	open-sse/services/qwenTokenPlanQuotaFetcher.ts	覆盖个人 Token Plan 配额获取器的网关主机（例如，Model Studio 控制台可使用 bailian-singapore-cs.alibabacloud.com）。
QWEN_TOKEN_PLAN_DASHBOARD_URL	https://home.qwencloud.com/	open-sse/services/qwenTokenPlanQuotaFetcher.ts	用于从已登录页面的 HTML 中解析 sec_token 的仪表板 URL。
ALIBABA_FREE_TIER_VISION_FE_PATH	/costing-balance/free-quota-image-video	open-sse/services/alibabaFreeTierQuotaFetcher.ts	覆盖用于获取阿里云 Model Studio 免费套餐视觉/媒体配额的控制台前端路径。
ALIBABA_FREE_TIER_MULTIMODAL_FE_PATH	/costing-balance/free-quota-multimodal	open-sse/services/alibabaFreeTierQuotaFetcher.ts	用于获取阿里云百炼免费额度多模态配额的控制台前端路径覆盖。
ALIBABA_FREE_TIER_AUDIO_FE_PATH	/costing-balance/free-quota-audio	open-sse/services/alibabaFreeTierQuotaFetcher.ts	用于获取阿里云百炼免费额度音频配额的控制台前端路径覆盖。
ALIBABA_FREE_TIER_ALLOWLIST_PATH	（未设置）	open-sse/services/alibabaFreeTierAllowlist.ts	内置阿里巴巴免费额度文本模型允许列表的可选本地 JSON 覆盖文件路径。若未指定，则依次回退到 $DATA_DIR/alibaba-free-tier-allowlist.json 和 config/alibaba-free-tier-allowlist.json。
CONTEXT_RESERVE_TOKENS	1024	open-sse/services/contextManager.ts	计算提示词预算时为补全输出预留的 token 数量。
CONTEXT_KEEP_LATEST_IMAGES	2	open-sse/services/contextManager.ts	为适应上下文窗口而清理较旧的内联图像时，要保留的最新内联图像数量（#8560）。
MODEL_ALIAS_COMPAT_ENABLED	已启用	open-sse/services/model.ts	切换旧版客户端使用的传统模型别名兼容层。
OMNIROUTE_EMERGENCY_FALLBACK	已启用	open-sse/services/emergencyFallback.ts	设置为 false（或 0）可禁用紧急预算耗尽回退机制，该机制会将失败的请求重新路由到免费的 nvidia/openai/gpt-oss-120b 模型。实际优先级为功能标志数据库覆盖 > 环境变量 > 默认值；如果数据库不可用，服务将回退到原始环境变量值。
COMMAND_CODE_CALLBACK_PORT	（未设置）	src/app/api/providers/command-code/auth/shared.ts	用于接收来自 Command Code CLI 辅助工具的 OAuth 式回调的本地端口。
COMMAND_CODE_VERSION	0.33.2	open-sse/executors/commandCode.ts	作为 x-command-code-version 请求头发送到 Command Code 上游的值。可覆盖此值以提升 CLI 版本。
COMMANDCODE_API_URL	https://api.commandcode.ai	open-sse/services/usage/command-code.ts	智能手机配额获取器遥测所使用的 Command Code 用量/配额上游服务的基础 URL。可覆盖此值以使用自托管或替代的 Command Code API。
MITM_LOCAL_PORT	443	src/mitm/server.cjs	MITM 调试代理的本地绑定端口。
MITM_DISABLE_TLS_VERIFY	0	src/mitm/server.cjs	设置为 1 以禁用上游 TLS 验证（仅限开发环境）。
MITM_IDLE_TIMEOUT_MS	60000	src/mitm/socketTimeouts.ts, src/mitm/server.cjs	代理连接的空闲套接字超时时间（毫秒）；超过此时间的空闲套接字将被关闭，以避免泄漏半开隧道。
BRIDGE_PORT	20129	bin/antigravity-bridge.mjs	Antigravity MITM 桥接器监听的端口。
ROUTER_URL	http://127.0.0.1:20128/v1/antigravity	bin/antigravity-bridge.mjs	桥接器将 Antigravity 流量转发到的路由器端点。
CERT_DIR	~/.omniroute/mitm	bin/antigravity-bridge.mjs	存放桥接器 TLS 监听器所用 server.key/server.crt 的目录；如果缺少其中任一文件，桥接器将退出。
MITM_VERBOSE	1	src/mitm/server.cjs, src/mitm/_internal/bypass.cjs	路由决策日志的详细程度：0 表示静默，值越高，记录的绕过/路由决策越多。
MITM_ROOT_CA_ENABLED	false	src/mitm/manager.ts	设置为 true 以选择启用根 CA + 每主机叶证书模型（#6684）。全新安装会自动启用；已有受信任旧版叶证书的安装会继续使用旧版固定 SAN 证书，除非主动启用此模式。
MITM_CERT_MODE	legacy	src/mitm/manager.ts, src/mitm/server.cjs	由 MITM 管理器为生成的代理进程设置（root-ca | legacy）——反映证书迁移决策；不应手动设置。
OMNIROUTE_NO_SUDO	0	src/mitm/systemCommands.ts	设置为 1（真值）以从 MITM 证书信任命令中移除开头的 sudo——适用于无 root 权限/使用用户命名空间的部署，其中操作员会手动信任 CA（例如通过 Node 的额外 CA 证书机制）。
SKIP_ANTIGRAVITY_DNS	（未设置）	src/mitm/dns/provision.ts	设置为 true 以完全跳过为 Antigravity 代理主机名配置 /etc/hosts DNS 条目——适用于无法使用 sudo/root 的容器。
OMNIROUTE_SKIP_DNS_WRITE	（未设置）	src/mitm/dns/dnsConfig.ts	设置为 1，在添加/移除 DNS 条目时跳过写入 hosts 文件——适用于沙盒化或只读测试环境。
OMNIROUTE_SKIP_SYSTEM_TRUST	0	src/mitm/cert/install.ts, src/mitm/tproxy/caTrust.ts	仅用于测试/CI 的保护开关：设置为 1 可使证书信任安装/卸载不执行任何操作，从而确保测试套件不会修改操作系统的信任存储。测试设置和 CI 工作流会自动设置此项。
CHANGELOG_BASE_REF	（自动）	scripts/check/check-changelog-integrity.mjs	为防止 CHANGELOG 内容被误删的检查关卡显式指定基准引用（默认使用 CI 中 PR 的目标分支，或最高版本的 release/v*）。
FREE_PROXY_AUTO_SYNC_ENABLED	false	src/lib/freeProxyProviders/scheduler.ts	设置为 true 可启用后台免费代理池自动同步调度器。需主动选择启用，默认关闭。
FREE_PROXY_AUTO_SYNC_INTERVAL_MS	1800000	src/lib/freeProxyProviders/scheduler.ts	自动同步间隔，以毫秒为单位（默认为 30 分钟）。
FREE_PROXY_1PROXY_ENABLED	true	src/lib/freeProxyProviders/oneproxy.ts	启用 1proxy 免费代理源。设置为 false 可禁用。
FREE_PROXY_1PROXY_API_URL	（参见 oneproxy.ts）	src/lib/freeProxyProviders/oneproxy.ts	1proxy API URL 覆盖值。
FREE_PROXY_1PROXY_MAX	500	src/lib/freeProxyProviders/oneproxy.ts	每次从 1proxy 同步时获取的最大代理数量。
FREE_PROXY_1PROXY_MIN_QUALITY	50	src/lib/freeProxyProviders/oneproxy.ts	从 1proxy 导入代理时的最低质量分数阈值。
FREE_PROXY_PROXIFLY_ENABLED	true	src/lib/freeProxyProviders/proxifly.ts	启用 Proxifly 免费代理源。设置为 false 可禁用。
FREE_PROXY_PROXIFLY_QUANTITY	100	src/lib/freeProxyProviders/proxifly.ts	每次 Proxifly 同步时获取的代理数量。
FREE_PROXY_PROXIFLY_ANONYMITY	elite	src/lib/freeProxyProviders/proxifly.ts	Proxifly 的匿名级别筛选器（elite、anonymous、transparent）。
FREE_PROXY_IPLOCATE_ENABLED	false	src/lib/freeProxyProviders/iplocate.ts	启用 IPLocate 免费代理源。仅在主动选择启用时生效。
FREE_PROXY_IPLOCATE_BASE_URL	https://raw.githubusercontent.com/iplocate/free-proxy-list/main/protocols	src/lib/freeProxyProviders/iplocate.ts	IPLocate 代理列表基础 URL 覆盖配置。
FREE_PROXY_WEBSHARE_ENABLED	true	src/lib/freeProxyProviders/webshare.ts	启用 Webshare 代理池源。设置为 false 可禁用；同时还需要设置 FREE_PROXY_WEBSHARE_API_KEY。
FREE_PROXY_WEBSHARE_API_KEY	（无）	src/lib/freeProxyProviders/webshare.ts	Webshare 账户 API 令牌（Authorization: Token <key>）。必需——未设置时，该提供者将保持禁用状态。
FREE_PROXY_WEBSHARE_API_URL	https://proxy.webshare.io/api/v2/proxy/list/	src/lib/freeProxyProviders/webshare.ts	Webshare 代理列表 API URL 覆盖配置。
FREE_PROXY_WEBSHARE_MAX	500	src/lib/freeProxyProviders/webshare.ts	每次 Webshare 同步导入的最大代理数量。
NEXT_PUBLIC_VERCEL_RELAY_ENABLED	true	src/app/(dashboard)/…/ProxyPoolTab.tsx	在“代理池”选项卡中显示或隐藏“部署 Vercel Relay”按钮。
VERCEL_API_BASE	https://api.vercel.com	src/app/api/settings/proxy/vercel-deploy/route.ts	Vercel API 基础 URL 覆盖配置（用于测试）。
NEXT_PUBLIC_VERCEL_RELAY_DEFAULT_PROJECT	omniroute-relay	src/app/(dashboard)/…/VercelRelayModal.tsx	Vercel Relay 部署模态框中预填的默认项目名称。
TAILSCALE_BIN	（自动检测）	src/lib/tailscaleTunnel.ts	tailscale 二进制文件的显式路径。
TAILSCALED_BIN	（自动检测）	src/lib/tailscaleTunnel.ts	tailscaled 守护进程二进制文件的显式路径。
TAILSCALE_AUTHKEY	（未设置）	src/lib/tailscaleTunnel.ts	用于非交互式/无头模式 tailscale up 的预共享 Tailscale 身份验证密钥（通过 --auth-key= 传递）。未设置时，登录将回退到交互式浏览器身份验证 URL。
NGROK_AUTHTOKEN	（未设置）	src/lib/ngrokTunnel.ts	对出站 ngrok 隧道进行身份验证。
DB_BACKUP_MAX_FILES	20	src/lib/db/backup.ts	手动/计划备份清理所保留的 SQLite 备份文件最大数量。迁移快照按内容寻址，并会在数据库状态相同时复用；在并发迁移窗口内不会被清理。覆盖在“设置 → 数据库备份保留”中保存的值。
DB_BACKUP_RETENTION_DAYS	0	src/lib/db/backup.ts	手动/计划备份清理所保留文件的最长时间（天）。0 表示禁用按时间清理。迁移快照在并发迁移窗口内不会被清理。覆盖在“设置 → 数据库备份保留”中保存的值。
OMNIROUTE_BACKUP_SCHEDULE_JOB_INTERVAL_MS	30000	src/lib/jobs/backupScheduleJob.ts	执行 backup-schedule.json 的服务器端任务的轮询间隔（毫秒）。该值必须远低于 cron 的 1 分钟粒度；低于 5000 或无法解析的值将回退为 30000。
CONTAINER_HOST	docker	scripts/check-permissions.sh	供入口点权限检查使用的容器运行时提示。对于任何 Podman 拓扑，请将其设置为 podman。由于容器无法确定引擎位于本地还是通过 Podman Machine 访问，因此警告会保持拓扑中立，并指向 contrib/podman/README.md。
QUOTA_STORE_DRIVER	sqlite	src/lib/quota/storeFactory.ts	配额共享用量存储后端：sqlite（默认）或 redis。
QUOTA_STORE_REDIS_URL	（未设置）	src/lib/quota/storeFactory.ts	当 QUOTA_STORE_DRIVER=redis 时使用的 Redis 连接字符串（例如 redis://localhost:6379）。
QUOTA_SATURATION_THRESHOLD	0.5	src/lib/quota/enforce.ts	池饱和度比率 (0..1)；达到或超过该值时，池将进入严格模式（不允许借用）。
QUOTA_SOFT_DEPRIORITIZE_FACTOR	0.7	open-sse/services/combo.ts	当软配额策略降低某个目标的优先级时，应用于该目标的评分乘数 (0..1)。
STATUS_SOFT_DEPRIORITIZE_FACTOR	0.5	open-sse/services/combo/autoStrategy.ts	当预检配额截止机制关闭时 (#4540)，在自动组合评分中应用于额度耗尽的提供者（credits_exhausted/rate_limited）的评分乘数 (0..1)。
QUOTA_CONSUMPTION_RETENTION_DAYS	14	src/lib/db/quotaConsumption.ts	quota_consumption 存储桶在 GC (gcQuotaConsumption) 前的保留期限（天）。
QUOTA_PREFLIGHT_CUTOFF_ENABLED	false	src/lib/resilience/settings.ts	可选启用（默认关闭）：启用自动路由硬配额截止机制，在评分前剔除低配额候选项。
OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL	false	open-sse/services/autoCombo/virtualFactory.ts	可选启用（默认关闭）：当 auto/<category>:<tier> 筛选器未匹配到已连接的候选项时，恢复旧版行为，即回退到完整的（未筛选的）池，而不是返回空池。默认关闭意味着 :free 表示“仅限免费层级”。
OMNIROUTE_CHAOS_MAX_PANEL	5	open-sse/services/autoCombo/virtualFactory.ts	auto/*:chaos 广播变体的面板大小上限（限制在 1–10）；一个请求最多可扇出到该数量且提供者各不相同的模型。
OMNIROUTE_CHAOS_MIN_PANEL	（引擎默认值）	open-sse/services/autoCombo/virtualFactory.ts	转发给 chaos 广播处理程序的最小面板大小调优值；未设置时保留引擎默认值。
OMNIROUTE_CHAOS_PANEL_TIMEOUT_MS	（引擎默认值）	open-sse/services/autoCombo/virtualFactory.ts	整个 chaos 面板扇出的硬超时时间 (ms)；未设置时保留引擎默认值。
GROK_AUTH_PATH	~/.grok/auth.json	open-sse/services/grokQuotaFetcher.ts	用于获取 grok-web 每周配额的 Grok CLI auth.json 路径；可针对测试或非标准 CLI 安装进行覆盖。
AGENTBRIDGE_UPSTREAM_CA_CERT	（未设置）	src/mitm/manager.ts	AgentBridge 上游 TLS 连接信任的额外 CA 证书（PEM）。
INSPECTOR_BUFFER_SIZE	1000	src/mitm/inspector/buffer.ts	流量检查器环形缓冲区中保留的已捕获请求的最大数量。
INSPECTOR_MAX_BODY_KB	1024	src/mitm/inspector/buffer.ts	截断前捕获的请求/响应正文的最大大小（KB）。
INSPECTOR_HTTP_PROXY_PORT	8080	src/mitm/inspector/httpProxyServer.ts	流量检查器 HTTP 代理的本地端口。
INSPECTOR_HTTP_PROXY_AUTOSTART	false	src/mitm/inspector/httpProxyServer.ts	启动时自动启动检查器 HTTP 代理。
INSPECTOR_TLS_INTERCEPT	false	src/lib/inspector/captureState.ts	为捕获的 HTTPS 流量启用 TLS 拦截（MITM）。
INSPECTOR_LLM_HOSTS_EXTRA	（未设置）	src/lib/inspector/captureState.ts	作为 LLM 端点进行捕获的额外主机名（以逗号分隔）。
INSPECTOR_MASK_SECRETS	true	src/mitm/inspector/buffer.ts	对捕获流量中的机密信息（身份验证标头/API 密钥）进行掩码处理。
INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES	30	src/app/api/tools/traffic-inspector/capture-modes/system-proxy/route.ts	系统代理保护机制自动还原操作系统代理设置前等待的分钟数。
INSPECTOR_INTERNAL_INGEST_TOKEN	（自动）	src/app/api/tools/traffic-inspector/internal/ingest/route.ts	用于验证向检查器内部采集端点提交的捕获数据的令牌。
PLAYGROUND_COMPARE_MAX_COLUMNS	4	src/app/(dashboard)/dashboard/playground/	Playground 比较模式中并排显示的最大列数。
PLAYGROUND_IMPROVE_PROMPT_DEFAULT_MODEL	（未设置）	src/app/(dashboard)/dashboard/playground/	Playground“改进提示词”操作的默认模型（未设置时回退到当前活动模型）。
BIFROST_ENABLED	1	src/app/api/v1/relay/chat/completions/bifrost/route.ts	Bifrost 边车代理的总开关。设置为 0 时，该路由返回 503，并携带 X-Bifrost-Killswitch 标头，同时将操作方切换至 TS 路径。可用于在不重新部署的情况下禁用边车（一级路由器事故、密钥轮换）。
BIFROST_BASE_URL	（未设置）	src/app/api/v1/relay/chat/completions/bifrost/route.ts	设置后，Bifrost 边车代理路由会将 /v1/chat/completions 流量转发到此 Go 网关，而不是 TS 中继处理程序。未设置 → 返回 503 并回退。尾部斜杠会被移除。
BIFROST_PORT	8080	src/lib/services/bootstrap.ts	当 OmniRoute 管理 Bifrost 边车生命周期时，受监管的 Bifrost 嵌入式服务所绑定的端口（127.0.0.1:<port>）。默认为 8080。
BIFROST_API_KEY	（未设置）	src/app/api/v1/relay/chat/completions/bifrost/route.ts	Bifrost 网关的 API 密钥（以 Authorization: Bearer ... 形式发送）。如果未设置，该路由要求请求携带有效的 OmniRoute API 密钥；此密钥仅用于网关端身份验证。
BIFROST_STREAMING_ENABLED	true	src/app/api/v1/relay/chat/completions/bifrost/route.ts	为 true 时，Bifrost 边车路由通过网关使用 SSE 将响应流式返回，而不是使用 TS 流式执行器。设置为 0 可强制通过网关返回非流式 JSON 响应。
BIFROST_TIMEOUT_MS	30000	src/app/api/v1/relay/chat/completions/bifrost/route.ts	代理到 Bifrost 网关时的单请求超时时间（毫秒）。超时时，该路由通过 X-Bifrost-Fallback 标头返回 TS 中继路径。
OMNIROUTE_BIFROST_KEY	（未设置）	src/app/api/v1/relay/chat/completions/bifrost/route.ts	BIFROST_API_KEY 的别名（供通过 OMNIROUTE_* 读取环境变量的脚本使用）。同时设置两者时，BIFROST_API_KEY 优先。
OMNIROUTE_RELAY_BACKEND	ts / auto	src/app/api/v1/relay/chat/completions/routingBackend.ts	/api/v1/relay/chat/completions 的中继后端：ts | bifrost | auto。ts = TypeScript 中继（未配置 Bifrost 时的默认值）；当设置了 BIFROST_BASE_URL 且 BIFROST_ENABLED ≠ 0 时，auto 会选择 Bifrost，并在边车不可访问时自动回退到 TS；bifrost 强制使用 Bifrost（严格模式，不回退）。身份验证、速率限制、注入防护和允许列表始终先在 Next 路由中执行。响应会携带 X-Routing-Backend / X-Routing-Fallback / X-Routing-Fallback-Reason。
RELAY_ROUTING_BACKEND	（未设置）	src/app/api/v1/relay/chat/completions/routingBackend.ts	OMNIROUTE_RELAY_BACKEND 的可接受别名（使用相同的 ts | bifrost | auto 值）。如果两者均已设置，则 OMNIROUTE_RELAY_BACKEND 优先。
OMNIROUTE_BIFROST_FAILURE_COOLDOWN_MS	5000	src/app/api/v1/relay/chat/completions/bifrostCooldown.ts	在 auto 模式下，Bifrost sidecar 跳转失败后，relay 再次尝试 sidecar 之前的冷却时间（毫秒）；冷却期间直接路由至 TS 路径，冷却结束后再次探测。0 表示禁用。仅在 OMNIROUTE_RELAY_BACKEND=auto 时适用。
OMNIROUTE_TLS_CERT	（未设置）	bin/cli/commands/serve.mjs	用于通过 HTTPS 提供 omniroute serve 服务的 PEM TLS 证书路径（等同于 --tls-cert）。必须与 OMNIROUTE_TLS_KEY 配套使用；之后，独立服务器将在同一监听器上终止 TLS（wss:// 可保持不变正常工作）。未设置 → 普通 HTTP。仅提供证书或密钥之一，或路径不可读时，会记录警告并继续使用 HTTP。
OMNIROUTE_TLS_KEY	（未设置）	bin/cli/commands/serve.mjs	用于 omniroute serve HTTPS 的 PEM TLS 私钥路径（等同于 --tls-key）。必须与 OMNIROUTE_TLS_CERT 配套使用。请参阅 OMNIROUTE_TLS_CERT。
OMNIROUTE_LOCAL_ENDPOINTS_ENABLED	0	src/lib/security/localEndpoints.ts	/api/local/* 路由的总开关。未设置或设为 0 时，生产环境中的所有 /api/local/* 路由均返回 503。在非回环部署中，必须设为 1 才能启用 Redis 启动器及类似的一键式本地服务启动器。与 isLocalOnlyPath() 路由守卫分类形成双重保护（src/server/authz/routeGuard.ts 中的 LOCAL_ONLY_API_PREFIXES）。
OMNIROUTE_LOCAL_ENDPOINTS_TOKEN	（未设置）	src/lib/security/localEndpoints.ts	供非回环地址调用方（例如桌面应用）访问 /api/local/* 时使用的 Bearer 令牌。设置后，来自非回环 IP 的请求必须携带 Authorization: Bearer <token>。在非回环部署中，当 OMNIROUTE_LOCAL_ENDPOINTS_ENABLED=1 时，此项为必需。
OMNIROUTE_REDIS_CONTAINER_NAME	omniroute-redis	bin/cli/commands/redis.mjs	一键式 Redis 启动器（omniroute redis up）的容器名称。CLI 和 RedisLauncherPanel GUI 均会使用。
OMNIROUTE_REDIS_HOST_PORT	6379	bin/cli/commands/redis.mjs	一键式 Redis 启动器的主机端口。如果主机已占用 6379，请更改此值。容器内部端口仍为 6379。
OMNIROUTE_REDIS_BIND_HOST	127.0.0.1	bin/cli/commands/redis.mjs	一键式 Redis 启动器发布到的主机接口。启动器会在没有密码的情况下启动 Redis，因此绑定到 0.0.0.0 会让局域网中的每台主机都能访问未经身份验证的 Redis——仅当你同时自行在实例上设置密码时，才应扩大绑定范围。
REDIS_BIND_HOST	127.0.0.1	docker-compose.yml	docker-compose 用于发布 Redis sidecar 的主机接口（#9286）。compose 中的 Redis 未使用 requirepass；应用容器通过 compose 网络（redis:6379）访问它——发布的端口仅供主机侧工具使用。0.0.0.0 会将未经身份验证的 Redis 暴露给整个局域网。
REDIS_PORT	6379	docker-compose.yml	compose Redis 边车容器的主机端口。
APP_BIND_HOST	127.0.0.1	docker-compose.yml, docker-compose.prod.yml	docker-compose 用于发布应用自身的仪表板/API/实时 WS 端口的主机接口（#12568）。由于 .env.example 默认提供 REQUIRE_API_KEY=false，使用 0.0.0.0 会将匿名 /v1 LLM 代理暴露给整个 LAN/WAN——仅当 REQUIRE_API_KEY=true，或前置反向代理强制执行其自身的身份验证时，才应扩大监听范围。
QDRANT_BIND_HOST	127.0.0.1	docker-compose.yml	docker-compose 用于发布 Qdrant 内存边车容器的主机接口（#12578）。关于 LAN 暴露风险的考虑与 REDIS_BIND_HOST 相同。
BIFROST_BIND_HOST	127.0.0.1	docker-compose.yml	docker-compose 用于发布 Bifrost 路由器边车容器的主机接口（#12578）。关于 LAN 暴露风险的考虑与 REDIS_BIND_HOST 相同。
REDIS_KEY_PREFIX	omniroute:	src/shared/utils/rateLimiter.ts	应用于每个 OmniRoute Redis 键的命名空间前缀（速率限制器、身份验证缓存、配额存储、预热熔断器）。当 Redis 实例与其他应用共享时，可防止键冲突（#11042）。
OMNIROUTE_INTERNAL_SERVICE_TOKEN	（未设置——机制已禁用）	src/lib/api/internalServiceAuth.ts	用于保留身份的内部 REST 跳转的共享密钥（#9260）：调用其他本地 OmniRoute 路由的 OmniRoute 组件会将其作为 x-omniroute-internal-service-token 发送，从而保留原始调用者的身份。使用 timingSafeEqual 进行比较。
OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE	（未设置）	src/lib/api/internalServiceAuth.ts	内部服务令牌的密钥文件变体：指向某个文件的路径，该文件去除首尾空白后的内容即为令牌。仅当内联变量未设置时才会使用。
OPENROUTER_PROVIDER_STATS_ENABLED	true	src/lib/catalog/openrouterProviderStats.ts	使用 OpenRouter 每周排名统计信息丰富仪表板的提供者列表（#9324）。默认启用；设置为 false 可完全跳过后台获取（非阻塞，且绝不会导致致命错误）。
OPENROUTER_PROVIDER_STATS_TTL_MS	86400000（24 小时）	src/lib/catalog/openrouterProviderStats.ts	OpenRouter 提供者统计快照的缓存 TTL，单位为毫秒。
OMNIROUTE_REDIS_IMAGE	redis:7-alpine	bin/cli/commands/redis.mjs	一键式 Redis 启动器使用的 Redis 镜像。可根据需要覆盖为 redis:8-alpine 或私有注册表镜像。
QDRANT_HOST	qdrant	（可选启用的集群配置）	当 --profile memory 处于活动状态时，Qdrant sidecar 的主机名。默认指向网络内的 qdrant 服务名称；对于外部部署，请覆盖此值。仅当代码中的 qdrantEnabled 为 true 时使用（src/lib/memory/vectorStore.ts:108）。
QDRANT_PORT	6333	（可选启用的集群配置）	Qdrant sidecar 的 REST 端口。
QDRANT_GRPC_PORT	6334	（可选启用的集群配置）	Qdrant sidecar 的 gRPC 端口。供在流式操作中优先使用 gRPC 而非 REST 的客户端库使用。
QDRANT_API_KEY	（未设置）	（可选启用的集群配置）	用于 Qdrant Cloud 或经过身份验证的本地部署实例的可选 API 密钥。留空 → 不发送 api-key 标头。
QDRANT_COLLECTION	omniroute-memory	（可选启用的集群配置）	OmniRoute 对话记忆嵌入的集合名称。首次运行时使用 QDRANT_VECTOR_SIZE 指定的维度创建。
QDRANT_EMBEDDING_MODEL	text-embedding-3-small	（可选启用的集群配置）	记录在 Qdrant 集合元数据中的默认嵌入模型名称。实际嵌入由 OmniRoute 设置中的 embeddingModel 字段所指向的提供者生成。
QDRANT_VECTOR_SIZE	1536	（可选启用的集群配置）	嵌入向量维度。必须与你用于生成嵌入的模型匹配（text-embedding-3-small → 1536；ada-002 → 1536；nomic-embed-text → 768）。
QDRANT_HNSW_EF_CONSTRUCT	128	（可选启用的集群配置）	HNSW 索引构建时的准确度。值越高 = 构建越慢、搜索越快。
OMNIROUTE_ROTATION_ENABLED	true	open-sse/services/rotationConfig.ts	用于控制可由运维人员配置的账户轮换功能的总开关。当为 false 时，下面的所有 OMNIROUTE_ROTATE_* 类别都不会触发账户回退（总开关关闭状态也会阻止默认启用的 429/500/502 类别）。这使监管前端（例如 VibeProxy 桌面应用）能够将其自身的轮换规则同步到后端的账户回退引擎。
OMNIROUTE_ROTATION_RATE_LIMIT_RESET_SECONDS	0	open-sse/services/rotationConfig.ts	当上游未提供明确的重置提示时，对受到速率限制的账户应用的冷却时间（秒）。0 = 使用引擎的默认冷却时间，而不是固定的覆盖值。
OMNIROUTE_ROTATION_DISABLE_TAG_WITHOUT_RESET	true	open-sse/services/rotationConfig.ts	前端“不在没有重置时间的情况下标记为受速率限制”偏好的镜像设置。
OMNIROUTE_ROTATE_ON_429	true	open-sse/services/rotationConfig.ts	针对 429 错误启用按状态回退。当设置为 false（且 OMNIROUTE_ROTATION_ENABLED=true）时，429 将不再触发账户轮换，而是返回给客户端。
OMNIROUTE_ROTATE_429_THRESHOLD	1	open-sse/services/rotationConfig.ts	在 OMNIROUTE_ROTATE_429_WINDOW_SECONDS 时间范围内，触发账户轮换所需的 429 错误数量。1（默认值）表示立即轮换，以保留原有行为。
OMNIROUTE_ROTATE_429_WINDOW_SECONDS	120	open-sse/services/rotationConfig.ts	用于统计计入 OMNIROUTE_ROTATE_429_THRESHOLD 的 429 错误的滑动窗口（秒）。
OMNIROUTE_ROTATE_ON_500	true	open-sse/services/rotationConfig.ts	针对 5xx 服务器错误（不包括拥有独立类别的 502）启用按状态回退。当设置为 false 时，这些错误将不再触发账户轮换。
OMNIROUTE_ROTATE_500_THRESHOLD	1	open-sse/services/rotationConfig.ts	在 OMNIROUTE_ROTATE_500_WINDOW_SECONDS 时间范围内，触发账户轮换所需的 5xx 错误数量。1（默认值）表示立即轮换。
OMNIROUTE_ROTATE_500_WINDOW_SECONDS	120	open-sse/services/rotationConfig.ts	用于统计计入 OMNIROUTE_ROTATE_500_THRESHOLD 的 5xx 错误的滑动窗口（秒）。
OMNIROUTE_ROTATE_ON_502	true	open-sse/services/rotationConfig.ts	针对 502（网关错误）启用按状态回退。当设置为 false 时，502 错误将不再触发账户轮换。
OMNIROUTE_ROTATE_502_THRESHOLD	1	open-sse/services/rotationConfig.ts	在 OMNIROUTE_ROTATE_502_WINDOW_SECONDS 时间范围内，触发账户轮换所需的 502 错误数量。1（默认值）表示立即轮换。
OMNIROUTE_ROTATE_502_WINDOW_SECONDS	120	open-sse/services/rotationConfig.ts	用于统计计入 OMNIROUTE_ROTATE_502_THRESHOLD 的 502 错误的滑动窗口（秒）。
OMNIROUTE_ROTATE_ON_400	false	open-sse/services/rotationConfig.ts	选择启用（默认关闭）：设为 true 时，普通的 400（错误请求）也会触发账户轮换。此行为仅为补充——它绝不会阻止引擎的现有行为；无论此标志如何设置，携带速率限制/配额文本的 400 仍会触发故障转移。
OMNIROUTE_ROTATE_400_THRESHOLD	1	open-sse/services/rotationConfig.ts	在 OMNIROUTE_ROTATE_400_WINDOW_SECONDS 时间范围内，触发账户轮换所需的 400 错误数量（仅当 OMNIROUTE_ROTATE_ON_400=true 时使用）。
OMNIROUTE_ROTATE_400_WINDOW_SECONDS	120	open-sse/services/rotationConfig.ts	用于统计计入 OMNIROUTE_ROTATE_400_THRESHOLD 的 400 错误的滑动时间窗口（秒）。

Claude 预热调度器

为选择启用的 Anthropic OAuth 连接提供由 Cron 驱动的预热，使 5 小时速率限制窗口由一个简单的计划请求开启，而不是由第一个真实请求开启（#8848）。除非 OMNIROUTE_WARMUP_ENABLED 为真值，并且连接已在 settings.claudeWarmup.connections 中标记，否则调度器将保持关闭；即使环境变量已开启，连接列表为空也意味着不会预热任何连接。

变量	默认值	源文件	描述
OMNIROUTE_WARMUP_ENABLED	（未设置 → 关闭）	src/lib/warmupScheduler.ts	预热调度器的总开关。接受 1/true/yes/on（不区分大小写，并会去除首尾空白）。任何其他值或未设置都会使调度器保持关闭。
OMNIROUTE_WARMUP_CRON	0 7 * * *	src/lib/warmupScheduler.ts	预热任务的五字段 Cron 表达式，无论主机时钟如何，均按 America/Los_Angeles（Anthropic 的重置时区）计算。
OMNIROUTE_WARMUP_CONCURRENCY	3	src/lib/warmupScheduler.ts	每次任务并行预热的连接数。限制在 1-10 之间；非数字值将回退为 3。
OMNIROUTE_WARMUP_MODEL	claude-3-5-haiku-20241022	src/lib/warmupScheduler.ts	用于预热请求的模型。仅当默认模型在你的套餐中不可用时才覆盖；请选择仍能开启窗口的最便宜模型。

浏览器登录 VNC 会话与数据目录别名

容器化的 Chromium+VNC，用于以交互方式捕获浏览器登录凭据（/api/vnc-session），另加一个旧版 DATA_DIR 别名。所有配置均为可选——VNC 默认使用随附的 omniroute-vnc-chromium:local 镜像，只有在使用自定义容器镜像、端口或调整生命周期时才需要覆盖。

变量	默认值	源文件	描述
OMNIROUTE_VNC_IMAGE	omniroute-vnc-chromium:local	src/lib/vncSession/manifest.ts	Chromium+VNC 登录容器的 Docker 镜像标签。构建 docker/vnc-browser/chromium，或将其指向自定义镜像。
OMNIROUTE_DOCKER_BIN	docker	src/lib/vncSession/manifest.ts	用于启动 VNC 容器的容器运行时二进制文件（例如，可将其设置为 podman）。
OMNIROUTE_VNC_CONTAINER_VNC_PORT	3000	src/lib/vncSession/manifest.ts	容器内暴露的 VNC/noVNC 端口。
OMNIROUTE_VNC_CONTAINER_CDP_PORT	9223	src/lib/vncSession/manifest.ts	容器内的 Chrome DevTools Protocol 端口。
OMNIROUTE_VNC_CONTAINER_PROFILE_DIR	/config	src/lib/vncSession/manifest.ts	容器内的 Chromium 配置文件目录路径。
OMNIROUTE_VNC_PROFILE_DIR	$HOME/.omniroute/browser-login-profiles	src/lib/vncSession/manifest.ts	用于存放持久化浏览器登录配置文件的主机目录。
OMNIROUTE_VNC_IDLE_MS	600000（10 分钟）	src/lib/vncSession/manifest.ts	非活动 VNC 会话被清理前的空闲超时时间（毫秒）。
OMNIROUTE_VNC_MAX_MS	1800000（30 分钟）	src/lib/vncSession/manifest.ts	单个 VNC 会话生命周期的硬性上限（毫秒）。
OMNIROUTE_VNC_MAX_SESSIONS	4	src/lib/vncSession/manifest.ts	VNC 并发会话的最大数量。
OMNIROUTE_VNC_READY_MS	45000	src/lib/vncSession/manifest.ts	等待容器化浏览器进入 CDP 就绪状态的超时时间（毫秒）。
OMNIROUTE_VNC_HARVEST_MS	20000	src/lib/vncSession/manifest.ts	登录完成后提取已捕获会话/cookie 的超时时间（毫秒）。
OMNIROUTE_VNC_CHROMIUM_ARGS	--remote-debugging-port=9222 --no-first-run --no-default-browser-check	src/lib/vncSession/manifest.ts	传递给容器化 Chromium 的额外命令行标志。
OMNIROUTE_VNC_NETWORK	omniroute-vnc-browser-login	src/lib/vncSession/manifest.ts	VNC 登录容器加入的专用 Docker 网络（#12571），而非默认桥接网络，因此同级容器无法访问其 CDP 桥接端口。
VIBEPROXY_DATA_DIR	（未设置）	open-sse/services/notionThreadSessions.ts	DATA_DIR 的旧版别名，仅在 DATA_DIR 和 OMNIROUTE_DATA_DIR 均未设置时检查。用于定位 Notion Web 线程会话缓存（<dir>/notion-web-thread-sessions.json）。

---

26. 测试与 E2E 工具

由 scripts/dev/run-next-playwright.mjs、scripts/dev/smoke-electron-packaged.mjs、 scripts/dev/run-ecosystem-tests.mjs 和 scripts/build/uninstall.mjs 使用。在生产部署中，请勿设置以下任何 值。

变量	默认值	源文件	描述
OMNIROUTE_E2E_BOOTSTRAP_MODE	auth	scripts/dev/run-next-playwright.mjs	Playwright 运行器的 E2E 引导模式（auth、fresh、reuse）。
OMNIROUTE_E2E_PASSWORD	回退到 INITIAL_PASSWORD	scripts/dev/run-next-playwright.mjs	注入 Playwright 环境的管理员密码。
OMNIROUTE_DISABLE_LOCAL_HEALTHCHECK	true	scripts/dev/run-next-playwright.mjs	在 Playwright 运行期间禁用本地健康检查轮询。
OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK	true	scripts/dev/run-next-playwright.mjs	在测试期间禁用 OAuth 令牌健康检查循环。
OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS	（未设置）	src/lib/tokenHealthCheck.ts	从主动令牌刷新扫描中排除的提供者，以逗号分隔（例如 codex,openai）。这是完全禁用健康检查的针对性替代方案——短 TTL 提供者会继续刷新，而级联提供者仅保持被动响应。
OMNIROUTE_HIDE_HEALTHCHECK_LOGS	true	scripts/dev/run-next-playwright.mjs	禁止在 Playwright 标准输出中显示健康检查日志。
OMNIROUTE_PLAYWRIGHT_SKIP_BUILD	0	scripts/dev/run-next-playwright.mjs	在 Playwright 启动前跳过 Next.js 生产构建（CI 优化）。
OMNIROUTE_SKIP_UNINSTALL_HOOK	0	scripts/build/uninstall.mjs	跳过 OmniRoute 卸载钩子（CI 使用此选项以保持 node_modules 完整）。
ECOSYSTEM_SERVER_WAIT_MS	180000	scripts/dev/run-ecosystem-tests.mjs	在运行生态系统/协议测试之前，等待服务器进入健康状态的时间（毫秒）。
ELECTRON_SMOKE_URL	http://127.0.0.1:20128/login	scripts/dev/smoke-electron-packaged.mjs	Electron 冒烟测试工具预期已打包应用提供服务的 URL。
ELECTRON_SMOKE_TIMEOUT_MS	45000	scripts/dev/smoke-electron-packaged.mjs	冒烟测试工具放弃前的总超时时间（毫秒）。
ELECTRON_SMOKE_SETTLE_MS	2000	scripts/dev/smoke-electron-packaged.mjs	页面加载后的稳定等待时长（毫秒）。
ELECTRON_SMOKE_APP_EXECUTABLE	（自动）	scripts/dev/smoke-electron-packaged.mjs	已打包 Electron 可执行文件的显式路径。
ELECTRON_SMOKE_DATA_DIR	（临时目录）	scripts/dev/smoke-electron-packaged.mjs	Electron 冒烟测试运行所使用的数据目录。
ELECTRON_SMOKE_KEEP_DATA	0	scripts/dev/smoke-electron-packaged.mjs	设置为 1 可在运行后保留冒烟测试数据目录。
ELECTRON_SMOKE_STREAM_LOGS	0	scripts/dev/smoke-electron-packaged.mjs	设置为 1 可在运行期间将 Electron 日志流式输出到 stdout。
ELECTRON_SMOKE_COLD_RESTART	0	scripts/dev/smoke-electron-packaged.mjs	#7592：使用同一数据目录重新启动，并断言第二次启动时选择原生 SQLite 驱动程序。
CLI_DEVIN_BIN	（PATH 查找）	open-sse/executors/devin-cli.ts	覆盖 Devin CLI 二进制文件路径。

文档翻译流水线

供 scripts/i18n/run-translation.mjs（npm run i18n:run 命令）使用。 所有五个变量默认均未设置——仅在应允许运行文档翻译器的机器上 在 .env 中设置它们。

变量	默认值	源文件	描述
OMNIROUTE_TRANSLATION_API_URL	（未设置）	scripts/i18n/run-translation.mjs	翻译后端的 OpenAI 兼容基础 URL。
OMNIROUTE_TRANSLATION_API_KEY	（未设置）	scripts/i18n/run-translation.mjs	翻译后端的 Bearer 令牌（绝不记录到日志中）。
OMNIROUTE_TRANSLATION_MODEL	（未设置）	scripts/i18n/run-translation.mjs	模型 ID，例如 gpt-4o-mini 或 cx/gpt-5.4-mini。
OMNIROUTE_TRANSLATION_TIMEOUT_MS	60000	scripts/i18n/run-translation.mjs	每个请求的超时时间（以毫秒为单位）。
OMNIROUTE_TRANSLATION_CONCURRENCY	4	scripts/i18n/run-translation.mjs	处理多个文件/区域设置时的并行翻译请求数。

---

27. Radar 信息源（自托管）

此可选附加功能由 RADAR_ENABLED 功能标志控制（默认关闭——该功能标志通过“设置”/数据库切换，而非环境变量；请参阅 docs/frameworks/RADAR.md）。 下面的前四个变量是可选的覆盖项，用于自托管或分叉的信息源以及支持者密钥流程。第五个变量 RADAR_ADMIN_URL 是一个独立的、无默认值的链接，指向所有者的 私有运维面板。有关完整的模块文档及其 端到端激活和引导式设置流程，请参阅 docs/frameworks/RADAR.md。

通用的“主页/更新日志”公告读取器并非通过环境 变量配置，也不依赖 RADAR_ENABLED 功能标志。它仅通过 GET 读取 src/shared/utils/releaseNotes.ts 中声明的公共仓库 news.json URL；忽略公告的 ID 仍保存在浏览器本地存储中。

变量	默认值	源文件	描述
RADAR_FEED_URL	https://radar.omniroute.online	src/lib/radar/{sync,referralsSync,offersSync,intelSync}.ts	由采用独立签名的目录、推荐、支持者优惠和情报信息源共享的基础 URL。可覆盖此值，使其指向自托管或分叉的服务。
RADAR_FEED_PUBKEY	（固定的默认密钥）	src/lib/radar/pinnedKeys.ts	用于验证自定义信息源签名的 Ed25519 公钥（base64-DER SPKI 或 PEM）。
RADAR_CONTRIBUTOR_CLAIM_URL	https://radar.omniroute.online/auth/github	src/lib/radar/links.ts	仪表板中的“我是贡献者”按钮打开的 URL（GitHub OAuth 支持者密钥申领流程）。
RADAR_SUPPORTER_PLANS_URL	https://radar.omniroute.online/planos	src/lib/radar/links.ts	仪表板中的“支持项目”按钮打开的 URL（付款/计划页面）。
RADAR_ADMIN_URL	（未设置）	src/lib/radar/links.ts	仅供所有者使用的私有运维面板链接。除通过 SSH 转发的 HTTP 环回地址外，均要求使用 HTTPS；未设置或无效的值不会创建导航项。

---

审计：已移除/失效的变量

以下变量曾出现在旧版本的 .env.example 中，但在当前代码库中没有运行时引用。它们已被移除：

变量	原因
STORAGE_DRIVER=sqlite	任何源文件都不会读取此变量。SQLite 是唯一受支持的驱动程序，无需进行选择。
INSTANCE_NAME=omniroute	存在于旧文档/环境模板中，但运行时未使用。未来的多实例功能可能会重新启用它。
SQLITE_MAX_SIZE_MB=2048	源代码中未引用。数据库大小未受到人为限制。
SQLITE_CLEAN_LEGACY_FILES=true	源代码中未引用。旧文件清理功能可能已被移除。
CLI_ROO_BIN	未在 src/shared/services/cliRuntime.ts 中注册。
CLI_KIMI_CODING_BIN	未在 src/shared/services/cliRuntime.ts 中注册（Kimi Coding 使用 OAuth，而非 CLI 二进制文件）。
IFLOW_OAUTH_CLIENT_ID / IFLOW_OAUTH_CLIENT_SECRET	源代码中任何位置均未引用。
CEREBRAS_API_KEY / COHERE_API_KEY / FIREWORKS_API_KEY / GROQ_API_KEY / MISTRAL_API_KEY / NEBIUS_API_KEY / PERPLEXITY_API_KEY / TOGETHER_API_KEY / XAI_API_KEY	已在 v3.8.0 中移除。运行时不再读取这些环境变量——凭据来自 Dashboard / data/provider-credentials.json / 加密数据库。
CURSOR_PROTOBUF_DEBUG	已在 v3.8.0 中移除。Cursor 执行器使用 CURSOR_DEBUG / CURSOR_STREAM_DEBUG（参见 §22）。
CLI_COMPAT_KIRO	已在 v3.8.0 中移除。Kiro 位于 CLI_COMPAT_OMITTED_PROVIDER_IDS 中——其开关不会产生任何效果。
QIANFAN_API_KEY	已在 v3.8.0 中与其他未使用的提供者 API 密钥占位项一并移除。

默认值修正

变量	旧 .env.example 值	实际代码默认值	修复
APP_LOG_RETENTION_DAYS	90	7	✅ 移除误导性值；将 7 记录为默认值
CALL_LOG_RETENTION_DAYS	90	7	✅ 移除误导性值；将 7 记录为默认值

OpenCode 配置重新生成（临时工具）

由 scripts/ad-hoc/regen-opencode-config.ts 使用，用于重新生成 opencode.json， 其中包含从正在运行的 OmniRoute 实例获取的准确 limit.context 和 limit.output 值。正常运行不需要这些变量——该脚本仅用于开发工具。

变量	默认值	源文件	说明
OMNIROUTE_URL	http://localhost:20128	scripts/ad-hoc/regen-opencode-config.ts	用于查询 /v1/models 的 OmniRoute 实例基础 URL。
OMNIROUTE_KEY	（未设置）	scripts/ad-hoc/regen-opencode-config.ts	用于向 OmniRoute /v1/models 端点进行身份验证的 API 密钥。未设置时回退到 OPENCODE_API_KEY。
OPENCODE_API_KEY	（未设置）	scripts/ad-hoc/regen-opencode-config.ts	写入重新生成的 opencode.json 中的 OpenCode 风格 API 密钥（sk-...）。未设置时回退到 OMNIROUTE_KEY。

压缩离线评估工具（临时工具）

供离线压缩评估 CLI scripts/compression-eval/index.ts 使用。 正常运行不需要——仅供开发者使用。

变量	默认值	源文件	说明
OMNIROUTE_EVAL_CREDENTIALS	{}（空）	scripts/compression-eval/index.ts	由操作人员提供的 JSON 凭据，用于离线压缩评估 CLI 所测试的提供者（使用 JSON.parse 解析）。如需空运行，请保持未设置。

VNC 浏览器会话

由 src/lib/vncSession/manifest.ts 使用，用于为浏览器自动化提供者配置基于 Docker 的无头 Chromium 会话。所有变量均为可选——默认值如下所示。

变量	默认值	源文件	说明
OMNIROUTE_DOCKER_BIN	docker	src/lib/vncSession/manifest.ts	用于启动 VNC 容器的 Docker 二进制文件路径。
OMNIROUTE_VNC_IMAGE	omniroute-vnc-chromium:local	src/lib/vncSession/manifest.ts	VNC Chromium 容器使用的 Docker 镜像。
OMNIROUTE_VNC_CHROMIUM_ARGS	（内置标志）	src/lib/vncSession/manifest.ts	传递给容器内浏览器的额外 Chromium CLI 参数。
OMNIROUTE_VNC_CONTAINER_VNC_PORT	3000	src/lib/vncSession/manifest.ts	容器内的 VNC 端口。
OMNIROUTE_VNC_CONTAINER_CDP_PORT	9223	src/lib/vncSession/manifest.ts	容器内的 Chrome DevTools Protocol 端口。
OMNIROUTE_VNC_CONTAINER_PROFILE_DIR	/config	src/lib/vncSession/manifest.ts	容器内的配置文件目录。
OMNIROUTE_VNC_PROFILE_DIR	（未设置）	src/lib/vncSession/manifest.ts	用于持久保存浏览器配置文件的主机端目录。
OMNIROUTE_VNC_IDLE_MS	600000	src/lib/vncSession/manifest.ts	回收 VNC 会话前的空闲超时时间（毫秒）。
OMNIROUTE_VNC_MAX_MS	1800000	src/lib/vncSession/manifest.ts	最大会话持续时间（毫秒）。
OMNIROUTE_VNC_MAX_SESSIONS	4	src/lib/vncSession/manifest.ts	VNC 会话的最大并发数。
OMNIROUTE_VNC_READY_MS	45000	src/lib/vncSession/manifest.ts	浏览器就绪超时时间（毫秒）。
OMNIROUTE_VNC_HARVEST_MS	20000	src/lib/vncSession/manifest.ts	回收/清理超时时间（毫秒）。
OMNIROUTE_VNC_NETWORK	omniroute-vnc-browser-login	src/lib/vncSession/manifest.ts	容器加入的专用 Docker 网络（#12571），不使用默认网桥。
VIBEPROXY_DATA_DIR	（未设置）	open-sse/services/notionThreadSessions.ts	用于持久保存 Notion 线程会话的目录。

内部服务身份验证

变量	默认值	说明
OMNIROUTE_INTERNAL_SERVICE_TOKEN	–	用于管理平面服务间身份验证的内联令牌。
OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE	–	包含内部服务令牌的文件路径（在容器中首选；会覆盖内联变量）。

OpenRouter 提供者统计信息

变量	默认值	说明
OPENROUTER_PROVIDER_STATS_ENABLED	true	设置为 false 可跳过获取用于扩充目录信息的 OpenRouter 各提供者统计数据。
OPENROUTER_PROVIDER_STATS_TTL_MS	3600000	已获取的 OpenRouter 提供者统计数据的缓存 TTL（毫秒）。

嵌入式 Redis 绑定

变量	默认值	描述
REDIS_BIND_HOST	127.0.0.1	嵌入式 Redis 服务的绑定地址。
REDIS_PORT	6379	嵌入式 Redis 服务的端口。
OMNIROUTE_REDIS_BIND_HOST	–	OmniRoute 范围内对嵌入式 Redis 绑定地址的覆盖设置。

---

24. v3.8.50 版本新增内容

这些设置是在上一次环境契约快照之后引入的。

变量	默认值	源文件	描述
OMNIROUTE_CHAT_ADMISSION_QUEUE_MS	2000	src/shared/middleware/chatBodyAdmission.ts	重量级聊天准入槽位的最长等待时间，超时后返回可重试的 503；短暂且有界的等待会将代理突发请求串行化，而不是立即返回 503。设置为 0 可恢复立即拒绝。
OMNIROUTE_CHAT_ADMISSION_MAX_QUEUED_BYTES	4194304 (4 MB)	src/shared/middleware/chatBodyAdmission.ts	准入等待的排队字节预算：限制进程范围内暂存的请求体缓冲总字节数，避免等待机制放大堆内存占用（#4380）。超出预算的等待请求会立即收到可重试的 503。
OMNIROUTE_CHAT_VIRTUAL_TTL_MS	60000 (60 s)	src/shared/middleware/chatBodyAdmission.ts	自 #10110 起已弃用且不执行任何操作：每会话准入通道已移除，改为使用单个进程范围预算。出于配置兼容性考虑仍接受此设置，但会忽略。
OMNIROUTE_CHAT_VIRTUAL_MAX_SESSIONS	64	src/shared/middleware/chatBodyAdmission.ts	自 #10110 起已弃用且不执行任何操作：每会话准入通道已移除，改为使用单个进程范围预算。出于配置兼容性考虑仍接受此设置，但会忽略。
OMNIROUTE_CHAT_VIRTUAL_LANES	0（关闭）	open-sse/services/admission/runtime.ts	自适应运行时虚拟准入通道（#9654）：每租户自适应门控（系统 2）的总开关。不同于上方已弃用的每连接通道变量（TTL_MS / MAX_SESSIONS，自 #10110 起不执行任何操作）。仪表板中有同名功能标志；环境变量优先于仪表板覆盖值；需要重启。
OMNIROUTE_RUNNOW_TIMEOUT_MS	30000	src/app/api/jobs/[id]/run-now/route.ts	限制立即运行调用在启动排队运行之前等待进行中作业的最长时间。
ADOBE_FIREFLY_BROWSER_REFRESH	已启用	open-sse/services/adobeFireflySession.ts	通过账户范围的 Chrome CDP 会话保持 IMS 和浏览器风险状态为最新；设置为 0 可禁用。
ADOBE_FIREFLY_SESSION_DISK	已启用	open-sse/services/adobeFireflySession.ts	将修复后的 Adobe 会话持久化到 DATA_DIR 下；设置为 0 可仅保存在内存中。
ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS	12000	open-sse/services/adobeFireflySession.ts	Adobe Firefly 生成请求提交之间的最短间隔。
ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS	15000	open-sse/services/adobeFireflySession.ts	每成功提交三次 Adobe 请求后的额外静默期。
ADOBE_FIREFLY_CHROME_HEADLESS	0	open-sse/services/adobeFireflyBrowserLogin.ts	仅用于调试的真正无头模式；Adobe colligo 通常会拒绝由此产生的风险会话。
CHROME_PATH	自动检测	open-sse/executors/cloudflare-playground.ts, open-sse/executors/chatgpt-web-codex.ts	可选的 Chrome 可执行文件绝对路径，供浏览器驱动的执行器在平台自动检测不足时使用。
TELEGRAM_BOT_TOKEN	（未设置）	src/lib/telegram/config.ts	用于启用入站 webhook 并为 Mini App initData 签名的 BotFather 令牌。
TELEGRAM_WEBHOOK_SECRET	（未设置）	src/lib/telegram/config.ts	通过 setWebhook 注册的共享密钥，并在每次 webhook 投递时根据 X-Telegram-Bot-Api-Secret-Token 标头进行验证。webhook 路径必须配置此项；未设置时，webhook 投递将被拒绝并返回 503。
TELEGRAM_DEFAULT_MODEL	auto/chat	src/lib/telegram/chatProxy.ts	用于 Telegram 聊天回复的模型。
TELEGRAM_BOT_API_BASE	https://api.telegram.org	src/lib/telegram/config.ts	用于代理或自托管 Bot API 服务器的 Bot API 基础 URL 覆盖值。
TELEGRAM_WEBHOOK_TIMEOUT_MS	60000	src/lib/telegram/config.ts	出站 Bot API 调用的超时时间，以毫秒为单位。
OMNIROUTE_OPTIONAL_PACK_TAR	1（已启用）	scripts/build/optionalPackStaging.mjs	设置为 0 可在为 Electron 独立运行目录暂存可选 ML/浏览器包时跳过生成 .tar.gz 归档文件（仍会生成包目录和 optional-packs.index.json）。桌面版发布工作流使用此设置来减小工件上传大小。

ChatGPT Web (Codex)

无头浏览器和出站工具隧道的全局默认值。在仪表板中设置的连接值优先。

变量	默认值	源文件	描述
CHATGPT_WEB_CODEX_CHROME_PATH	（自动检测）	open-sse/executors/chatgpt-web-codex.ts	用于 npm、systemd 和 PM2 运行模式的显式 Chrome/Chromium 路径。
CHROME_PATH	（自动检测）	open-sse/executors/chatgpt-web-codex.ts	显式 Chrome/Chromium 路径的通用回退设置。
CHATGPT_WEB_CODEX_CDP_URL	（未设置）	open-sse/executors/chatgpt-web-codex.ts	内部 CDP 端点；Docker 使用端口 9223 上的 Sidecar。
CDP_PROXY_TOKEN	（未设置）	docker/chatgpt-web-codex-browser/cdp-proxy.mjs	设置后，对 CDP 代理 Sidecar 的每个请求都必须在请求头 X-Omni-Cdp-Token 中携带此值（#13679）。未设置值时，代理将以未经身份验证的方式转发——此时仅由 Compose 网络 chatgpt-web-codex-net 的网络隔离提供保护。可使用 openssl rand -hex 32 生成。
CHATGPT_WEB_CODEX_TUNNEL_ID	（未设置）	open-sse/executors/chatgpt-web-codex.ts	用于本地 Codex 工具轮次的全局 OpenAI 隧道 ID。
CHATGPT_WEB_CODEX_RUNTIME_KEY	（未设置）	open-sse/executors/chatgpt-web-codex.ts	全局隧道运行时密钥；切勿输出到日志中。
CHATGPT_WEB_CODEX_CONNECTOR_NAME	OmniRoute Codex v2	open-sse/executors/chatgpt-web-codex.ts	为 MCP 桥接新建的 ChatGPT 自定义连接器的确切名称。
CODEX_CHATGPT_WEB_HOME	<DATA_DIR>/chatgpt-web-codex	open-sse/vendor/codex-chatgpt-web/config.ts	用于浏览器、Broker 和隧道状态的专用目录。
CODEX_CHATGPT_WEB_BROWSER_DIAGNOSTICS	0	open-sse/vendor/codex-chatgpt-web/adapters/chatgpt-web/browser-worker.ts	设置为 1 时，将在每个检查点捕获浏览器诊断图像。
CODEX_CHATGPT_WEB_LAUNCHER	（未设置）	open-sse/vendor/codex-chatgpt-web/config.ts	指向持久化 Launcher 二进制文件的可选绝对路径。
CODEX_CHATGPT_WEB_BUN	（自动检测）	open-sse/vendor/codex-chatgpt-web/config.ts	指向 Bun 运行时二进制文件的可选绝对路径。
CODEX_WEB_GPT_BUN	（未设置）	open-sse/vendor/codex-chatgpt-web/config.ts	CODEX_CHATGPT_WEB_BUN 的旧版回退设置；新部署使用规范名称。

---

OmniConductor 桥接器

长时间运行的 SSE 消费端，用于将 OmniConductor 中枢任务镜像到本地 A2A TaskManager（src/lib/conductor/）。需选择启用——仅当设置 CONDUCTOR_HUB_URL 时，桥接器才会启动。仅限服务器端：中枢令牌绝不能传到浏览器。

变量	默认值	源文件	描述
CONDUCTOR_HUB_URL	（空）	src/lib/conductor/boot.ts	OmniConductor 中枢的基础 URL（例如 http://127.0.0.1:7910）。未设置 = 禁用桥接器。
CONDUCTOR_HUB_TOKEN	（空）	src/lib/conductor/boot.ts	SSE 订阅源的中枢凭据——在中枢上创建一个 spokesperson 类型的对等方（POST /v1/peers，需管理员权限）。
CONDUCTOR_ORCHESTRATOR_TOKEN	（空）	src/lib/conductor/hubProxy.ts	用于传入的 A2A→中枢任务委派（POST /v1/tasks）的凭据；未设置时回退使用 CONDUCTOR_HUB_TOKEN。
CONDUCTOR_SPOKESPERSON_URL	http://127.0.0.1:7920	src/lib/conductor/faroProxy.ts	仪表板聊天代理（/api/conductor/ask）后端的 spokesperson（Faro）服务基础 URL。

配额感知调度

由 open-sse/services/combo.ts 和 src/lib/quota/quotaScheduler.ts 用于请求前的令牌预算检查。需选择启用——未设置时，默认路由行为保持不变。

变量	默认值	源文件	描述
OMNIROUTE_QUOTA_AWARE_ROUTING	0	open-sse/services/combo.ts	设置为 1 时，在分派前跳过其每个时间窗口的令牌预算（rateLimitOverrides.tpm，表 provider_quota_state）不足以承担预估请求成本的连接。未配置预算时采用开放式失败策略。

---

OmniRoute 源码 (a58000c7685f)