Minara 核心

MINARA_API_KEY

Minara 后端 API 凭据。

• 作用: agent 向 Minara REST 接口（portfolio、swap、perps、autopilot、workflow、analytics）发起的每一次调用。
• 消费方: src/minara/client.ts、src/minara/read-client.ts、src/minara/safe-trading-client.ts，经由 src/app.ts。
• 何时设置: 在无 device-flow JWT 可用的非交互式环境（CI、Docker、workflow 引擎）中运行时。
• 未设置时: gateway 会在 $MINARA_DATA_DIR/credentials.json（llm slot）查找已保存的 device-flow JWT（请先运行 minara auth login minara）。若两者都不存在，agent 拒绝 Minara 调用。
• 格式: Minara 控制台颁发的不透明字符串。
• 设置归属: 非用户设置项

MINARA_BASE_URL

Minara API base URL 覆盖。

• 作用: 每个 Minara HTTP 客户端指向的 origin，包括 OAuth /v1/oauth/authorize 的重定向目标（后者又会把用户交给同品牌的授权页 —— 指向 dev 后端，用户就会看到 dev 授权 UI）。
• 消费方: apps/agent/src/gateway/server.ts、apps/agent/src/gateway/auth-cli.ts、apps/agent/src/minara/client.ts、apps/agent/src/app.ts。
• 何时设置: 你指向自托管实例、staging 后端或本地 mock（见 apps/agent/tests/fakes/mock-minara-server.ts）时。
• 未设置时: 默认为 prod origin https://api.minara.ai（与 CLI 的 DEFAULT_MINARA_BASE_URL 常量一致）。
• 格式: 绝对 URL，无尾部斜杠。
• 设置归属: 非用户设置项

MINARA_FRONTEND_BASE_URL

Minara web 前端 base URL。

• 作用: token:// / address:// 自定义 URI scheme
• 在终端 OSC 8 超链接和 deep-research
• HTML 报告中解析到的 URL，以及桌面端 OAuth 成功页面
• /oauth/desktop/success 的地址；也将供即将到来的
• minara_open_pricing_page / _topup_page / _subscription_page 工具使用。
• 消费方: apps/agent/src/config/frontend-url.ts（由 apps/agent/src/gateway/api.ts、apps/agent/src/gateway/render/uri-rewrite.ts 和 apps/agent/src/deep-research/report-renderer.ts 读取）。
• 何时设置: 发布到 prod（https://minara.ai）或对本地 Next.js dev server 运行时。
• 未设置时: 默认为 https://minara.ai。
• 格式: 绝对 URL，无尾部斜杠。
• 设置归属: 非用户设置项

MINARA_DATA_DIR

持久化状态目录。

• 作用: SQLite 数据库、沙箱文件牢笼、auth profile、审计日志和生成的文档所在位置。
• 消费方: apps/agent/src/gateway/cli.ts、apps/agent/src/app.ts、apps/agent/src/tools/_shared/sandbox.ts。
• 何时设置: 在 Docker / systemd 下运行、~ 映射到非持久路径，或你想并排保留多个 agent profile 时。
• 未设置时: 默认为 ~/.minara。
• 格式: 绝对文件系统路径。缺失时于首次启动时创建。
• 设置归属: 非用户设置项

MINARA_TERMINAL_CWD

agent 工作目录覆盖。

• 作用: agent 读写用户文件、运行 shell 命令所在的 cwd。解析顺序：会话级覆盖（运行时由 /cwd 设置）→ 本变量 → process.cwd()。
• 消费方: apps/agent/src/agent/runtime-cwd.ts（resolveAgentCwd）。
• 何时设置: gateway/cron 入口的启动目录是安装目录、而非目标工作目录时。本地 CLI 通常不设置它，回退到 shell cwd。
• 未设置时: 回退到 process.cwd()（agent 进程的启动目录）。
• 格式: 指向真实目录的绝对路径。不存在的路径会被忽略，解析继续回退到 process.cwd()。
• 设置归属: 非用户设置项

