LobeHub
LobeHub

特性标志

除了基础的环境变量配置外,LobeHub 还提供了一些特性标志(Feature Flags),用于控制是否全局启用某个功能,或者根据需要对特定用户群体或环境启用或禁用功能。

核对部署版本

开关名称和默认值可能随版本变化。应检查所部署版本的定义,不能只依赖最新 main 分支。功能状态标签用于描述开放范围,不是开关名称。本页不提供未经核验的交互式助理分享开关。

特性标志环境变量 FEATURE_FLAGS

  • 类型:可选
  • 描述:用于控制 LobeHub 的特性功能,支持多个功能标志,使用 + 增加一个功能,使用 - 来关闭一个功能,多个功能标志之间使用英文逗号 , 隔开,最外层建议添加引号 " 以避免解析错误。
  • 默认值:-
  • 示例:"-welcome_suggest"

FEATURE_FLAGS 控制这里列出的布尔开关,不能替代服务配置、权限、凭据或部署要求。仅打开一个开关,不代表功能已经可用。

你可以通过上述配置语法来实现更多的功能组合。所有的功能配置项都是布尔类型,通过 + 来启用,通过 - 来关闭。

注意:与 OPENAI_MODEL_LIST 变量不同,FEATURE_FLAGS 变量不支持 all 关键字,你需要手动控制所有的功能标志(否则它们会采用对应的默认值)。

