环境变量

本页介绍 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> ： 大写下划线命名法，提供商前缀优先
• 任何地方都未提交真实密钥值