MINARA_BACKGROUND_MODELS_ENABLED

MINARA_BACKGROUND_MODELS_ENABLED：后台任务模型的默认状态。

• 作用: 标题、压缩和无人值守工作是否使用设置里指定的模型。无论开关如何，聊天都继续使用已选模型。
• 消费方: apps/agent/src/config/preferences/schema.ts 与 apps/agent/src/llm/model-routing-service.ts。
• 何时设置: 部署管理员希望默认开启或关闭后台任务模型时。用户保存的设置优先。
• 未设置时: 默认开启。只有当前服务商为 Minara 时才会实际生效。
• 格式: 布尔值。真值接受 1、true、yes、on；假值接受 0、false、no、off。
• 设置归属: 设置 → 偏好（schema 键）

MINARA_FINANCIAL_SAFETY_ENABLED

MINARA_FINANCIAL_SAFETY_ENABLED：财务安全提醒的默认状态。

• 作用: 用户主动发起的 Chat Agent Loop 是否注册财务安全技能，用于处理高风险消费、交易升级、诈骗、胁迫和人身安全危机信号。后台自动化和 Subagent 始终不会注入该技能。
• 消费方: apps/agent/src/config/preferences/schema.ts、apps/agent/src/guardrail/service.ts 与 apps/agent/src/app.ts。
• 何时设置: 部署需要默认关闭财务安全时设为 false。用户在个性化中保存的选择优先。
• 未设置时: 默认开启。用户可在个性化 → 财务安全中关闭。
• 格式: 布尔值。真值接受 1、true、yes、on；假值接受 0、false、no、off。
• 设置归属: 设置 → 偏好（schema 键）

MINARA_AUTO_MODEL_STRATEGY

MINARA_AUTO_MODEL_STRATEGY：对话 Auto 的默认映射。

• 作用: 选了 Auto 时，如何把这条消息的分档映射到固定的 Minara 目录模型。SIMPLE/MEDIUM 用 DeepSeek V4 Flash 0731（需要视觉/PDF 时用 Sonnet 5）；economy 的 COMPLEX 用 GLM 5.2、REASONING 用 Kimi K3；balanced 的 COMPLEX 用 GPT-5.6 Terra、REASONING 用 GPT-5.6 Sol；quality 的 SIMPLE/MEDIUM 用 Sonnet 5、COMPLEX 用 GPT-5.6 Sol、REASONING 用 Opus 5。custom 默认沿用 quality，再保存用户的覆盖配置。这不会改后台任务模型。
• 消费方: apps/agent/src/config/preferences/schema.ts 与 apps/agent/src/llm/auto-model.ts。
• 何时设置: 部署希望 Auto 默认更省或更强时。用户保存的设置优先。只有选中 Auto 后才会出现这一行。
• 未设置时: 默认为 balanced。
• 格式: economy、balanced、quality 或 custom。custom 从 quality 开始，并把覆盖配置保存在设置中。
• 设置归属: 设置 → 偏好（schema 键）

MINARA_DEFAULT_MODEL

agent 初始模型 id。

• 作用: 交互式聊天使用的默认模型 id。开启后台任务模型后，标题、压缩和无人值守工作可以使用设置里指定的模型，聊天仍保留此模型。
• 消费方: apps/agent/src/app.ts（createApp 模型解析链）。
• 何时设置: 当持久化在 ~/.minara/settings.json 中的模型 pin 对当前生效的提供商不正确时 —— 例如只配置了 OPENROUTER_API_KEY，但持久化的 id 是 Anthropic 原生的 claude-sonnet-4-6，而 OpenRouter 会以 400 拒绝它（其命名为 anthropic/claude-sonnet-4.5）。web UI 的 Settings → Model 选择器是长期方案；这个 env 旋钮是进程生命周期内的覆盖。
• 未设置时: 回退到持久化的 defaultModel.model，然后回退到硬编码的 claude-sonnet-4-6。
• 格式: 模型 id 字符串。OpenRouter 用带前缀的名称（anthropic/claude-sonnet-4.5、openai/gpt-5、google/gemini-2.5-pro 等）。Anthropic 原生用裸 id（claude-sonnet-4-6、claude-opus-4-7、claude-haiku-4-5-20251001）。解析顺序（第一个非空者胜出）：config.model（编程式）> MINARA_DEFAULT_MODEL（本变量）> 持久化选择 > 硬编码默认值。
• 设置归属: 非用户设置项

