内置工具

内置工具（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"}]
设置归属: 非用户设置项

本页目录