環境變量

本頁介紹 minara-agent-v2 加載環境變量的約定，以及引入新變量所需的步驟。每個變量的詳細參考（包括默認值、格式、使用方文件，以及未設置時的影響），請參閱 參考 → 環境變量。

標準模板位於項目根目錄的 .env.example。請保持該文件與兩個頁面同步。

MINARA_ 前綴專用於 Minara 平臺專屬變量 （MINARA_API_KEY、MINARA_BASE_URL、MINARA_SKIP_FUND_CONFIRM、 MINARA_DATA_DIR、MINARA_OPENAI_BASE_URL、 MINARA_OPENAI_CHAT_PATH）。Agent 循環基礎設施變量（網關、日誌、 模型、場景、記憶配置）不使用該前綴。

用戶可見開關寫入 Settings（settings.json#preferences）。密鑰寫入 credentials.json（設定 → API Keys / 訊息）。呼叫端讀 prefs.get / secrets.* / infra.get。Env 是啟動時的維運層，以及覆蓋鏈上的文件化回退。

TL;DR 約定

任何需要 API 密鑰、secret、token 或可覆蓋 URL 的新技能或工具，必須：

1. 寫入正確的存儲，再透過 façade 讀取。 密鑰走 API-key / messaging 登錄表和 secrets.dataSource / secrets.messaging。用戶開關走 preferences schema 和 prefs.get。維運基礎設施（GATEWAY_PORT、MINARA_DATA_DIR）走 config/infra/schema.ts 和 infra.get。嚴禁硬編碼密鑰；嚴禁通過 CLI 參數傳入並回顯。

2. 在同一次提交中，將有詳細說明的條目追加到 apps/agent/src/config/env-docs/，再生成 .env.example。 條目須說明：控制的內容、消費它的技能/工具、運營商何時需設置、未設置時的默認行為，以及可接受的值格式。僅有一行存根（# FOO_KEY=）的條目會被拒絕。