AGENT_MAX_ITERATIONS

每轮工具调用循环的最大迭代次数。

• 作用: agent 循环在抛出 MaxIterationsError 之前运行多少次 LLM→工具→LLM 周期的上限。作用于三阶段循环的 Phase 2（数据收集）部分。
• 消费方: src/app.ts → AgentConfig.maxIterations。
• 何时设置: 你想更严格地控制成本（调低），或复杂的多工具查询需要更多迭代（调高）时。
• 未设置时: 默认为 30。
• 格式: 正整数。
• 设置归属: 非用户设置项

AGENT_MAX_TOKENS

为 agent 循环工具调用周期内的每一次 LLM 调用固定 max_tokens 上限。可选覆盖。

• 作用: 设置后，该值会原样作为 max_tokens 参数转发给每一次 messages.create 调用。未设置时，agent 在 src/llm/model-output-limits.ts 里按三段顺序从当前生效的模型本身推导上限：先读 live provider listing（Anthropic /v1/models 的 max_tokens），再读 OpenRouter 目录发布的上限，两者都查不到才落到 32K 兜底值并打出带模型名的告警。模型推导路径是默认且推荐的姿态："不设人为上限"，好让长篇机构报告 / deep-research 表格 / 聊天摘要不被截断地完成。真的撞到上限时，该 turn 现在会显式失败，而不是把截断的半截回答当成功返回。
• 消费方: src/app.ts → AgentLoop.maxTokens。
• 何时设置: 仅当你想要与模型原生上限不同的值时 —— 对简单查询严格控制成本，或固定到较小值以获得可预测的每轮计费。
• 未设置时: agent 使用模型的完整输出窗口（推荐）。
• 格式: 正整数。
• 设置归属: 非用户设置项

GATEWAY_HOST

HTTP gateway 绑定的网络接口。

• 作用: npm run serve（src/gateway/server.ts）绑定的网络接口。127.0.0.1 / localhost = 仅本地；0.0.0.0 = 所有接口（本机之外可达）。
• 消费方: src/gateway/serve-cli.ts（decideBind 守卫）。
• 何时设置: 把 gateway 暴露到 localhost 之外时（LAN 主机、Docker 网桥）。非 loopback 绑定必须鉴权 —— 要么设置 GATEWAY_AUTH_TOKEN，要么 gateway 在非交互式环境中自动生成一个，并在交互式环境中拒绝启动。
• 未设置时: 默认为 127.0.0.1（仅本地）。
• 格式: 要绑定的 IP 或主机名。
• 设置归属: 非用户设置项

GATEWAY_PORT

HTTP gateway 端口。

• 作用: npm run serve（src/gateway/server.ts）为 REST/SSE API 绑定的端口。
• 消费方: src/gateway/server.ts。
• 何时设置: 在交互式 REPL 之外 —— 或替代它 —— 运行 HTTP gateway 时。npm run dev 会忽略。
• 未设置时: 默认为 8080。
• 格式: 1-65535 的整数。
• 设置归属: 非用户设置项

GATEWAY_AUTH_TOKEN

HTTP gateway bearer token。

