特性标志
除了基础的环境变量配置外,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_apps | MCP 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。它控制创建者的灰度开放范围,不控制访客对已有分享的访问。
服务端门控分别检查两层条件:
- 部署支持:
ENABLE_BUSINESS_FEATURES必须为true。否则,新建分享和访客访问均返回FORBIDDEN,不会进入灰度开关判断。 - 创建者灰度:新建或重新启用分享还要求创建者的
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 启用前:
- 将
APP_URL设置为调用方使用的公网地址,Webhook URL 由它生成。 - 配置
KEY_VAULTS_SECRET,用于加密 Webhook 密钥,并在部署更新时保留它。 - 可选:配置 QStash,让唤醒和积压调用的恢复按计划执行。未配置时,唤醒在应用进程内执行,恢复依赖应用请求触发。
- 设置
FEATURE_FLAGS="+webhook"并重启应用。
打开一个 Agent,进入助理档案 → Webhook,创建 Webhook 后点击「发送测试」:在「最近调用」中应能看到这次调用已运行,并链接到 Agent 回复所在的话题。
关闭开关后,Webhook 与自动化入口隐藏,调用不再触发 Agent 运行。调用仍会通过认证、入库并得到确认,但会被跳过、不消耗额度;Webhook 与其 URL 会保留,重新开启后恢复工作。
MCP Events:部署前提
MCP Events 的要求比 Agent Webhook 多。为它启用 webhook 前:
- 将
APP_URL设置为 MCP 服务器能访问的公网 HTTPS 地址。localhost、私有域名和 IP 字面量不支持。 - 配置
KEY_VAULTS_SECRET,用于加密 webhook 签名密钥。按环境变量说明生成密钥,并在部署更新时保留它。 - 配置 QStash,确保续订、退订重试和积压事件恢复有定时触发。Docker 启动器每五分钟注册一次 sweep;其他部署需自行配置定时任务。没有 QStash 时,这些维护依赖应用请求触发,执行时机没有保证。
- 设置
FEATURE_FLAGS="+webhook"并重启应用。连接已认证、支持 SEP-3415 webhook 事件的远程 HTTP MCP 服务器,然后刷新连接器工具。
在对话里请求订阅事件并批准后,打开设置 → 自动化,确认状态为生效中,再从上游触发一次事件,确认原 Topic 收到事件与 Agent 回复。永不过期订阅不做定时健康检查;投递中断时,在自动化列表点击「检查」恢复投递。
关闭开关后,工具与自动化入口会隐藏,受影响用户的事件不再触发 Agent 运行,也不再续订。入站事件仍会验签和入库,但会被跳过,不消耗额度。订阅记录保留,有限有效期的订阅可能在关闭期间过期。
重新开启后,有效订阅会恢复事件触发,定时续订会尝试从保存的 cursor 恢复过期订阅。不再需要的订阅可以在关闭开关前后任意时刻删除。