內置工具

內置工具（src/tools/*）每個都是可選的——缺失 key → 該特性靜默禁用。

web_search / web_extract 後端

web_search 與 web_extract 共用一個後端。模型不能選擇 provider。按可用性取第一個： 1. Tavily — TAVILY_API_KEY。最高優先級。 2. Firecrawl — FIRECRAWL_API_KEY，僅當 Tavily 不可用時。 3. Exa — 本地 EXA_API_KEY，或已登錄的 Minara 會話（平臺 exaPassthrough），僅當 Tavily 與 Firecrawl 都不可用時。沒有鏈式回落，沒有 DuckDuckGo / Google / Brave / Anthropic 原生路徑，也沒有 HTML 抓取提取。空結果和 HTTP 錯誤留在當前後端。被 JS 牆擋住的頁面走 browser_navigate / browser_snapshot。高級過濾（Exa category、Firecrawl sources/tbs、 Tavily topic/depth）只出現在當前後端的工具 schema 上。

`EXA_API_KEY`

Exa 網頁搜索與提取（Tavily 與 Firecrawl 之後）。

作用: 當 Tavily 與 Firecrawl 都不可用時，作為 web_search 和 web_extract 的後端。有本地 key 時直接調用（優先於平臺透傳）。未設置時，已登錄的 Minara 會話仍可通過平臺 exaPassthrough 走 Exa。Exa 是神經搜索索引；搜索結果附帶高亮摘錄。提取走 /contents（乾淨頁面文本）。失敗不會回落到其他後端。
消費方: src/tools/web-backends.ts，經 src/app.ts 的 createWebTools()。
何時設置: 希望在不依賴 Minara 登錄的情況下本地使用 Exa。
未設置時: 若設置了 Tavily key 則使用 Tavily，否則 Firecrawl，否則已登錄時仍走 Exa。三者都不可用時，這兩個工具會被隱藏。
格式: 來自 https://dashboard.exa.ai/api-keys 的 Exa API key。
設置歸屬: 設置 → API 密鑰

`FIRECRAWL_API_KEY`

Firecrawl 搜索 + 提取（Tavily 之後）。

作用: 當 Tavily 不可用時，作為 web_search 與 web_extract 的後端。/search 返回標題/URL；/scrape 返回乾淨 markdown（onlyMainContent: true）。
消費方: src/tools/web-backends.ts，經 src/app.ts 的 createWebTools()。
何時設置: 希望在沒有 Tavily 的情況下同時覆蓋搜索和高質量整頁提取。
未設置時: 跳過 Firecrawl；若設置了本地 Exa key 或已登錄則使用 Exa。
Free tier: 每月 500 credits。格式：來自 https://www.firecrawl.dev/app/api-keys 的 Firecrawl API key。
設置歸屬: 設置 → API 密鑰

`TAVILY_API_KEY`

Tavily 網頁搜索與提取（最高優先級）。

作用: 同時作為 web_search 和 web_extract 的默認後端。失敗不會回落到 Firecrawl 或 Exa。
消費方: src/tools/web-backends.ts，經 src/app.ts 的 createWebTools()。
何時設置: 希望以 Tavily 作為網頁研究後端。
未設置時: 若設置了 Firecrawl key 則使用 Firecrawl，否則使用 Exa（本地 key 或登錄透傳）。三者都不可用時，web_search 和 web_extract 保持隱藏。沒有 DuckDuckGo 回退。
格式: 來自 https://tavily.com 的 Tavily API key。
設置歸屬: 設置 → API 密鑰

`GOAL_MAX_TURNS`

常駐 /goal 在暫停等待複核前的最大自動續跑輪數（REPL goal 模式）。

未設置時默認: 20
格式: 正整數
設置歸屬: 設置 → 偏好（schema 鍵）

`POSITION_MEMORY_ENABLED`

持倉/會話感知的記憶注入。開啟時，每個涉及某資產（消息中的 ticker，或用戶近期現貨熱門標的之一）的對話輪，都會把最多 5 條關於該資產的已存記憶注入到易變的 prompt 尾部——對於建議類問題注入過往觀點和交易備註，對於基本面類問題注入用戶的分析偏好和習慣。確定性且本地化（關鍵詞意圖路由 + SQLite 查詢，零額外 LLM 調用）；交易信號來自由 trading-summary 重建刷新的預構建現貨熱門標的產物。由 app.ts（positionMemoryProvider）經 memory/position-memory.ts 消費。通過 preferences 管理器實時讀取，因此翻轉它在下一輪生效。

未設置時默認: off
格式: 設為 1/true/yes/on 啟用
設置歸屬: 設置 → 偏好（schema 鍵）

`OPENAI_API_KEY`

OpenAI 平臺 key，多用途。

作用: (1) research.knowledge_base skill —— 寫入 Qdrant 的 text-embedding-3-* embeddings。 (2) src/tools/audio.ts 中的音頻 TTS。 (3) 可選的 LLM provider（需顯式啟用）—— 與 OpenAI OAuth 路徑不同。僅設置此 env 並不會自動把 OpenAI 選為 LLM provider。要啟用 LLM 路徑，運行 minara auth login openai --api-key $OPENAI_API_KEY，它會寫入 openaiApiKey profile 槽。
消費方: src/skills/builtin/research/knowledge-base.ts, src/tools/audio.ts, src/llm/openai-api-key.ts.
未設置時: 研究 KB 寫入被跳過；TTS 不可用；LLM 使用另一個 provider。
格式: 來自 https://platform.openai.com 的 sk-...。
設置歸屬: LLM 提供商憑證（設置 → 提供商與模型）

`OPENAI_BASE_URL`

可選的 OpenAI API base URL 覆蓋。

作用: OpenAI api-key LLM 客戶端 + 工具調用的目標地址。
默認值: https://api.openai.com/v1
何時設置: 指向 Azure OpenAI 兼容網關，或一個具有相同 wire 形態的企業代理。
未設置時: 使用官方 OpenAI 端點。
設置歸屬: 非用戶設置項

`OPENAI_ORG_ID`

可選的 OpenAI organization 頭。

作用: 在每次 LLM 調用中作為 OpenAI-Organization 發送。
何時設置: 你的 OpenAI 賬戶有多個 org，且你希望把賬單路由到某個特定 org。
未設置時: 使用與該 API key 綁定的默認 org。
設置歸屬: 非用戶設置項

`FAL_KEY` / `FAL_QUEUE_URL`

Fal.ai 圖像/媒體 provider。

作用: 用於 image_generate、video_generate 和實時圖片/視頻模型目錄的 Fal.ai 鑑權。
消費方: src/media/* 與媒體生成工具。
何時設置: 需要 API Key 鑑權時設置。也可在設置 > 模型與服務商 > 圖片與視頻中使用 Fal.ai 登錄。
未設置時: 媒體生成需要先使用 Fal.ai 登錄。
格式: FAL_KEY 是來自 https://fal.ai 的不透明字符串； FAL_QUEUE_URL 是隊列端點的可選覆蓋（絕對 URL，僅在使用私有 Fal.ai 部署時設置）。
設置歸屬: 設置 → API 密鑰 (FAL_KEY)
設置歸屬: 非用戶設置項 (FAL_QUEUE_URL)

消息網關

send_message 工具、workflow 觸發器和 autopilot 報告所用的出站通知目的地。可同時配置多個 provider；LLM 每次調用經 provider 參數選擇其一，回落到 MESSAGING_DEFAULT_PROVIDER。優先用 minara auth messaging add <provider>——該向導會把憑據持久化到 ~/.minara/credentials.json（messaging 槽），從不觸碰此文件。

`MESSAGING_DEFAULT_PROVIDER`

當調用方省略 provider 參數時， send_message 使用的默認 provider。

作用: agent-loop / workflow / autopilot 在不帶顯式 provider 時調用 send_message，會路由到此 id。
消費方: src/app.ts（網關映射構建）， src/tools/messaging.ts（處理器分發）。
何時設置: 你配置了多個 provider，並希望某個特定 provider 作為默認（例如 telegram 用於個人告警， slack 用於團隊通知——而你希望默認走 telegram）。
未設置時: 第一個已配置的 provider 勝出（插入順序遵循 src/messaging/providers.ts 中的 MESSAGING_PROVIDERS—— telegram → discord → slack → whatsapp → signal → email → home_assistant）。
格式: 一個 provider id —— telegram、discord、slack、 whatsapp、signal、email、home_assistant 之一。大小寫不敏感。
設置歸屬: 非用戶設置項

`MESSAGING_MAX_ATTACHMENT_BYTES`

send_message({attachments: [...]}) 調用中每個附件的大小上限。

作用: 在每個附件上傳到其 provider API 之前， resolver 會 stat 沙箱文件，當大小超過此值時以清晰的錯誤拒絕。防止一個不受約束的、由 LLM 控制的路徑用超大文件對 SMTP 中繼 / Discord / Telegram 發起 DOS。
消費方: src/messaging/attachment-resolver.ts.
何時設置: 運營方希望收緊 50 MB 的默認值（例如針對 Slack 免費層 1 GB 存儲配額，或屏蔽任何超過一分鐘的音頻）。
未設置時: 默認為 52 428 800 字節（50 MB）。Provider API 各自獨立強制其上限——此上限是 Minara 一側的限制；provider 仍可能拒絕其 API 認為過大的文件。
格式: 十進制整數（字節）。小於等於 0 的值被忽略。
設置歸屬: 非用戶設置項

`TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID`

出站 Telegram 消息。

作用: send_message 工具經 Bot API 向指定 chat 發帖。被 workflow 通知和告警輸出使用。 Telegram 是當前唯一內置流式編輯支持的 provider （見網關上的 streamDefaultIntervalMs）。
消費方: src/messaging/telegram.ts.
何時設置: 你希望 agent（或某個 workflow 觸發器）向 Telegram 頻道或私聊推送告警。
未設置時: send_message 對其他傳輸方式仍可用，但 Telegram 路徑會返回清晰的配置錯誤。
格式: TELEGRAM_BOT_TOKEN 是來自 @BotFather 的 123456:ABC-DEF... 字符串；TELEGRAM_CHAT_ID 是數字 chat id（頻道/群組為負數，私聊為正數）。
設置歸屬: 設置 → 消息渠道

`TELEGRAM_RICH_TEXT`

將出站回覆渲染為 Telegram 富文本。

作用: 開啟時（默認），markdown 回覆會渲染為 Telegram HTML（粗體、標題、表格、代碼塊、任務列表），若 Telegram 拒絕該標記則以 MarkdownV2 → 純文本回退。流式編輯僅刷新完全閉合的結構，因此用戶永遠看不到半渲染的格式。
消費方: src/messaging/telegram.ts.
何時設置: 設為 false（或 0/no/off）以原樣發送 agent 的文本，不帶任何格式。
未設置時: 富文本為開啟狀態。
設置歸屬: 設置 → 偏好（schema 鍵）

`SLACK_BOT_TOKEN` / `SLACK_CHANNEL_ID`

出站 Slack。

作用: 當請求 provider: "slack"（或 slack 為默認）時， send_message 工具路由到 Slack。出站由共享的 Vercel Chat SDK Slack adapter 提供： SLACK_BOT_TOKEN 負責發送並支持 post+edit 流式編輯； SLACK_CHANNEL_ID 是默認目標頻道。搭配下面的 SLACK_APP_TOKEN 開啟 Socket Mode 入站流。
消費方: src/messaging/chatsdk/adapters/slack.ts.
何時設置: 團隊 / 工作通知,以及 Slack 雙向對話。
未設置時: send_message 的 Slack 路徑不可用；其他 provider 仍可用。
格式: SLACK_BOT_TOKEN 以 xoxb- 開頭；SLACK_CHANNEL_ID 是 C... channel id（不是 #name）。
設置歸屬: 設置 → 消息渠道

`SLACK_APP_TOKEN`

用於 Socket Mode 入站的 app 級 token（xapp-…）。

作用: 啟用客戶端出站的 Slack 入站守護進程（Socket Mode）。設置後，agent 會向 Slack 打開一個 WebSocket 並接收 Events API 消息——無需公網 Request URL / webhook 服務器，因此雙向聊天在無公網 IP 的機器上也能工作。與 SLACK_BOT_TOKEN 搭配（用於發送回覆）。
消費方: src/messaging/inbound/slack-daemon.ts.
何時設置: 你希望在不暴露公網 webhook 的情況下實現 Slack 雙向聊天（例如運行在筆記本 / NAT 之後）。在 Slack app 配置的 "Socket Mode" / "App-Level Tokens" 下以 connections:write scope 生成它。
未設置時: Slack 入站回落到 webhook 路徑（需要一個公網 Request URL + SLACK_SIGNING_SECRET）。
格式: xapp-1-...。
設置歸屬: 設置 → 消息渠道

`DISCORD_BOT_TOKEN` / `DISCORD_CHANNEL_ID`

出站 Discord。

作用: 請求 provider: "discord"（或 discord 為默認）時， send_message 工具路由到 Discord。經 PATCH /channels/{id}/messages/{id} 支持流式編輯，節流 1000ms（Discord 速率限制 = 每 channel 每 5 秒 5 次）。
消費方: src/messaging/discord.ts.
何時設置: 社區服務器通知、以 Discord 為中心的團隊。
未設置時: send_message 的 Discord 路徑不可用。
格式: DISCORD_BOT_TOKEN 是來自 Developer Portal app 頁面的不透明 bot secret；DISCORD_CHANNEL_ID 是數字 channel snowflake。 bot 必須已被邀請進服務器 + channel，並擁有 Send Messages + Manage Messages 權限（僅當你依賴流式編輯時才需要 Manage Messages）。
設置歸屬: 設置 → 消息渠道

`HASS_URL` / `HASS_TOKEN` / `HASS_NOTIFY_SERVICE`

Home Assistant 通知。

作用: 請求 provider: "home_assistant" 時，send_message 工具路由到 Home Assistant 的通知平臺。不支持流式傳輸（notify.* 是 fire-and-forget）；helper 在收尾時回落為單次發送。
消費方: src/messaging/home_assistant.ts.
何時設置: 你希望把交易告警推送到手機推送 / Alexa TTS / 其他由 Home Assistant 中轉的端點。
未設置時: send_message 的 Home Assistant 路徑不可用。
格式: HASS_URL 是完整的 base URL（https://hass.example:8123，無尾部斜槓）；HASS_TOKEN 是來自你 HA profile 的長效訪問 token；HASS_NOTIFY_SERVICE 是 notify service id （mobile_app_pixel、alexa_tts；開頭的 notify. 可省略——由 adapter 自動剝離）。
設置歸屬: 設置 → 消息渠道

`SMTP_HOST` / `SMTP_PORT` / `SMTP_USER` / `SMTP_PASSWORD` / `EMAIL_FROM` / `EMAIL_TO`

出站郵件（SMTP）。

作用: 請求 provider: "email" 時，send_message 工具路由到郵件。主題從消息的第一行推斷（≤ 120 字符、單行）——否則回落為 "Minara alert"。不支持流式編輯。
消費方: src/messaging/email.ts（封裝 MIT 許可的 nodemailer）。
何時設置: 合規 / 歸檔渠道，或目標收件人不使用任何聊天平臺時。
未設置時: send_message 的郵件路徑不可用；其他 provider 仍可用。
格式: SMTP_HOST 是中繼主機名；SMTP_PORT 為 587（STARTTLS）或 465（SSL）（adapter 按端口選擇 TLS 模式—— 僅當 port === 465 時 secure: true）；SMTP_USER / SMTP_PASSWORD 是憑據（Gmail 請用應用專用密碼）；EMAIL_FROM 是 From 頭地址；EMAIL_TO 是默認收件人（可經 channel 逐條覆蓋）。
設置歸屬: 設置 → 消息渠道

`GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET`

由運營方提供的 Google OAuth client，用於驅動 "Email (Gmail)" 一鍵連接（provider id email-gmail）。

作用: 啟用 Settings → Messaging 中的 Connect-Gmail 按鈕。隨後 agent 使用極窄的 gmail.send scope 經 Gmail API 發送通知（從不讀取郵件）。
消費方: src/gateway/api.ts（OAuth init）+ src/messaging/gmail.ts.
何時設置: 要提供 Gmail 連接器時。在 Google Cloud console 中創建一個 OAuth client，類型選 "Desktop app"（loopback redirect），然後把 ID + secret 粘貼到這裡，或直接粘到 Email (Gmail) 面板。優先級與其他所有 messaging 憑據一致：導出的 env 變量勝出；否則使用 UI 中保存的值。
未設置（且未在 UI 中填寫）時：Connect-Gmail 按鈕被禁用；其他 provider 仍可用。
preferences-schema-coverage: SKIP —— messaging-provider 憑據在 Settings → Messaging 中管理，不在 Preferences schema 中（與 SMTP_* / TELEGRAM_* 相同）。
設置歸屬: 設置 → 消息渠道

`GMAIL_REFRESH_TOKEN` / `GMAIL_SENDER_EMAIL` / `GMAIL_TO`

Gmail 連接狀態。GMAIL_REFRESH_TOKEN 和 GMAIL_SENDER_EMAIL 由 Connect-Gmail 流程寫入（無需手動設置）。GMAIL_TO 是可選的收件人覆蓋——留空則把通知推送到已連接的收件箱本身（push-to-self）。 preferences-schema-coverage: SKIP —— 見上文 GOOGLE_OAUTH_CLIENT_ID。

設置歸屬: 設置 → 消息渠道

`WHATSAPP_ACCESS_TOKEN` / `WHATSAPP_PHONE_NUMBER_ID` / `WHATSAPP_RECIPIENT`

經 Meta Cloud API 的出站 WhatsApp。

作用: 請求 provider: "whatsapp" 時，send_message 工具路由到 WhatsApp。不支持流式編輯（Meta 的 edit API 有 15 分鐘窗口 + 嚴格速率限制，使其不適合 LLM token 流式傳輸）。
消費方: src/messaging/whatsapp.ts.
何時設置: 你已開通具備 WhatsApp Business API 訪問權限的 Meta Business app，並需要經 WhatsApp 送達通知。
未設置時: send_message 的 whatsapp 路徑不可用。
格式: WHATSAPP_ACCESS_TOKEN 是一個長的不透明 Bearer token（通常以 EAA... 開頭），由 Meta Developer Portal 或你的 Business System User 簽發；WHATSAPP_PHONE_NUMBER_ID 是已註冊業務電話號碼的數字 id；WHATSAPP_RECIPIENT 是 E.164 格式的默認收件人（+12025551234）——send_message 的 channel 參數可逐條覆蓋它。
Note: 收件人必須處於有效的 24 小時客服窗口內，或被髮送預先批准的模板消息——這是 Meta 的政策約束，不是我們的。純文本消息僅在用戶於過去 24 小時內向該業務發過消息時才有效。
設置歸屬: 設置 → 消息渠道

`SIGNAL_CLI_NUMBER` / `SIGNAL_RECIPIENT` / `SIGNAL_CLI_BINARY`

出站 Signal。

作用: 請求 provider: "signal" 時，send_message 工具路由到 Signal。與其他所有 provider 不同， Signal 沒有 HTTP API——Minara 在本地 shell out 到 signal-cli （MIT 許可，https://github.com/AsamK/signal-cli）。不支持流式編輯（Signal 協議不允許編輯）。
消費方: src/messaging/signal.ts.
何時設置: 你希望向某個 Signal 收件人發送注重隱私的告警，且宿主機上已有 signal-cli 工具。
未設置時: send_message 的 signal 路徑不可用。
Runtime dependency: signal-cli 必須已安裝並在 PATH 上（macOS：brew install signal-cli；Debian：見上游倉庫）。首次使用前，註冊發送方號碼： signal-cli -u +15555550100 register 然後輸入手機收到的短信驗證碼。若 app 啟動時二進制文件不存在，signal provider 會被靜默跳過——其他 provider 繼續工作。
格式: SIGNAL_CLI_NUMBER 和 SIGNAL_RECIPIENT 必須都是 E.164 格式（開頭 +、國家碼、總計 8-15 位數字、無空格或短橫線——例如 +12025551234）。adapter 在構造時以及每次 send() 調用時校驗該正則，並使用固定的 argv 佈局，在收件人前加 -- 以阻止任何前導短橫線的 flag 注入。SIGNAL_CLI_BINARY 是二進制路徑的可選覆蓋——默認是對 signal-cli 做 PATH 查找。
CLAUDE.md §4a Bucket B 豁免：該模塊 spawn 一個子進程，但使用 argv 形式配 shell: false，且沒有 LLM 輸入進入 argv——消息體經一個獨立的 -m 槽傳遞，收件人在寫入前經正則校驗。
設置歸屬: 設置 → 消息渠道

入站消息 webhook（可選，帶 kill switch）

入站監聽器不會自動啟動——調用方自行實例化 InboundServer（見 src/messaging/inbound/server.ts）。啟用後，它監聽來自 Telegram、Discord 和 Slack 的簽名 webhook，並把歸一化的 InboundMessage 事件分派給單個已註冊的處理器。 WhatsApp + Signal 入站在本 PR 中未接入（WhatsApp 需要證書交換握手；Signal 使用 signal-cli 守護進程 JSON-RPC socket ——兩者都值得各自的 PR）。

`TELEGRAM_WEBHOOK_SECRET`

Telegram 在 X-Telegram-Bot-Api-Secret-Token 頭中回顯的共享 secret。與 setWebhook 的 secret_token 參數在同一時機設置。

作用: 缺失或不匹配該頭的請求會在處理器運行前返回 401。
未設置時: /webhooks/telegram 路由返回 404——入站服務器表現得如同 Telegram 入站未配置。
格式: 不透明字符串，1–256 字符（Telegram 自身的約束）。
設置歸屬: 非用戶設置項

`SLACK_SIGNING_SECRET`

Slack app signing secret（不是 bot token）。

作用: 按 Slack 公佈的方案，對 v0:{timestamp}:{body} 用 HMAC-SHA256 做 webhook 簽名校驗。
未設置時: /webhooks/slack 返回 404。
格式: 來自 Basic Information → App Credentials 的不透明十六進制字符串。
設置歸屬: 設置 → 消息渠道

`DISCORD_PUBLIC_KEY` / `DISCORD_APPLICATION_ID`

Discord 應用標識。

作用: Vercel Chat SDK 的 Discord adapter 構造函數要求應用公鑰（即使在 Gateway 模式下），因此必須與 DISCORD_BOT_TOKEN 一起設置 DISCORD_PUBLIC_KEY 才能構建 adapter。DISCORD_APPLICATION_ID 為可選,用於標識應用以註冊 slash 命令。
未設置時: Discord 視為未配置(缺公鑰無法構建 adapter)。
格式: DISCORD_PUBLIC_KEY 為 64 字符小寫十六進制（原始 32 字節 Ed25519 公鑰）；DISCORD_APPLICATION_ID 為數字應用 id。
設置歸屬: 設置 → 消息渠道

`WHATSAPP_APP_SECRET` / `WHATSAPP_VERIFY_TOKEN`

WhatsApp Cloud API 入站 webhook（Meta）。

作用: - WHATSAPP_APP_SECRET 經 X-Hub-Signature-256 為每個 POST 簽名（對原始 body 做 HMAC-SHA256）。簽名錯誤 → 401。 - WHATSAPP_VERIFY_TOKEN 是 Meta 的 hub.verify_token，在運營方於 Meta dashboard 註冊 webhook URL 時的一次性 GET 握手中回顯。
未設置時: - WHATSAPP_APP_SECRET 缺失 → /webhooks/whatsapp POST = 404。 - WHATSAPP_VERIFY_TOKEN 缺失 → /webhooks/whatsapp GET = 404。
格式: 不透明字符串；app secret 是來自 Meta app dashboard 的十六進制，verify token 是你自行配置的任意值。
設置歸屬: 設置 → 消息渠道

PR2: 亞洲 IM 平臺（Lark / WeCom / DingTalk / WeChat OA / QQ / LINE）

每個塊同時設置出站憑據以及 src/messaging/inbound/specs/<id>.ts 所需的入站 webhook secret。任何塊留空則同時禁用該 provider 的出站 + 入站；該路由 404，網關從 live map 中省略。

`LARK_APP_ID` / `LARK_APP_SECRET` / `LARK_DEFAULT_CHAT_ID` / `LARK_VERIFICATION_TOKEN` / `LARK_ENCRYPT_KEY` / `LARK_DOMAIN`

Lark / 飛書 — LARK_*。租戶 token 出站 + 簽名/加密的 webhook 事件。

作用: 出站 Lark IM 消息；供 agent-loop 使用的入站 webhook 事件（im.message.receive_v1）。
消費方: src/messaging/lark.ts + src/messaging/inbound/specs/lark.ts.
格式: LARK_APP_ID — 來自 Lark 開發者後臺的 cli_xxxxx。 LARK_APP_SECRET — 同一後臺的不透明 secret。 LARK_DEFAULT_CHAT_ID — 默認 oc_xxxxx chat id。 LARK_VERIFICATION_TOKEN — Event Subscription 驗證 token。 LARK_ENCRYPT_KEY — 可選的 Event Subscription 加密 key。設置後，入站 POST body 以 SHA256(encrypt_key) 為密鑰 AES-256-CBC 加密到達。留空為明文模式。 LARK_DOMAIN — open.feishu.cn（默認，中國大陸）或 open.larksuite.com（國際版）。
設置歸屬: 設置 → 消息渠道

`WECOM_CORP_ID` / `WECOM_AGENT_ID` / `WECOM_SECRET` / `WECOM_DEFAULT_TOUSER` / `WECOM_CALLBACK_TOKEN` / `WECOM_CALLBACK_AES_KEY`

WeCom（企業微信）自建應用。

作用: 出站到 WeCom 用戶 / 部門 + 簽名的 AES 加密回調入站。WeCom 兩個面都經與 WeChat OA 相同的 legacy SHA1+AES 信封路由。
消費方: src/messaging/wecom.ts + src/messaging/inbound/specs/wecom.ts.
格式: WECOM_CORP_ID — 來自 "我的企業" 頁面的 corp ID。 WECOM_AGENT_ID — 應用 agent ID（數字）。 WECOM_SECRET — 應用 secret。 WECOM_DEFAULT_TOUSER — 默認收件人（@all 表示全體 agent）。 WECOM_CALLBACK_TOKEN — 來自 "接收消息" 回調配置的 Token。 WECOM_CALLBACK_AES_KEY — 同一頁面的 43 字符 EncodingAESKey。
設置歸屬: 設置 → 消息渠道

`DINGTALK_WEBHOOK_URL` / `DINGTALK_WEBHOOK_SECRET`

DingTalk（釘釘）自定義群機器人 — 帶 HMAC 簽名的出站 webhook。

作用: 經機器人的 webhook URL 出站到某個 DingTalk 群（按 DingTalk 規範用 timestamp + secret 簽名）。入站監聽 DingTalk POST 回來的 outgoing-message webhook。
消費方: src/messaging/dingtalk.ts + src/messaging/inbound/specs/dingtalk.ts.
格式: DINGTALK_WEBHOOK_URL — 那個 https://oapi.dingtalk.com/robot/send?access_token=… URL。 DINGTALK_WEBHOOK_SECRET — 來自 "簽名" 模式的 SECxxxx 簽名 secret。
設置歸屬: 設置 → 消息渠道

`DINGTALK_STREAM_APP_KEY` / `DINGTALK_STREAM_APP_SECRET`

Stream Mode 入站。

作用: 啟用客戶端出站的 DingTalk Stream Mode 守護進程。兩者都設置後，agent 會打開一個 gateway WebSocket 並經它接收 bot 消息——無需公網回調 URL，因此雙向聊天在無公網 IP 的機器上也能工作。與上面的機器人 webhook 不同：Stream Mode 以組織 app 身份認證（AppKey / AppSecret），而回復仍經機器人 webhook 發出。
消費方: src/messaging/inbound/dingtalk-daemon.ts.
何時設置: 你希望在不暴露公網回調的情況下實現 DingTalk 雙向聊天。在 DingTalk 開發者後臺該 app 的 "憑證與基礎信息" 頁面找到 AppKey / AppSecret。
未設置時: DingTalk 入站回落到 outgoing-webhook 路徑（需要公網回調 URL）。
格式: 來自 DingTalk 開發者後臺的不透明字符串。
設置歸屬: 設置 → 消息渠道

`WECHAT_OA_APP_ID` / `WECHAT_OA_APP_SECRET` / `WECHAT_OA_TOKEN` / `WECHAT_OA_AES_KEY` / `WECHAT_OA_DEFAULT_OPENID`

WeChat OA（公眾號）客服消息。

作用: 出站客服消息（必須在用戶的 48 小時互動窗口內——超出該窗口平臺會返回 errcode 45015）。入站：簽名 + AES 加密的消息事件。
消費方: src/messaging/wechat_oa.ts + src/messaging/inbound/specs/wechat_oa.ts.
格式: WECHAT_OA_APP_ID / WECHAT_OA_APP_SECRET — OA AppID + AppSecret。 WECHAT_OA_TOKEN — 來自公眾平臺 → 設置 → 服務器配置的服務器配置 Token。 WECHAT_OA_AES_KEY — 同一頁面的 43 字符 EncodingAESKey。 WECHAT_OA_DEFAULT_OPENID — 默認收件人 openid。
設置歸屬: 設置 → 消息渠道

`QQ_BOT_APP_ID` / `QQ_BOT_APP_SECRET` / `QQ_BOT_TOKEN` / `QQ_BOT_DEFAULT_CHANNEL_ID`

QQ Bot v2（官方 Bot OpenAPI）。

RATE LIMIT WARNING: 官方機器人被限制為每個 bot 每月僅 4 條
主動消息，加每天 200 條主動私信，加每個 channel 每天 20
條主動子頻道消息。大多數交互
必須使用被動回覆（用戶發起消息後 ≤5s）；
主動推送保留給關鍵告警。
消費方: src/messaging/qq.ts + src/messaging/inbound/specs/qq.ts.
格式: QQ_BOT_APP_ID — bot AppID（數字）。 QQ_BOT_APP_SECRET — bot Secret（既用作出站認證，也用作入站 Ed25519 簽名校驗的種子）。 QQ_BOT_TOKEN — bot token（legacy 字段，為兼容保留）。 QQ_BOT_DEFAULT_CHANNEL_ID — 默認目標。格式 <kind>:<id>，其中 kind 為 c2c | group | channel | dm。裸 id 默認為 channel:。
設置歸屬: 設置 → 消息渠道

`LINE_CHANNEL_ACCESS_TOKEN` / `LINE_CHANNEL_SECRET` / `LINE_DEFAULT_USER_ID`

LINE Messaging API。

作用: 出站 LINE push 消息（按量計費）加簽名的入站 webhook 事件。Reply token（免費）尚未接入——每條出站都經計費的 push API。
消費方: src/messaging/line.ts + src/messaging/inbound/specs/line.ts.
格式: LINE_CHANNEL_ACCESS_TOKEN — 來自 LINE Developers 的長效 bearer。 LINE_CHANNEL_SECRET — 用於校驗入站 X-Line-Signature 的 channel secret（HMAC-SHA256、base64）。 LINE_DEFAULT_USER_ID — 默認收件人 userId / groupId / roomId。
設置歸屬: 設置 → 消息渠道

PR3: 西方 IM + 聯邦（Mattermost / Teams / Google Chat / BlueBubbles / Matrix）

`MATTERMOST_URL` / `MATTERMOST_BOT_TOKEN` / `MATTERMOST_DEFAULT_CHANNEL_ID` / `MATTERMOST_OUTGOING_WEBHOOK_TOKEN`

Mattermost — bot-token 出站 + outgoing-webhook 入站。

CAVEAT: Mattermost 的 outgoing-webhook 特性僅在公開
channel 中、且僅在為該 webhook 配置的 TRIGGER WORDS 上觸發。
私有 channel 和私信需要 WebSocket bot 路徑（未來的 PR）。
消費方: src/messaging/mattermost.ts + src/messaging/inbound/specs/mattermost.ts.
格式: MATTERMOST_URL — Mattermost 服務器 URL（無尾部斜槓）。 MATTERMOST_BOT_TOKEN — 某個 bot 賬戶的 personal access token。 MATTERMOST_DEFAULT_CHANNEL_ID — 默認目標 channel。 MATTERMOST_OUTGOING_WEBHOOK_TOKEN — 與 outgoing-webhook body 中的 token 字段比對的 token（常數時間）。
設置歸屬: 設置 → 消息渠道

`TEAMS_BOT_APP_ID` / `TEAMS_BOT_APP_PASSWORD` / `TEAMS_BOT_TENANT_ID` / `TEAMS_DEFAULT_CONVERSATION_ID` / `TEAMS_DEFAULT_SERVICE_URL`

Microsoft Teams — 帶 JWT 校驗入站的 Bot Framework。

入站 JWT 校驗從
https://login.botframework.com/v1/.well-known/openidconfiguration 動態拉取 JWKS——
切勿在任何地方硬編碼該 JWKS URL；Microsoft 會輪換它。
消費方: src/messaging/teams.ts + src/messaging/inbound/specs/teams.ts.
格式: TEAMS_BOT_APP_ID — bot 的 Microsoft App ID GUID。 TEAMS_BOT_APP_PASSWORD — bot 的 Microsoft App 密碼。 TEAMS_BOT_TENANT_ID — 多租戶用 common，單租戶用 GUID。 TEAMS_DEFAULT_CONVERSATION_ID — 推送的默認會話。 TEAMS_DEFAULT_SERVICE_URL — 默認 Bot Framework serviceUrl （通常為 https://smba.trafficmanager.net/teams）。生產代碼應從入站 activity 中學習該值並按會話持久化；此 env 變量是 bootstrap 回退。
設置歸屬: 設置 → 消息渠道

`GOOGLE_CHAT_CREDENTIALS` / `GOOGLE_CHAT_USE_ADC` / `GOOGLE_CHAT_PROJECT_NUMBER` / `GOOGLE_CHAT_DEFAULT_SPACE_ID`

Google Chat — Vercel Chat SDK adapter（service-account 或 ADC；webhook 入站）。

作用: 出站與入站均由共享的 Vercel Chat SDK Google Chat adapter 提供。入站是 Google 簽名的 webhook / Pub/Sub 推送：InboundServer 將 /webhooks/google_chat 轉發給 chat.webhooks.google_chat （需 MESSAGING_INBOUND_ENABLED=1）。
消費方: src/messaging/chatsdk/adapters/google_chat.ts.
格式: GOOGLE_CHAT_CREDENTIALS — service-account 憑據 JSON（或密鑰文件路徑）。CLAUDE.md §4：路徑必須位於 data / sandbox 樹內；切勿引用運營方控制範圍之外的路徑。 GOOGLE_CHAT_USE_ADC — 設為 true 則改用應用默認憑據（Application Default Credentials）。 GOOGLE_CHAT_DEFAULT_SPACE_ID — 默認 space 資源名（例如 spaces/AAAA1234567）。
設置歸屬: 設置 → 消息渠道

`BLUEBUBBLES_SERVER_URL` / `BLUEBUBBLES_PASSWORD` / `BLUEBUBBLES_DEFAULT_CHAT_GUID`

BlueBubbles — 經自託管服務器的 iMessage 橋接。

需要運營方在一臺持續登錄目標 iMessage 賬戶的 Mac 上
運行 BlueBubbles 服務器。認證是
單一共享密碼——純常數時間比對，無 HMAC。
消費方: src/messaging/bluebubbles.ts + src/messaging/inbound/specs/bluebubbles.ts.
格式: BLUEBUBBLES_SERVER_URL — BlueBubbles 服務器的公網 URL （通常是 ngrok / cloudflared 這類隧道）。 BLUEBUBBLES_PASSWORD — 服務器密碼（匹配 ?guid= query）。 BLUEBUBBLES_DEFAULT_CHAT_GUID — 默認 chat GUID （例如 iMessage;-;+15551234567）。
設置歸屬: 設置 → 消息渠道

`MATRIX_HOMESERVER` / `MATRIX_ACCESS_TOKEN` / `MATRIX_USER_ID` / `MATRIX_DEFAULT_ROOM_ID`

Matrix — 聯邦式 client-server API。入站作為 long-poll 守護進程運行（無 HTTP webhook），由 MESSAGING_MATRIX_INBOUND 門控。

消費方: src/messaging/matrix.ts + src/messaging/inbound/matrix-daemon.ts.
格式: MATRIX_HOMESERVER — homeserver URL（例如 https://matrix.org）。 MATRIX_ACCESS_TOKEN — 長效 access token。使用 Bearer 頭，而非已棄用的 ?access_token= query 形式。 MATRIX_USER_ID — bot 用戶（例如 @bot:example.org）；用於在 /sync 中過濾自環。 MATRIX_DEFAULT_ROOM_ID — 默認 room id（例如 !abc:example.org）。
Caveats: 此網關不支持端到端加密（E2EE）
房間。只有明文房間才會發出守護進程能消費的
m.room.message 事件。
設置歸屬: 設置 → 消息渠道

`MESSAGING_MATRIX_INBOUND`

Matrix /sync 守護進程的 kill switch。

作用: 設置後，app 啟動時會開啟 long-poll 監聽器，把 Matrix 房間消息發進 agent-loop 橋接。
消費方: src/messaging/inbound/matrix-daemon.ts，經 src/app.ts 中 provider 註冊表的 inboundDaemon 枚舉。
格式: 1/true/yes/on（大小寫不敏感）。
設置歸屬: 設置 → 偏好（schema 鍵）

`MESSAGING_TELEGRAM_POLLING` / `MESSAGING_DISCORD_GATEWAY` / `MESSAGING_SLACK_SOCKET` / `MESSAGING_MATTERMOST_WS` / `MESSAGING_QQ_WS` / `MESSAGING_DINGTALK_STREAM` / `MESSAGING_LARK_WS`

客戶端出站的入站守護進程 — 覆蓋開關。

這些平臺同時支持 webhook（平臺向公網 URL 連接進來）
和客戶端出站守護進程（agent 連接出去
並持有一個長連接 / 輪詢）。守護進程正是讓雙向聊天
在無公網 IP 的個人機器上工作的關鍵——無隧道、無第三
方。
默認情況下，當某平臺的出站憑據已配置，且沒有為其
接入公網 webhook（即其 webhook 簽名 secret 未設置，或
MESSAGING_INBOUND_ENABLED 關閉）時，每個守護進程自動啟動。
為某平臺配置 webhook，則它改為保持 webhook
入站。這些開關是對該自動決策的顯式覆蓋，
為三態： - 未設置 / 空 → auto（上面的默認） - 1/true/yes/on → 強制守護進程開啟 - 0/false/no/off → 強制守護進程關閉（僅保留 webhook） MESSAGING_TELEGRAM_POLLING — Telegram getUpdates long-poll （src/messaging/inbound/telegram-daemon.ts）。Webhook 信號： TELEGRAM_WEBHOOK_SECRET。 MESSAGING_DISCORD_GATEWAY — Discord Gateway WebSocket；還會送達 Interactions webhook 無法送達的普通 channel / DM 消息（src/messaging/inbound/discord-daemon.ts）。需要在 Discord 開發者門戶啟用特權的 "Message Content" intent。 Webhook 信號：DISCORD_APPLICATION_PUBLIC_KEY。 MESSAGING_SLACK_SOCKET — Slack Socket Mode；需要 SLACK_APP_TOKEN （src/messaging/inbound/slack-daemon.ts）。Webhook 信號： SLACK_SIGNING_SECRET。 MESSAGING_MATTERMOST_WS — Mattermost v4 WebSocket bot；還能觸達 outgoing-webhook 路徑無法觸達的 DM / 私有 channel （src/messaging/inbound/mattermost-daemon.ts）。Webhook 信號： MATTERMOST_OUTGOING_WEBHOOK_TOKEN。 MESSAGING_QQ_WS — QQ v2 gateway WebSocket （src/messaging/inbound/qq-daemon.ts）。無 webhook 專屬信號（QQ 的 webhook 複用出站的 QQ_BOT_APP_SECRET），因此只要配置了 QQ 就優先用 gateway 守護進程；設 MESSAGING_QQ_WS=0 改用 webhook。 MESSAGING_DINGTALK_STREAM — DingTalk Stream Mode；需要 DINGTALK_STREAM_APP_KEY / _SECRET （src/messaging/inbound/dingtalk-daemon.ts）。DINGTALK_WEBHOOK_SECRET 為出站發送簽名、非 webhook 入站，因此不會抑制守護進程；設 MESSAGING_DINGTALK_STREAM=0 改用 webhook。 MESSAGING_LARK_WS — 經官方 SDK 的 Lark / 飛書長連接（src/messaging/inbound/lark-daemon.ts）。Webhook 信號： LARK_VERIFICATION_TOKEN。
設置歸屬: 非用戶設置項

`MESSAGING_INBOUND_TRANSCRIBE`

對入站消息啟用語音轉寫。需要 OPENAI_API_KEY。

作用: 設為 1/true/yes/on 時，入站語音附件會被下載、經 OpenAI Whisper 轉寫，且轉寫文本填入 InboundMessage.text。原始音頻保留在 attachments 中，以便下游消費方重放。
消費方: src/messaging/inbound/transcribe.ts（在後續工作中由入站消息歸一化器調用）。
未設置時: 語音附件到達時 text 為空，由調用方自行負責其想要的路由。
格式: 1/true/yes/on（大小寫不敏感）。
設置歸屬: 設置 → 偏好（schema 鍵）

`MESSAGING_VOICE_REPLY`

在流式文本之外，用一個語音回覆附件回應入站語音消息。

作用: agent 的文本回復定稿後，該回復會被合成為音頻，並作為語音（或 audio/file，視能力而定）附件發回同一 channel/thread。僅當入站消息本身含有一個已轉寫的語音附件時才觸發。TTS 失敗絕不會破壞文本回復。
消費方: src/messaging/inbound/agent-bridge.ts，經 voice-delivery helper。需要已配置的語音 provider （ELEVENLABS_API_KEY 或 OPENAI_API_KEY）。
格式: 1/true/yes/on（大小寫不敏感）。
設置歸屬: 設置 → 偏好（schema 鍵）

`ELEVENLABS_API_KEY`

ElevenLabs 語音平臺 key。

作用: 跨網關 /v1/voice/* 端點、web 朗讀和 messaging 語音回覆的語音合成（TTS，eleven_turbo_v2_5）與轉寫（STT，Scribe）的首選 provider。設置後，語音上 ElevenLabs 會優先於 OpenAI 被自動選中（延遲更低）； OpenAI 仍為回退，也是唯一能生成 OGG/Opus 語音消息（Telegram）的 provider。
消費方: src/voice/resolve.ts.
未設置時: 語音回落到 OPENAI_API_KEY；若那個也未設置，語音功能不可用（清晰報錯，不崩潰）。
格式: 來自 https://elevenlabs.io 的 sk_...。
設置歸屬: 非用戶設置項

`VOICE_COMPOSER_STT_PROVIDER` / `VOICE_COMPOSER_STT_MODEL` / `VOICE_CONVERSATION_STT_PROVIDER` / `VOICE_CONVERSATION_STT_MODEL` / `VOICE_FILE_STT_PROVIDER` / `VOICE_FILE_STT_MODEL` / `VOICE_REPLY_TTS_PROVIDER` / `VOICE_REPLY_TTS_MODEL`

按場景配置語音 Provider 與模型。

作用: 分別配置輸入框聽寫、免手動語音對話、完整音頻文件/消息以及 Agent 語音回覆。Provider 可為 auto、openai 或 elevenlabs。
Defaults: 輸入框/對話默認 auto + gpt-live-transcribe；文件/消息默認 auto + gpt-transcribe；回覆默認 auto + 實際 Provider 的推薦 TTS 模型。
Compatibility: VOICE_STT_PROVIDER/MODEL 僅作為文件場景兼容別名；VOICE_TTS_PROVIDER/MODEL 僅作為回覆場景兼容別名。場景變量優先。
消費方: src/voice/resolve.ts 與 /v1/voice/* Gateway 路由。
設置歸屬: 設置 → 偏好（schema 鍵）

`VOICE_TTS_PROVIDER`

固定語音合成廠商。

作用: 僅對 TTS 覆蓋自動選擇（ElevenLabs 優先、 OpenAI 回退）。
消費方: src/voice/resolve.ts（運行時 preference voice.ttsProvider）。
格式: auto | elevenlabs | openai。默認：auto。
設置歸屬: 設置 → 偏好（schema 鍵）

`VOICE_TTS_VOICE`

朗讀回覆時使用的 voice id。

作用: 作為其原生 voice id 傳給主 TTS provider （ElevenLabs voice id，或 OpenAI voice 名稱如 alloy）。回退 provider 使用各自的默認 voice。
消費方: src/voice/resolve.ts（運行時 preference voice.ttsVoice）。
未設置時: 項目默認 voice / OpenAI "alloy"。
設置歸屬: 設置 → 偏好（schema 鍵）

`VOICE_TTS_MODEL`

主 provider 的 TTS model id。

作用: ElevenLabs model（也是 Settings -> Voice models 中默認選中的），以及 OpenAI 為主時的 OpenAI model。 ElevenLabs 可選項：eleven_v3（最擬人，默認）、 eleven_multilingual_v2、eleven_turbo_v2_5、eleven_flash_v2_5。
消費方: src/voice/settings.ts（ElevenLabs base）+ src/voice/resolve.ts（OpenAI，運行時 preference voice.ttsModel）。
未設置時: eleven_v3（ElevenLabs）/ gpt-4o-mini-tts（OpenAI）。
設置歸屬: 設置 → 偏好（schema 鍵）

`VOICE_TTS_STABILITY` / `VOICE_TTS_SIMILARITY_BOOST` / `VOICE_TTS_STYLE` / `VOICE_TTS_SPEAKER_BOOST` / `VOICE_TTS_SPEED` / `VOICE_TTS_FAST_FIRST`

語音送達默認值（ElevenLabs voice_settings）。每個設定基線；Settings -> Voice models 滑塊在其之上按用戶覆蓋。

消費方: src/voice/settings.ts. VOICE_TTS_STABILITY 0..1 — 越低越生動，越高越穩定（默認 0.6） VOICE_TTS_SIMILARITY_BOOST 0..1 — 對該 voice 音色的貼合度（默認 0.8） VOICE_TTS_STYLE 0..1 — 表現力 / 個性（默認 0.45） VOICE_TTS_SPEAKER_BOOST 1/0 — 清晰度增強（默認開啟） VOICE_TTS_SPEED 0.7..1.2 — 播放速率（默認 0.9） VOICE_TTS_FAST_FIRST 1/0 — 用最快的 model 朗讀每條回覆的第一句，讓語音更快開始（默認開啟）
設置歸屬: 非用戶設置項

`VOICE_STT_PROVIDER`

固定語音轉文字廠商。

消費方: src/voice/resolve.ts（運行時 preference voice.sttProvider）。
格式: auto | elevenlabs | openai。默認：auto。
設置歸屬: 設置 → 偏好（schema 鍵）

`VOICE_FFMPEG_PATH`

用於語音轉碼的可選 ffmpeg 二進制。

作用: AMR 語音格式（WeCom、無內置轉寫的 WeChat OA）在 STT 前經 ffmpeg 中轉，WeCom 語音回覆把 mp3 → AMR 轉碼。未設置時，在 PATH 上查找 "ffmpeg"；當兩者都無法解析時，這些轉碼會被跳過，受影響的平臺優雅降級。
消費方: src/messaging/audio-transcode.ts.
設置歸屬: 非用戶設置項

`VOICE_STT_MODEL`

主 provider 的 STT model id。

消費方: src/voice/resolve.ts（運行時 preference voice.sttModel）。
未設置時: scribe_v1（ElevenLabs）/ gpt-4o-mini-transcribe（OpenAI）。
設置歸屬: 設置 → 偏好（schema 鍵）

`TWITTERAPI_API_KEY`

第三方 Twitter/X 抓取 provider。

作用: 經 twitterapi.io 抓取器讀取 tweet、profile 和搜索結果（有速率限制，無需 OAuth）。
消費方: src/tools/providers/twitterapi.ts。經 requires_env 門控 research.social.twitter skill。
何時設置: 你希望 research.social skill 在不擁有開發者 app 的情況下拉取實時 Twitter 數據。
未設置時: research.social.twitter 從 skill catalog 中隱藏。
格式: 來自 https://twitterapi.io 的不透明 API key。
與 X_API_BEARER_TOKEN（官方 X API）不同——這個
走第三方抓取器，另一個直接對接 api.x.com/2。
可設其一或兩者都設。
設置歸屬: 設置 → API 密鑰

`X_API_BEARER_TOKEN`

X（Twitter）官方 API bearer token。

作用: 對 api.x.com/2 的只讀、app-only 訪問（搜索、lookup、timeline）。
消費方: src/tools/providers/x-api.ts。經 requires_env 門控內置的 x.api skill。
何時設置: 你在 https://developer.x.com 上擁有一個開發者 app，並希望 agent 對接官方 API，以替代（或補充）twitterapi.io 抓取器。
未設置時: x.api skill 從 catalog 中隱藏。
格式: 來自 console.x.com 的 Bearer token——長的不透明字符串。
設置歸屬: 設置 → API 密鑰

`GLASSNODE_API_KEY`

Glassnode 鏈上分析。

作用: 鏈上指標端點（SOPR、MVRV、realised cap、flows 等）。
消費方: src/tools/providers/glassnode.ts。經 requires_env 門控 research.onchain.glassnode skill。
何時設置: 你有 Glassnode 訂閱，並希望 agent 直接引用鏈上指標。
未設置時: glassnode skill 從 catalog 中隱藏。
格式: 來自 https://glassnode.com 的不透明 API key。
設置歸屬: 設置 → API 密鑰

`QDRANT_URL` / `QDRANT_API_KEY`

供 research KB 使用的向量數據庫。

作用: (1) research.knowledge_base skill —— 教 agent 從終端經 curl 查詢運營方精選的 Qdrant collection（news、 projects、people、docs）。 (2) kb_search 工具 —— 對同一 Qdrant 查詢路徑的一等封裝，由 institution 模式的分析師（news / fundamentals / sentiment）在回落到 web_search 之前使用。
消費方: src/skills/builtin/research-knowledge-base.ts（skill）和 src/tools/kb-search.ts（institution 模式工具）。兩者都門控於 QDRANT_URL 存在；kb_search 還需要一個已配置的 embeddings provider（EMBEDDING_PROVIDER + EMBEDDING_API_KEY）。
何時設置: 你希望 agent 查詢一個已由 v1 填充的 Qdrant 實例，以獲取比公網搜索更新鮮 / 更聚焦的 news + project 事實。
未設置時: knowledge_base skill 從 catalog 中隱藏，且 kb_search 工具不註冊。Institution 分析師回落到既有的 web_search（行為零變化）。
格式: QDRANT_URL 是絕對 URL（https://xxx.qdrant.io）。 QDRANT_API_KEY 可選——僅當你的部署需要認證時才設置（Qdrant Cloud 需要；本地 docker 通常不需要）。
設置歸屬: 非用戶設置項 (QDRANT_URL)
設置歸屬: 設置 → API 密鑰 (QDRANT_API_KEY)

`KB_EMBEDDING_PROVIDER` / `KB_EMBEDDING_API_KEY` / `KB_EMBEDDING_MODEL` / `KB_EMBEDDING_DIM`

僅針對 KB 的 Embedder 覆蓋，只作用於 kb_search。

作用: 在把 kb_search query 字符串發往 Qdrant 之前，用哪個 embedder 對其做 embedding。該 embedder 必須與最初填充 Qdrant collection 的那個一致—— 維度不匹配會導致 Qdrant 在每次調用時返回 400。
何時設置: 僅當你的 kb_search Qdrant 實例是用與你 memory 所用（EMBEDDING_PROVIDER / EMBEDDING_MODEL）不同的 embedder 填充時。常見情形： v1 Qdrant 用 OpenAI text-embedding-3-small（1536d）填充，而你的 memory 跑 voyage-3（1024d）。
未設置時: kb_search 回落到共享 embedder （EMBEDDING_PROVIDER + EMBEDDING_API_KEY + EMBEDDING_MODEL + EMBEDDING_DIM）。若 memory 和 KB 共用同一 model，則無需覆蓋。
格式: 接受值與上面的 EMBEDDING_* 家族完全相同。 KB_EMBEDDING_API_KEY 未設置時默認取 EMBEDDING_API_KEY （因此 OpenAI 用戶只需設置 provider + model 覆蓋）。
設置歸屬: 非用戶設置項 (KB_EMBEDDING_PROVIDER, KB_EMBEDDING_MODEL, KB_EMBEDDING_DIM)
設置歸屬: 設置 → API 密鑰 (KB_EMBEDDING_API_KEY)

`E2B_API_KEY`

Kernel 雲瀏覽器協調器（https://e2b.dev）。

作用: 讓工作臺啟動 Kernel 雲端 Chromium（協調器沙箱）。需配對 KERNEL_API_KEY。此密鑰不會把 shell、文件或 execute_code 移出 gateway 宿主。
消費方: 由工作臺雲瀏覽器運行時（Kernel bootstrap）使用。調用時解析（Settings → API Keys 中新增的密鑰無需重啟即生效）。
何時設置: Desktop/CLI 想用 Kernel Live View 而不是本機瀏覽器時設置。Hosted Web Browser 的協調器也需要它。
未設置時: 雲瀏覽器 placement 不可用；Desktop/CLI 在宿主允許時保持本機瀏覽器。
格式: 來自 https://e2b.dev 控制台的不透明密鑰。
Safety: 不要為了跑 bash 而把共享 org key 注入 per-user hosted agent。Shell 留在 gateway VM 上。
設置歸屬: 設置 → API 密鑰

`KERNEL_API_KEY`

KERNEL_API_KEY，用於 Web 瀏覽器工作臺的託管 Chromium。

作用: 創建 Web 瀏覽器工作臺使用的 Kernel 雲端 Chromium 會話。同一個會話同時提供嵌入式實時畫面和 Agent 瀏覽器工具使用的 CDP 端點。
消費方: 由工作臺雲瀏覽器運行時使用。調用時動態解析，因此在 Settings > API Keys 保存後無需重啟即可生效。
何時設置: 當 Web 用戶需要交互式遠端瀏覽器時設置。該運行時還需要 E2B_API_KEY 來啟動 kernel-browser 協調器。
未設置時: Web 瀏覽器顯示配置引導，並提供 Kernel 官方密鑰文檔和控制台鏈接。桌面端原生瀏覽器仍可使用。
格式: 在 https://dashboard.onkernel.com 創建的不透明 API 密鑰。
設置歸屬: 設置 → API 密鑰

`WORKBENCH_E2B_SESSION_IDLE_SECONDS`

Web 雲端資源暫停寬限期。

作用: 最後一個 Web 客戶端離開 Chat 或 Institution 會話後，Gateway 等待多久再暫停該會話的雲端 Browser。暫停保留 Kernel 會話直至超時；gateway 上的 shell 不受影響。
消費方: 由 Preferences computer.cloudSessionIdleSeconds → Gateway 工作臺雲端資源回收器使用。桌面端原生 Browser 和 Computer 會話不使用此設置。
未設置時默認: 60 秒（1 分鐘）。
何時設置: 調高可在較慢的會話切換中保留雲端狀態，調低可更快暫停。優先用 Settings → Preferences；env 為覆蓋項。在延遲到期前返回會取消待執行的暫停。
格式: 0 到 3600 的有限秒數。無效值或負數使用默認的 60 秒。Terminal 不受影響。
設置歸屬: 設置 → 偏好（schema 鍵）

`MINARA_HOST_KIND`

覆蓋 Gateway 宿主分類。

作用: 強制 Browser/Computer 後端選擇使用的宿主類型：desktop | local-cli | hosted-e2b | web-remote。
消費方: 由 src/computer/host.ts（currentHostKind）使用。放置策略、capability 端點、Chromium 啟動策略與私網 URL 規則都讀此分類。
未設置時默認: 未設置時由 MINARA_DESKTOP_PID / computer bridge / CDP、E2B_SANDBOX_ID 或 CREDENTIALS_DEK+/data、再 GATEWAY_HOST 推斷，否則為 local-cli。
何時設置: 僅用於測試與運維診斷。生產 Desktop 與 hosted-e2b 應依賴自動信號。
格式: 取值為：desktop、local-cli、hosted-e2b、web-remote 之一。
設置歸屬: 非用戶設置項

`MINARA_COMPUTER_BACKEND`

固定會話運行時（local / cloud / docker）。

作用: 將會話運行時（瀏覽器、shell 與文件）固定為 local、cloud 或 docker，或保持 auto（Desktop 本地優先）。Shell 與文件始終跟隨 gateway 進程，除非固定 docker。cloud 只選擇 Kernel 雲瀏覽器；GUI 電腦操控僅 Desktop。hosted 上 bash 跑在 agent VM，瀏覽器走 cloud。
消費方: 由 Preferences computer.backend → src/computer/backends.ts（readSessionBackendOverride）與會話運行時 placement（經 SessionRuntimeStore）使用。
未設置時默認: 未設置時自動：hosted → 本地 shell + 雲瀏覽器；Desktop 在原生橋可用時優先本地（即使已配置雲密鑰）；Desktop 無橋且同時配置 E2B_API_KEY + KERNEL_API_KEY 時瀏覽器走 cloud，否則 local；local-cli 始終保持 local（密鑰僅使顯式 Cloud 瀏覽器可選）。auto 從不選擇 docker — 需顯式固定 docker。
何時設置: 優先用 Settings → Preferences → 會話運行時。設為 cloud 強制 Kernel 瀏覽器（shell 仍在本機）；設為 docker 強制本地容器後端（需 MINARA_DOCKER_SANDBOX_IMAGE）；設為 local 強制 Desktop 橋（橋缺失時明確失敗）。
格式: auto、local、cloud 或 docker。空 / 未設置 = auto。
設置歸屬: 設置 → 偏好（schema 鍵）

`MINARA_DOCKER_SANDBOX_IMAGE`

Docker 執行後端鏡像。

作用: 粘性 docker 執行後端（同一容器內的 shell + 文件 + execute_code）所用的容器鏡像。通過 Preferences computer.backend=docker（或 MINARA_COMPUTER_BACKEND=docker）選擇——沒有按次的 environment 覆蓋。加固：丟棄除包管理器所需最小集之外的所有 capability，no-new-privileges、PID 限制、大小受限的 /tmp；無宿主機 bind mount，無宿主機 env 轉發。每個 chat 會話一個容器，跨調用複用，空閒 15 分鐘後移除。
消費方: src/tools/_execution/docker-environment.ts，經 src/app.ts 中接入的 ExecutionRouter。在調用時解析。
何時設置: 你希望在不另開雲 VM 的情況下，為不受信任代碼提供強本地隔離。需要一個運行中的 Docker（或 Podman）守護進程；CLI 會在 PATH 和常見 Docker Desktop 位置被發現。
未設置時: docker 後端不可用；code/shell 在網關宿主機上運行。
格式: 任何可拉取的、含你所需語言運行時的鏡像引用，例如 python:3.12-slim 或 node:22-slim。
Safety: 與本地隔離相同姿態——容器即安全邊界，除非通過 environment_provision_credentials 顯式注入，否則不持有宿主機憑證。僅通過 Preferences computer.backend=docker 選擇 docker（無按次覆蓋）。
設置歸屬: 非用戶設置項

`MINARA_GITHUB_APP_CLIENT_ID`

Coding GitHub 登錄使用的公開客戶端 ID。

作用: 啟用供結構化 HTTPS Git 和 Pull Request 使用的 GitHub App 設備授權憑據 Provider。
消費方: Desktop 發佈 CI 將其嵌入 product-config.json；Desktop 把這個公開值傳給 src/app/bootstrap.ts 以裝配 CodingGitService。Shell 或項目 .env 仍可用於開發覆蓋。
何時設置: 運營方已註冊啟用設備授權並具有經審核倉庫權限的 Minara GitHub App 時設置。
未設置時: 未設置時，連接 GitHub 會提示需要運營配置；本機 SSH 不受影響。
格式: 可選的產品 GitHub App client id（例如 Iv1.example），不是 client secret。
設置歸屬: 非用戶設置項

`MINARA_FILTERED_SSH_AGENT`

Desktop 內部 SSH 權限標記。

作用: 標記 SSH_AUTH_SOCK 是由 Desktop 管理的過濾端點，只暴露所有者選中的身份。
消費方: src/gateway/api.ts 在裝配本機 SSH 憑據 Provider 時讀取。
何時設置: 不要手動設置；僅當過濾 SSH agent 代理運行時由 Minara Desktop 注入。
未設置時: 未設置時，本機 SSH 憑據 Provider 保持不可用，不會信任未過濾的環境 SSH agent。
格式: 內部值 1；其他值均視為未設置。
設置歸屬: 非用戶設置項

`MINARA_CLOUD_CREDENTIAL_FILES`

provisioned 進 docker 執行容器的憑據文件 —— 由運營方聲明、僅上傳。

作用: environment_provision_credentials 上傳進雲 VM 的文件集，以便在那裡運行的代碼可以認證。 agent 無法選擇路徑——只有此配置可以。每個條目把 data dir 內的一個文件映射到一個絕對的 VM 目標。本地路徑必須相對於 MINARA_DATA_DIR；絕對路徑、 .. 穿越、以及逃出 data dir 的 symlink 會在解析時逐條被拒。Provisioned 的 VM 路徑僅上傳： environment_pull_file 拒絕把它們讀回，且文件內容絕不進入模型 context。
消費方: src/tools/_execution/credential-provision.ts，經 src/tools/environment-files.ts。
何時設置: 你在雲 VM 中運行的代碼需要一個 API key 文件 / token 文件。優先只讀、低影響面的憑據—— VM 擁有完整的網絡出站。切勿在此聲明錢包 key 或資金流轉憑據。
未設置時: environment_provision_credentials 報告無文件；雲運行是無憑據的（默認姿態）。
格式: JSON 數組 {"local": "<relative path>", "remote": "/abs/vm/path"}。例如：[{"local":"cloud-creds/market.json","remote":"/root/.creds/market.json"}]
設置歸屬: 非用戶設置項

本頁目錄