• 作用: 对 HTTP gateway 的每一个入站请求要求 Authorization: Bearer <token>。
• 消费方: src/gateway/server.ts（经由 src/gateway/api.ts）。
• 何时设置: 在任何网络接口上暴露 gateway 时。token 以常数时间相等性比较。
• 未设置且绑定 loopback（127.0.0.1）时：鉴权被禁用，每个请求都被接受 —— 之所以安全，只因本机之外无法触达它。未设置且绑定非 loopback 接口时，gateway 在非交互式环境（Docker/CI，写入 <dataDir>/gateway-token）自动生成 token，或在交互式环境拒绝启动。设置 MINARA_ALLOW_INSECURE_BIND=1 可强制无鉴权的公开绑定（不推荐）。
• 格式: 不透明的高熵字符串。用 openssl rand -hex 32 生成。
• 设置归属: 非用户设置项

GATEWAY_CORS_ORIGINS

浏览器跨域 origin 白名单。

• 作用: 浏览器可以跨域读取的 web origin（Access-Control-Allow-Origin 响应头 + OPTIONS 预检）。非浏览器调用方（curl、桌面外壳、其它服务器）用 bearer token 鉴权，不受影响。
• 消费方: src/gateway/serve-cli.ts（resolveCorsOrigins），经由 src/gateway/api.ts。
• 何时设置: 在非 loopback 绑定上从与 gateway 不同的 origin 提供 web UI 时 —— 例如 UI 在 https://app.example.com 调用位于 https://api.example.com 的 gateway。列出每一个浏览器 origin。
• 未设置时: loopback 绑定允许所有 origin（*，本地开发不变）；非 loopback 绑定默认拒绝所有跨域浏览器读取 —— 同源 UI（WEB_UI_DIST_DIR）和用 token 鉴权的 API 客户端仍可正常工作。
• 格式: 逗号分隔的 origin（scheme://host[:port]），或 * 表示任意。
• 设置归属: 非用户设置项

MINARA_ALLOW_INSECURE_BIND

绕过安全绑定守卫。

• 作用: 设置后，gateway 会在非 loopback 接口上无鉴权提供服务，而不是拒绝启动 / 自动生成 token。每一个请求 —— 包括资金流转端点 —— 都会被任何能触达该端口的人接受。
• 消费方: src/gateway/bind-security.ts（isInsecureBindAllowed）。
• 何时设置: 在你愿意承担风险的、完全可信且有防火墙的单主机网络上作为最后手段。切勿用于公网或共享网络。
• 未设置时: 安全绑定守卫处于激活状态（默认，推荐）。
• 格式: 1/true/yes/on 启用。
• 设置归属: 非用户设置项

WEB_UI_DIST_DIR

同源 web-ui 静态根目录。