3. 對於領域技能（apps/agent/src/skills/builtin/*.ts 或 apps/agent/src/skills/external/<id>/），在 requires_env 中聲明該變量，以便 SkillRegistry 在憑據缺失時完全隱藏該技能：

   export const myNewSkill: DomainSkill = {
     id: "research.my_provider",
     // ...
     requires_env: ["MY_PROVIDER_API_KEY"],
   };

4. 對於工具（apps/agent/src/tools/*.ts），當密鑰缺失時，工廠函數應返回空的 ToolEntry[]。工具註冊表會靜默排除未註冊的名稱，因此下游技能中的 tool_names 引用會優雅降級：

   export function createMyProviderTools(): ToolEntry[] {
     const apiKey = secrets.dataSource("MY_PROVIDER_API_KEY");
     if (!apiKey) return [];
     // ...
   }

5. 嚴禁提交真實密鑰。 .env 已加入 .gitignore；.env.example 是已提交的模板，值留空。

.env 加載方式

加載由 apps/agent/src/config/load-env.ts 處理。這是一個副作用模塊，調用 Node 22 內置的 process.loadEnvFile(".env")。它作為每個入口的第一行被導入：

• apps/agent/src/gateway/cli.ts：REPL 模式
• apps/agent/src/gateway/server.ts：HTTP 模式

ESM 求值順序保證加載器在任何在導入時讀取 process.env.<NAME> 的下游模塊之前運行。

優先級：已由 shell / CI / systemd 導出的變量優先於 .env 中的值。加載器不會覆蓋已有的 key。這與 Node 的默認行為一致，也是最安全的規則（不會意外遮蔽 CI 注入的密鑰）。

無 dotenv 依賴。 僅依賴 process.loadEnvFile，自 Node 22.5 起穩定可用。.env 文件缺失時靜默跳過，不報錯。

變量清單

每個變量的詳細文檔（默認值、格式、使用方文件、未設置時的影響），請參閱 參考 → 環境變量。下表為快速參考摘要。

LLM 提供商

至少需要一個可解析的提供商（直接設置，或通過 minara auth login 保存的 OAuth 配置），否則 Agent 拒絕啟動。

擴展思考（Extended Thinking）

Claude 3.7+ / Sonnet 4.x / Opus 4.x / Haiku 4.5+ 支持 thinking API 參數。模型按 query 自行決定花多少 budget 去推理：簡單查詢花約 0 thinking tokens，複雜綜合可能用滿預算。其他 provider（OpenAI o1/o3）的 reasoning 是自動的，對於它們參數被接受但不生效。

web-ui 複用現有的 ReasoningBlock（默認摺疊，帶流式預覽）渲染 trace，覆蓋普通 chat 與機構模式的 persona card 兩個面。對於不支持原生擴展思考的模型，輸入框工具欄會展示一個手動 Thinking 開關，開啟後會在用戶消息前面追加一句 "think step by step" 的指令。

web_search / web_extract 後端

web_search 與 web_extract 共用一個後端。模型不能選擇 provider。按可用性取第一個：Tavily → Firecrawl → Exa（本地 EXA_API_KEY 或已登錄的平台 exaPassthrough）。沒有鏈式回落，沒有 DuckDuckGo / Google / Brave / Anthropic 原生路徑，也沒有 HTML 抓取提取。空結果和 HTTP 錯誤留在當前後端。

Minara 核心

HTTP 網關

安全與涉及資金的操作

混合記憶檢索

當 EMBEDDING_PROVIDER=disabled（默認）時，混合搜索代碼路徑不活躍：所有記憶行的 embedding_state 保持 'pending'，embedding 列為 NULL；searchMemoriesHybrid 直接回退到現有的 FTS5 BM25 路徑，結果字節完全一致。運營商僅在需要跨詞彙召回提升時啟用（例如中文查詢 山寨币最近怎么样 檢索英文 altcoin drawdown 知識）。寫入路徑保持同步，embedding 在行提交後通過 queueMicrotask 異步進行，不影響用戶側延遲。

當提供商已啟用但發生瞬時 API 失敗時，行的狀態為 embedding_state='failed'。minara doctor 命令（E1 階段）暴露每種狀態的計數，便於運營商發現堆積；minara doctor --fix --apply（E2 階段）通過 MemoryStore.backfillEmbeddings() 補填。failed 和 pending 均可補填，同一行可能循環，直到成功 embedding 後狀態變為 embedded。短於 10 個字符的行，或觸發方法論注入掃描器的行，狀態為 skipped，永遠不會 embed。

回測反饋循環（Sprint 6：在線結果填充器）

週期性任務，用於閉合符合條件執行的學習循環。它計算確定性的交易後市場結果（"+5.20% in 24h"），持久化結果，再運行可選的推理評價。統一 Trading Memory 的來源規則會先執行：自動或來源未知的 perps 不會進入人工評價鏈路。

不會重新執行歷史決策。 僅評價 trade_executions 中已有的 pending 行。開啟後，gateway 啟動時會先立即處理逾期任務，再進入固定間隔。默認暗部署（BACKTEST_ENABLED=false）。

上線協議（plan dapper-coalescing-shell §Sprint 6）：

1. 設置 BACKTEST_ENABLED=true 和 BACKTEST_DRY_RUN=true，運行一個 cron 週期。檢查 shadow_runs WHERE facet='backtest_outcome'，確認結果字符串符合 ±N.NN% in Xh 格式，跳過原因合理。
2. 將 BACKTEST_DRY_RUN 翻轉為 false。Runner 開始向 trade_executions 寫入確定性 outcome 和終態；evaluation run 與 observation 保持追加寫入。
3. 只有歸因乾淨後才開啟 LEARNING_RECORD_USAGE=true。按 profile version 監控 evaluation_runs、methodology_observations 和 methodology_metric_stats；只有 promoted primary run 影響新統計。

個性化重建（M3.2 事件驅動閾值）

Minara 通過 PersonalizationRebuilder 從每次對話中學習交易偏好。M3.2 之前，重建器每 10 分鐘在冷卻後運行一次。M3.2 將其改為事件驅動加閾值門控：數據寫入（交易、記憶、聊天輪次）觸發事件喚醒重建器；每次重建須通過兩個獨立門控，即最少新輸入數量和自上次重建以來的最小經過時間。兩個門控須同時滿足，缺一不觸發。

60 分鐘安全網調度器仍然存在，用於覆蓋丟失的事件（如寫入與其訂閱者之間進程重啟），但在安靜的系統上產生零 LLM 調用和零 info 日誌。

交易摘要閾值

如果交易頻率導致摘要頻繁更新，可提高閾值；如需在回測或新手引導期間儘快收斂，可降低閾值。

記憶提取閾值

rebuildMemories 掃描游標 last_indexed_chat_id 之後寫入的 chat_turns 行並提取離散事實。默認使用僅 ADD 提示詞（無 UPDATE/DELETE），矛盾內容與先前事實並列 ADD，在檢索時解決。當 MEMORY_CONSOLIDATION_ENABLED 開啟時，後續的消解過程改為對每條事實判定 ADD / UPDATE / SUPERSEDE，在寫入時整理過時與矛盾的行（見 Minara Memory）。每條提取的事實以行的形式寫入共享 memories 表，包含 fact_type、attributed_to、entities_json 和 linked_memory_ids 元數據。

共享配置項

運營提示： 在全新部署時，將 FIN_PROFILE_TRADING_SUMMARY_MIN_NEW_TRADES 設為 1，將 FIN_PROFILE_MEMORIES_MIN_NEW_TURNS 設為 2，使重建器在第一天快速預熱。配置文件穩定後恢復默認值。

Agent 外歷史鏡像

個性化重建器現在消費三個數據源：本地 trade_history（agent 會話內）、perps_fills（Minara /v1/perp-wallets/fills 跨子錢包鏡像）、external_spot_activities（Minara /v1/tx/cross-chain/activities）。以下配置項控制 MinaraHistorySync 的同步策略以及 LLM 重建讀取的數據量。

同步觸發模型。 三條路徑觸發 MinaraHistorySync.scheduleSync()：(1) 任何 trade:recorded 事件（agent 剛執行了一筆交易，用戶很可能也在 web/mobile 端做了操作），(2) PersonalizationRefreshTask 的每小時安全網 tick（兜底丟失的事件），(3) 顯式的 /refresh-personalization --force / POST /v1/profile/refresh 路徑。5 分鐘節流保證每個窗口內 API 不會被打超過一次。

水位粒度。 minara_history_sync_state 以 (source, sub_account_id) 為主鍵。單個子錢包的瞬時故障既不會汙染其同伴的水位，也不會影響全局 spot 游標。

Hyperliquid 永續合約

MINARA_HL_DEX_DISCOVERY 控制在構建永續合約快照和同步交易歷史時，Minara 發現 Hyperliquid 命名永續 DEX 的範圍。

Strategy Studio（測試版）

一個運營商配置項控制 strategy-rl 基準測試運行器使用的離線策略代碼生成子 Agent。它有合理默認值，不設置也可正常使用。

Harness RL

機構模式（多 Agent 投研團隊模擬）

minara_institution_analyze 工具召集 6 階段流水線（4 名分析師並行 → 多空研究辯論 → 研究主管（RM）→ 交易員 → 三方風控辯論 → 投資組合經理（PM））用於高風險單資產分析。以 TradingAgents 為原型；輪次數默認值與該項目的 default_config.py 完全一致，超時和 token 上限則遵循 Minara 的 deep-research 及 Agent 循環約定。

以下所有變量均為 Agent 循環基礎設施，按項目約定無 MINARA_ 前綴。全部不設置時採用 TA 錨定的默認值。

單模型策略。 流水線中每個角色（分析師、辯論參與者、研究主管（RM）、交易員、風險人物、投資組合經理（PM）、配置 Agent/Allocator）均運行在運營商選定的 Agent 模型上，與 Agent 其餘部分使用相同的提供商和模型。不支持按角色覆蓋。如需在更強的模型上運行綜合分析，可為整個會話切換 Agent 默認模型。

成本說明： 單次機構運行約 25 次 LLM 調用 × 4K 輸出 token，合計約 10⁵ 輸出 token。以默認設置在 Sonnet 級模型上約需 $1-3。向終端用戶暴露該工具時，請在顯著位置註明此成本。

硬編碼常量（v1 中不可通過環境變量調整）：

• 第 1 階段分析師併發數 = 4（分析師數量；通過 Promise.all 並行，無信號量庫）。
• 子 Agent 內層循環輪次上限 = 5 輪。與 Minara 的 strategy-code-subagent 規範一致；分析師通常只需 1-3 次工具調用即可生成報告。
• 單次 LLM 調用超時 = wallClock / 10，下限 5 秒。
• 輸出語言 = 繼承自現有的用戶消息語言檢測（與 deep-research 使用相同的模式）；內部辯論輪次始終使用英語，僅最終報告本地化。

如實際運營需要調整硬編碼常量，請在後續 PR 中將其提升為環境變量。

自學習與 Phase B 反思（v2 PR 1 / PR 2）

v2 自學習軌道將每次機構運行持久化到三張 SQLite 表（institution_runs、institution_role_outputs、institution_reflections），針對仍持有的倉位運行多窗口 Phase B 反思階梯（1d/7d/30d/90d/180d/365d），並在每次新機構調用前對陳舊的歷史運行寫入"懶加載"反思（Phase 0 回顧刷新）。以下所有變量均為 Agent 循環基礎設施，按項目約定無 MINARA_ 前綴。

分析師恢復與規範資產預解析

每個 Phase-1 分析師 slot 先在自由的 tool 調用循環裡跑，然後跑一輪固定格式的綜合 turn，要求模型用 HEADLINE / KEY FINDINGS / CONFIDENCE 的結構化散文格式總結觀察。編排器在服務端直接把散文解析為 AnalystReport：不再有強制提交的 toolChoice 階段，也沒有重試 harness。當散文為空或解析失敗時，編排器回落到 buildSubagentSummaryReport，它在兩種分支下都能產出可用報告（tool 有成功結果時引用 tool 數據；全部失敗時回到該分析師角色的默認推理）。下游階段始終收到可用的總結；舊的 data_gap 標誌已經退役，也沒有可調的重試預算，契約是"始終產出可用結果"，沒有預算需要調。

在 Phase 1 派發之前，若 ticker 為 unknown，會觸發服務端的規範身份預解析：並行查詢 CoinGecko / CMC / DexScreener，將每個 provider 的結果歸一化為 chain+contract（或 chain+native）身份，持久化在帶過期時間的 SQLite 緩存中。

方向感知評分。 Phase B 記錄的 raw_return 對做空倉位取反，對持平決策歸零（在下跌標的上盈利的做空記錄正收益，而非負收益）。做多或未指定方向的倉位直接透傳。詳見 reflect.ts applyDirection()。

可重試的數據中斷。 標準窗口評估在價格獲取失敗時寫入 data_unavailable 佔位符；下次 cron 執行時，一旦價格恢復，該佔位符會被 UPSERT 為 ok。nextDueStandardWindow 按 status='ok' 過濾，確保窗口在成功前持續重新評估。

離線學習配置調優（Phase B 門控）

apps/agent/src/learning/methodology-store.ts 中的 LEARNING_CONFIG 超參數目前為手動調整。未來的貝葉斯優化工具將針對 Sprint 6 積累的 P&L 歸因數據對其進行調優；代碼位於 apps/agent/src/learning/replay/ 和 tools/tuning/（構建完成後）。

該工具僅離線運行，通過 CLI / Python 子進程執行，從不作為請求路徑的一部分。在數據積累達到準備門控（≥100 條已評估交易，≥20 條唯一方法論命中，見 minara learning stats）之前，整個路徑保持禁用。

完整路線圖及目標函數設計見 apps/agent/docs-src/bo-learning-config-tuning.md。

方法論自優化循環（第 1-7 階段）

輪次結束鉤子運行獨立的 Haiku 級摘要器，從建議類輪次提取 {asset, decision, confidence, quoted_price}，並持久化到 decision_history。默認為異步模式；對用戶可見延遲無影響。

階段 2 ： 多週期回測 + 幻覺檢查

定時任務填充 decision_outcomes 表，記錄 1 天、3 天、1 周、1 月的收益。填充前，系統對比 agent_quoted_price 與歷史實際價格；偏差超過 HALLUCINATION_MAX_PRICE_DELTA_PCT 時，該決策被標記並排除在下游學習外。

第 3 階段 ： 獎勵

獎勵函數將 4 個時間跨度的收益向量聚合為單個標量，用於評估每項決策。BUY 獎勵上升行情，SELL 獎勵下降行情，HOLD 獎勵中性走勢（|收益| ≤ 閾值）。

第 4 階段 / 7 ： 方法論實例分發

每個（模板、資產類別）的閾值覆蓋。第 4 階段提供腳手架；第 7 階段將提示詞構建器切換為優先使用實例覆蓋。off 保持第 4 階段前的行為完全不變。

實例分發默認啟用：提示詞構建器在可用時將 BO 調優的實例覆蓋合併到模板默認值。通過 DISABLE_METHODOLOGY_INSTANCE_DISPATCH=1 緊急停止開關恢復僅模板解析（見上文 agent-loop 部分的說明）。

第6階段 ：： BO 調優週期

Python 工具集（位於 tools/tuning/）按符合條件的 bucket 運行 bayesian-optimization； 由 TS 週期編排器驅動，該編排器評估 6 個資格門限 + 資產類別配置。

推出順序：

1. DECISION_CAPTURE_ENABLED=true ：： 開始錄製建議輪次。
2. 等待約 30 天收集數據。
3. DECISION_BACKTEST_ENABLED=true + DECISION_BACKTEST_DRY_RUN=true ：： 影子模式運行 1 周。
4. DECISION_BACKTEST_DRY_RUN=false ：： 實時回測寫入。
5. 檢查 minara learning stats 報告 READY_FOR_BO=true。
6. METHODOLOGY_INSTANCE_TUNING_ENABLED=true ：： 激活 BO 週期。
7. Instance dispatch 默認啟用；保持 DISABLE_METHODOLOGY_INSTANCE_DISPATCH 未設置。

內置工具

每一行都是可選的。缺少變量會靜默禁用相應功能。

消息平臺（擴展集）

在原有七個平臺（telegram、discord、slack、email、whatsapp、signal、home_assistant）之上新增 11 個 IM 與消費社交平臺。每個平臺有自己的 env 變量塊；任何一項為空都會靜默禁用該 provider 的出入站（路由 404，gateway 從運行時映射中剔除）。

詳細配置步驟、入站 webhook URL、簽名算法見 消息通道 各平臺子頁。連線憑據最快的路徑是 minara auth messaging add（交互式 picker，列出 18 個平臺及其當前已配置 / 未配置狀態）。

Lark / Feishu

WeCom（企業微信）

DingTalk（釘釘）

WeChat OA（公眾號）

QQ Bot

LINE

Mattermost

Microsoft Teams

Google Chat

BlueBubbles（iMessage）

Matrix

客戶端外連入站 daemon

Telegram、Discord、Slack、Mattermost、QQ、DingTalk 和 Lark 都支持客戶端外連入站 daemon：Agent 主動向外建立並保持一條長連接（長輪詢或 WebSocket），而不必運行公網 webhook 服務器。這正是讓雙向對話能在沒有公網 IP、沒有隧道、沒有第三方的個人機器上工作的原因。當平臺的出站憑據已配置且未為其配置公網 webhook 時，對應 daemon 會自動啟動；下面的開關是對該自動判定的顯式三態覆蓋（留空 = 自動，1 = 強制開啟，0 = 強制關閉）。

MCP 集成

原生提供商密鑰（PR-A → PR-G 遷移）

提供商路由推出已下線了供應商 coinglass / coinank / query-token-audit / meme-rush / polymarket / okx-dex-token / okx-wallet-portfolio / okx-security / okx-dex-trenches SKILL.md 包。它們的功能現在存在於 apps/agent/src/tools/_shared/ 下的原生優先鏈以及 analysis.derivatives / market.flows / security.token / discovery.dex / prediction.markets 技能中。下面列出的環境變量控制原生提供商，而非舊版 SKILL.md 包。

原生 prediction.markets 技能是只讀的（Polymarket 的公開 Gamma + CLOB 讀端點），無需任何環境變量。已下線的 external-polymarket SKILL.md 使用 PRIVATE_KEY / RPC_URL / POLY_BUILDER_* 來進行認證訂單下單；該寫入路徑尚未遷移，這些環境變量在 Agent 中已無消費者。

保留的外部技能包

PR-G 刪除後，這些 vendor 化的技能包仍保留在原地 （它們覆蓋了原生優先鏈尚未吸收的能力）：

方法論學習閉環 ： case 歸因 + synthesis（Phase 1-5）

Phase 1-5 系列引入的方法論學習閉環的調節參數（case-recorder、歸因 cron、synthesis）。全部可選 ： 默認值面向生產環境調優。大多數運維方只 需關注 總開關和 synthesis 閾值。

總開關（事故響應）

設為 1 / true / yes / on 啟用。其他值或未設保持路徑活躍。 熱讀 ： 運維可不重啟 agent 翻轉。

Synthesis 調優（Phase 4 D）

價格質量（Phase 3 F4.3）

每個資產類別的日內絕對收益上限。7 天窗口按 sqrt(7) 放大。攔截單日 FX 印錯、拆股後的價格跳變、退市標的歸零等汙染 Wilson 的髒數據。

Case-recorder 維護（Phase 2）

Phase 5 ： 跨 turn 橋接 + 調度器

運營學習 cron

agent 默認不自動調度學習 cron。運維方將下面任一 minara learning 子命令接入系統 cron / launchctl / systemd timer。推薦每日節奏：

# 每日 03:00 — sweep、归因、synthesize。幂等，错过的一次会在下一 tick 重放。
0 3 * * *  /usr/local/bin/minara learning cron --json >> /var/log/minara-learning.log

CLI 表面（Phase 4 E）：

minara learning methodology explain <id>          # 当前状态 + 审计
minara learning methodology lifecycle [--kind k]  # 审计日志尾部
minara learning methodology cases [--asset c]     # case 表尾部
minara learning attribute                         # 一次 7d 归因 pass
minara learning synthesize [--asset c]            # 一次 synthesis pass
minara learning sweep-orphans                     # 一次 orphan sweep
minara learning cron                              # 上面全部

方法論審計子系統（被動觀察者）

一套只讀的審計子系統疊加在學習閉環之上，產出一個複合健康分。六個維度合成複合分：synthesis 決策穩定性、畢業後短期降級率、歸因健康度、資產類覆蓋度、隔離反覆檢測、cron 健康度。子系統永不變更學習狀態，唯一寫入是每次 pass 一行到 methodology_audit_reports。端到端測試在每次審計 pass 前後哈希四張學習表，一旦未來回歸引入寫入會立即失敗。

cron 與 agent loop 合作。每次 tick 檢查共享的 BusyTracker。如果有用戶對話在跑、或 agent 空閒時間不足配置的閾值，本次 tick 被推遲。連續 N 次推遲後，飢餓守衛強制執行，避免長期忙碌的部署丟失審計覆蓋。pass 執行過程中，orchestrator 在每個 SQL 階段之間向事件循環讓步，turn 進來時立即在 busy tracker 上暫停。

默認每天跑一次。cron_health 讀取 methodology_cron_runs 心跳錶，由 src/learning/methodology-cron.ts 在每次學習 tick 末尾寫入，所以歸因通道安靜（無可歸因 case）不會被誤判為閉環已死。

CLI 接口：

minara learning audit run [--window-days N]  # 内联单次 pass
minara learning audit show [--latest|--pass <id>]
minara learning audit trend [--days N]       # composite 历史 + sparkline
minara learning audit findings [--severity high|medium|low]

資金確認繞過（高級 ： 生產警告）

MINARA_SKIP_FUND_CONFIRM 由統一確認門執行。設置後 fund-moving 調用跳過確認卡片並在首次調用即執行。case-recorder 同步 適配 ： 繞過下執行的 turn 計為 fund_moving_executed 進行 Wilson 歸因。 不要在交互式或生產環境中設置。

主動式財富智能體

後臺監管循環負責運行每個已激活的委託（按市價標記持倉、止盈/止損/再平衡、記錄盈虧快照、寫入工作日誌），以及較慢的重新發現循環（尋找新機會）。這三項也可以在 設置 → 主動模式（以及主動模式模塊自身的設置頁）裡實時修改；下面的環境變量是啟動時的兜底。多 worker 部署只在 IS_PRIMARY_WORKER=1 的 worker 上運行該循環。

x402 支付牆預授權（PR-X）

這些變量約束了 HTTP 402 / x402 支付牆的"一次付費後自動付費"功能。授權調用本身始終經過第 3b 條的兩步確認門控；在活躍會話範圍內匹配的後續付款跳過每次調用的用戶提示，直接通過 transfer_token 執行。每次自動扣費都會向響應寫入審計元數據（會話 ID + 剩餘預算），讓用戶可以追蹤每次扣費。

連接到：

• apps/agent/src/minara/x402-preauth-store.ts ： SQLite 存儲 + 上限計算
• apps/agent/src/minara/x402-preauth-config.ts ： 環境加載器 + 上限輔助函數
• apps/agent/src/tools/_shared/confirm.ts ： shouldAutoExecuteX402 輔助函數
• apps/agent/src/tools/trade.ts ： transfer_token 優先查詢自動執行策略
• apps/agent/src/tools/x402-preauth.ts ： x402_preauth_grant / _list / _revoke
• apps/agent/src/gateway/repl-commands.ts ： /x402 preauth CLI 入口

scope=any + ttl=forever 是最寬鬆的授權組合。 REPL 的 /x402 preauth grant 處理器對該組合需要雙重顯式確認； LLM 工具 x402_preauth_grant 永遠不會自動提議它。

OpenClaw 工作空間集成

Agent 讀取並寫入工作空間目錄（默認 ~/.minara/workspace/，可通過 MINARA_WORKSPACE_DIR 環境變量或 --workspace 標誌覆蓋），該目錄包含按 OpenClaw 的 AGENTS.default.md 模式建模的 markdown 文件：SOUL.md（身份）、AGENTS.md（規則）、IDENTITY.md、USER.md、MEMORY.md（精選長期記憶）、HEARTBEAT.md（會話間備忘）、BOOTSTRAP.md（僅首次運行）、TOOLS.md（環境特定工具說明）和 memory/YYYY-MM-DD-*.md（日誌）。

模板位於 apps/agent/src/workspace/templates/ 下。啟動路徑在 createApp() 內自動調用 seedWorkspaceIfMissing()，使新安裝獲得完整文件集，無需操作員運行 minara setup。種子過程是冪等的 ： 用戶編輯過的文件永遠不會被覆蓋。HEARTBEAT.md 有意不被種子化（Agent 在首輪結束時寫入真實的；種子化陳舊狀態會造成誤導）。

Web UI 的設置 → 工作空間面板通過網關的 /v1/workspace/files 端點編輯 ~/.minara/workspace/ 下的運行時文件，使用 sha256 樂觀併發控制。

連接到：

• apps/agent/src/workspace/seed.ts ： seedWorkspaceIfMissing + atomicWriteFile
• apps/agent/src/workspace/heartbeat-writer.ts ： 每輪 ## State 寫入器
• apps/agent/src/workspace/daily-log-writer.ts ： 每會話日誌記錄
• apps/agent/src/workspace/dreaming-task.ts ： 定期 MEMORY.md 合併
• apps/agent/src/workspace/bootstrap-handler.ts ： BOOTSTRAP_DONE 時歸檔
• apps/agent/src/workspace/soul-change-detector.ts ： 披露 SOUL.md 編輯

MINARA_WORKSPACE_DIR 和 --workspace CLI 標誌覆蓋讀寫的默認 ~/.minara/workspace/ 路徑，包括自動種子和網關編輯器。在指向現有 OpenClaw 工作空間時有用（--workspace ~/.openclaw/workspace）。

深度研究報告渲染

Point-in-time 財務快照

歷史快照只接納 SEC accepted time 不晚於請求截止時間的事實。FMP 數據只有在確定性匹配 SEC filing 後才能補充事實。Yahoo 當前摘要、市值、板塊、行業、TTM 數值和 DCF 始終屬於 latest-only approximation。

行為記憶

設置 BEHAVIOR_MEMORY_ENABLED=true 後才會開始採集。分類開關彼此獨立；資產上下文、交易和對話仍需顯式開啟。系統不保存請求/聊天正文、密鑰、地址、訂單參數或單項持倉。

添加新環境變量的檢查清單

合併前請完成：

• 選定歸屬：preferences schema、API-key / messaging 登錄表，或 infra schema（不屬於 prefs/secrets 登錄表時加 exempt）
• 呼叫端透過 prefs.get / secrets.* / infra.get 讀取，而不是 process.env.<NAME>
• 在 apps/agent/src/config/env-docs/sections/ 對應章節添加說明塊（用途、消費者、何時設置、未設置時的默認值、值格式）
• 對於域技能：設置 requires_env: ["<NAME>"]，使技能在憑據缺失時自動隱藏
• 對於工具：工廠函數在變量缺失時返回 []（啟動時絕不拋錯）
• 變量名遵循約定 <PROVIDER>_API_KEY / <PROVIDER>_TOKEN / <PROVIDER>_<FIELD> ： 大寫下劃線命名法，提供商前綴優先
• 任何地方都未提交真實密鑰值