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 之一。
• 設置歸屬: 非用戶設置項