• 作用: 设置为已构建的 web-ui dist/ 目录时，HTTP gateway 会在与 API 相同的 origin 上于 / 提供该 SPA（资源 + 客户端导航回退到 index.html）—— 因此桌面外壳或单 origin 部署无需单独的静态主机，也无需 CORS。API（/v1/*）仍受 bearer 门控；只有静态外壳和 /assets/* 是公开的。
• 消费方: src/gateway/static-spa.ts（经由 src/gateway/api.ts）。
• 何时设置: 打包桌面应用，或在一个端口上同时提供 UI + API 时。
• 未设置时: 不提供静态 UI —— gateway 表现为纯 API 服务器（Docker / CLI 的默认）。
• 格式: 指向包含 index.html 的现有目录的绝对路径。
• 设置归属: 非用户设置项

WEBHOOK_PORT

webhook gateway 端口。

• 作用: 可选的 webhook 监听器为入站事件（TradingView alert、Minara push 事件、喂给 src/workflow/triggers.ts 的价格提醒触发）绑定的端口。
• 消费方: src/gateway/server.ts。
• 何时设置: 你把外部 webhook 源接入 workflow 引擎时。必须与 GATEWAY_PORT 不同。
• 未设置时: 不启动 webhook 监听器 —— 只有计划中的 cron 触发会发起自主轮次。
• 格式: 1-65535 的整数。
• 设置归属: 非用户设置项

FILES_URL_BASE

沙箱文件下载的 URL 前缀。

• 作用: agent 向客户端返回文件时，把本地沙箱路径改写成的公开前缀。
• 消费方: src/app.ts。
• 何时设置: HTTP gateway 部署在反向代理之后、调用方需要绝对 URL（https://agent.example.com/v1/files）时。
• 未设置时: 默认为相对路径 /v1/files。
• 格式: 绝对 URL 或相对路径前缀，无尾部斜杠。
• 设置归属: 非用户设置项

OFFLINE_MODE

出站 HTTP 总开关。

• 作用: 经 src/tools/_shared/fetch-timeout.ts 的每一次出站 fetch 都以 blocked 错误短路。所有工具的网络调用都被拒绝。
• 消费方: src/tools/_shared/fetch-timeout.ts。
• 何时设置: 运行确定性测试或气隙演示、任何出站调用都会是 bug 时。
• 未设置时: 网络调用正常工作。
• 格式: 1 / true / yes / on 启用。其他任何值 = 关闭。
• 设置归属: 设置 → 偏好（schema 键）

HTTPS_PROXY / HTTP_PROXY / ALL_PROXY / NO_PROXY

出站代理。

• 作用: Minara 自有传输使用的正向代理：模型调用、行情与数据源请求、MCP 服务器和无头浏览器。在设置 > 偏好设置 > 安全 > 向本地命令传递代理设置开启时，python / node / shell 子进程也会收到代理环境变量。按 HTTPS_PROXY、HTTP_PROXY、ALL_PROXY 的顺序检查，第一个设了的生效；大写和小写变量名都会读。
• 消费方: src/config/egress/resolve.ts，它在启动时解析一次环境变量，然后交给每种传输各自的适配器。Desktop 只能在运行时替换由它管理的系统代理路由；除此之外没有别处读这些变量。
• 何时设置: 本机只能经由代理访问外网时。Minara Desktop 会自动探测并注入系统代理；系统 HTTP 代理和 PAC 变化无需重启，会应用到新请求、重连、新启动的浏览器和子进程。手工设置这些环境变量是给 CLI、gateway 和 Docker 用的，仍属于启动时配置，修改后需要重启。
• 未设置时: Minara 自有连接直连出网。Minara 不会向子进程传递代理变量，但 TUN 模式等系统级网络转发仍可能承载这些流量。
• 格式: http:// 或 https:// URL，可以带凭证（http://user:pass@proxy:3128）。SOCKS URL 会被记录一条日志后忽略——代理必须支持 HTTP CONNECT。NO_PROXY 是逗号分隔的主机列表（CIDR 网段对子进程和浏览器有效，对 agent 进程本身无效）；无论是否列出，回环地址和私有网段始终绕过代理。
• Note: 启用子进程代理继承时，带凭证的 URL 对模型编写的本地代码可见；发生时 Minara 每个进程警告一次。关闭上面的安全偏好可停止环境变量传递，但不会隔离子进程的直连或 TUN 转发网络。
• 设置归属: 非用户设置项

CLOUD_SYNC_AUTO

在后台与 Minara 账号同步。

• 作用: 本机是否在无人操作时自动与 Minara 账号互相同步，大约每五分钟一次。手动同步始终可用，不受此项影响；这个开关只管你没有主动触发的那些同步。
• 消费方: 运行时 Preferences 中的 cloudSync.auto 和 src/app/sync.ts。同步哪些数据由 CLOUD_SYNC_CHAT 和 CLOUD_SYNC_PERSONALIZATION 分别决定。
• 何时设置: 你在多台设备上使用 Minara，希望它们自动保持一致。
• 未设置时: 在有人手动同步之前不上传任何内容。对话里含本地路径和私密上下文，因此后台同步默认关闭。
• 格式: 1 / true / yes / on 启用。其他任何值 = 关闭。
• 设置归属: 设置 → 偏好（schema 键）

CLOUD_SYNC_CHAT

同步内容中是否包含对话。

• 作用: 对话是否纳入同步范围。只发送你和助手说的话 —— 工具调用、工具结果和思考过程都留在本机。
• 消费方: 运行时 Preferences 中的 cloudSync.chat。
• 何时设置: 设为 false 可以保留其他数据的同步，同时把对话文本留在本机。
• 未设置时: 包含对话，但仅当本机进行同步时才实际生效。
• 格式: 0 / false / no / off 表示排除。其他任何值 = 包含。
• 设置归属: 设置 → 偏好（schema 键）

CLOUD_SYNC_PERSONALIZATION

同步内容中是否包含 Minara 记住的事。

• 作用: Minara 记住的那些简短事实是否纳入同步范围。它们是单句描述，不是完整对话。
• 消费方: 运行时 Preferences 中的 cloudSync.personalization。
• 何时设置: 设为 false 可以只同步对话，不共享推导出来的记录。
• 未设置时: 包含这些记录，但仅当本机进行同步时才实际生效。
• 格式: 0 / false / no / off 表示排除。其他任何值 = 包含。
• 设置归属: 设置 → 偏好（schema 键）

CLOUD_SYNC_USER_TAGS

同步内容中是否包含你的投资偏好答案。

• 作用: 你关于自己的那些维度答案（风险偏好、持有周期、关注市场等）是否纳入同步范围。
• 消费方: 运行时 Preferences 中的 cloudSync.user-tags。
• 何时设置: 设为 false 可以把这些答案留在本机，同时继续同步其他数据。
• 未设置时: 包含这些答案，但仅当本机进行同步时才实际生效。
• 格式: 0 / false / no / off 表示排除。其他任何值 = 包含。
• 设置归属: 设置 → 偏好（schema 键）

CLOUD_SYNC_PROFILE

同步内容中是否包含你的自定义设置与自选列表。

• 作用: 你自己设定的那些设置是否随同步走 —— 自定义指令、允许 Minara 带入回答的内容、你关注的钱包、以及自选列表。Minara 根据你的交易推导出来的摘要留在生成它的那台设备上。
• 消费方: 运行时 Preferences 中的 cloudSync.profile。
• 何时设置: 设为 false 可以让这些设置按设备各自保留。
• 未设置时: 包含这些设置，但仅当本机进行同步时才实际生效。
• 格式: 0 / false / no / off 表示排除。其他任何值 = 包含。
• 设置归属: 设置 → 偏好（schema 键）

CLOUD_SYNC_WORKFLOW

同步内容中是否包含自动化和云端工作流。

• 作用: 自动化和云端工作流是否纳入同步范围。第一次可能较久。两边实现不同，有的在这边打不开 —— 那些会留在账号上，并显示为这台设备打不开的条目，而不是同步失败。
• 消费方: 运行时 Preferences 中的 cloudSync.workflow。
• 何时设置: 设为 true 可在同步对话和记忆的同时带上自动化。
• 未设置时: 自动化默认不同步，直到在同步设置里打开。在本机重建云端工作流需要主动选择。
• 格式: 1 / true / yes / on 启用。其他任何值 = 关闭。
• 设置归属: 设置 → 偏好（schema 键）

LOG_LEVEL

logger 详细程度。

• 作用: src/core/logger.ts 输出的最低级别。低于此级别的消息被丢弃。
• 消费方: src/core/logger.ts。
• 何时设置: 开发新工具 / skill 时用 debug，安静的生产部署用 warn 或 error。
• 未设置时: 默认为 warn。
• 格式: debug | info | warn | error 之一。
• 设置归属: 非用户设置项