配置项解释默认值
check_updates允许检查更新。开启
provider_settings控制模型供应商设置的显示。开启
openai_api_key允许用户自定义 OpenAI API Key。开启
openai_proxy_url允许用户自定义 OpenAI 代理 URL。开启
api_key_manage控制 API 密钥管理页面 (/profile/apikey) 的访问。关闭
agent_share控制新建或重新启用交互式助理分享;还需部署支持,详见下文边界。关闭
agent_llm_relay对只有用户设备能访问的模型服务商(本地 Ollama / LM Studio、私网地址),由发起运行的客户端执行单次模型调用,助理循环仍在服务端运行;这类运行需要有打开的 LobeHub 客户端。关闭
agent_deferred_init普通聊天发送在消息落库后立即返回,工具发现和上下文组装放到第一个助理步骤中执行,发送不再等待。需要队列模式的助理运行时。关闭
agent_deferred_hetero_dispatch普通聊天发给在线设备上的异构助理(Claude Code、Codex 等)时,不等设备接收任务就立即返回;派发在响应后执行,失败会显示在助理消息上。关闭
dashboard看板:首页与项目看板页面、监控组件侧边栏、对话内的组件预览,以及用于搭建监控组件的 builtin-dashboard 助理工具。关闭时以上入口均隐藏,组件与看板相关接口返回 FORBIDDEN;已发布的组件仍按计划刷新。关闭
mcp_appsMCP Apps:MCP 服务器为工具结果声明了交互页面(ui://)时,在对话中渲染该页面(服务器提供的 HTML,运行在沙箱 iframe 中)。关闭时按普通工具结果显示,服务端也不再向 MCP 服务器声明支持 MCP Apps。关闭
webhook入站 Webhook 唤醒 Agent。MCP Events:Agent 订阅远程连接器事件,并在原 Topic 中运行;创建订阅遵循用户的工具审批设置。Agent Webhook:在助理档案 → Webhook 中管理、任意外部系统都能调用的 URL,调用即运行 Agent。每次事件或调用会消耗额度。需公网 APP_URL 与密钥加密配置;MCP Events 还需支持 webhook 事件的已认证 MCP 服务器。关闭后入口隐藏,投递仍会记录但不运行。关闭
edit_agent允许用户编辑助手。开启
ai_image控制 AI 图像生成功能和页面 (/image)。开启
speech_to_text启用语音转文本功能。开启
token_counter保留用于令牌计数器显示。开启
welcome_suggest显示欢迎建议。开启
changelog控制更新日志弹窗 / 页面的显示。开启
market启用助手市场功能。开启
knowledge_base启用知识库功能。开启
rag_eval控制 RAG 评估功能 (/repos/[id]/evals)。关闭
cloud_promotion控制用户菜单中云服务推广链接的显示。关闭
commercial_hide_github隐藏设置页面底部的 GitHub 相关链接(需要商业授权)。关闭
commercial_hide_docs隐藏文档和帮助菜单,包括更新日志、文档和反馈(需要商业授权)。关闭

交互式助理分享:部署与灰度边界

以下行为已按提交 659db0780b263f023019337a48f23e17e77e260d 核验,其他版本可能不同。

agent_share 定义的默认值为 false。它控制创建者的灰度开放范围,不控制访客对已有分享的访问。

服务端门控分别检查两层条件:

  1. 部署支持:ENABLE_BUSINESS_FEATURES 必须为 true。否则,新建分享和访客访问均返回 FORBIDDEN,不会进入灰度开关判断。
  2. 创建者灰度:新建或重新启用分享还要求创建者的 enableAgentShare === true。值为 false 或未定义均拒绝。运行时配置中的数组值表示获准创建者的用户 ID,不是访客名单。

在已核验的开源代码中,ENABLE_BUSINESS_FEATURES 是值为 false 的代码常量, 不是环境变量。FEATURE_FLAGS="+agent_share" 无法绕过这层部署门控, 不能使标准自托管部署获得交互式助理分享功能。

商用功能常量定义了这层边界。本指南不提供修改代码绕过边界的操作步骤。

在支持该功能的部署中,将创建者移出灰度范围,本身不会撤销已有分享。访客访问已有分享或通过它聊天,不要求访客拥有该开关。所有者仍可管理、预览或撤销已有分享;这些操作仍受各自既有的授权检查约束。

分享路由在 enableShare 和将 updateVisibility 设为 link 时检查创建者门控。改为 private 不要求灰度开关,但会阻止访客访问。因此,关闭 agent_share 不能替代关闭某个具体分享。

你可以随时检查 featureFlags 以获取最新的特性标志列表。

Agent Webhook:部署前提

Agent Webhook 与 MCP Events 共用 webhook 开关,默认关闭。为 Agent Webhook 启用前:

  1. 将 APP_URL 设置为调用方使用的公网地址,Webhook URL 由它生成。
  2. 配置 KEY_VAULTS_SECRET,用于加密 Webhook 密钥,并在部署更新时保留它。
  3. 可选:配置 QStash,让唤醒和积压调用的恢复按计划执行。未配置时,唤醒在应用进程内执行,恢复依赖应用请求触发。
  4. 设置 FEATURE_FLAGS="+webhook" 并重启应用。

打开一个 Agent,进入助理档案 → Webhook,创建 Webhook 后点击「发送测试」:在「最近调用」中应能看到这次调用已运行,并链接到 Agent 回复所在的话题。

关闭开关后,Webhook 与自动化入口隐藏,调用不再触发 Agent 运行。调用仍会通过认证、入库并得到确认,但会被跳过、不消耗额度;Webhook 与其 URL 会保留,重新开启后恢复工作。

MCP Events:部署前提

MCP Events 的要求比 Agent Webhook 多。为它启用 webhook 前:

  1. 将 APP_URL 设置为 MCP 服务器能访问的公网 HTTPS 地址。localhost、私有域名和 IP 字面量不支持。
  2. 配置 KEY_VAULTS_SECRET,用于加密 webhook 签名密钥。按环境变量说明生成密钥,并在部署更新时保留它。
  3. 配置 QStash,确保续订、退订重试和积压事件恢复有定时触发。Docker 启动器每五分钟注册一次 sweep;其他部署需自行配置定时任务。没有 QStash 时,这些维护依赖应用请求触发,执行时机没有保证。
  4. 设置 FEATURE_FLAGS="+webhook" 并重启应用。连接已认证、支持 SEP-3415 webhook 事件的远程 HTTP MCP 服务器,然后刷新连接器工具。

在对话里请求订阅事件并批准后,打开设置 → 自动化,确认状态为生效中,再从上游触发一次事件,确认原 Topic 收到事件与 Agent 回复。永不过期订阅不做定时健康检查;投递中断时,在自动化列表点击「检查」恢复投递。

关闭开关后,工具与自动化入口会隐藏,受影响用户的事件不再触发 Agent 运行,也不再续订。入站事件仍会验签和入库,但会被跳过,不消耗额度。订阅记录保留,有限有效期的订阅可能在关闭期间过期。

重新开启后,有效订阅会恢复事件触发,定时续订会尝试从保存的 cursor 恢复过期订阅。不再需要的订阅可以在关闭开关前后任意时刻删除。