OpenBot配置参考：环境变量与YAML配置完整指南

OpenBot配置参考环境变量与YAML配置完整指南【免费下载链接】OpenBotOpen-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.项目地址: https://gitcode.com/gh_mirrors/openb/OpenBotOpenBot 是一款每个 AI 同事都拥有自己电脑的开源项目其全部行为都通过环境变量与YAML 配置租户包来定义。本指南带你 10 分钟读完 OpenBot 配置哪些变量是启动必需项、.env里该怎么填、租户包的 5 个 YAML 文件各管什么以及如何安全地修改配置并重启生效。3 步启动OpenBot 配置的最快路径 OpenBot 的 API 服务器在启动时会同时校验环境变量和租户包配置错误会直接拒绝启动并说明原因——这比运行到一半才报错安全得多。复制环境变量模板cp .env.example .env填入必需值见下表运行启动脚本bash scripts/start.sh完整说明见官方文档docs/configuration.md模板文件带大量中文注释可直接阅读.env.example。环境变量配置5 个启动必需项以下变量缺失任意一个服务器都会拒绝启动变量作用DATABASE_URLPostgreSQL 连接串KEY_ENCRYPTION_KEY凭证加密密钥openssl rand -base64 32生成INTELLIGENCE_API_URLCopilotKit Intelligence API 地址INTELLIGENCE_GATEWAY_WS_URLIntelligence 实时网关地址INTELLIGENCE_API_KEYIntelligence 项目运行时密钥⚠️ 注意三个INTELLIGENCE_*变量会被作为一个整体校验——只填一半会被判定为配置错误而不是未配置。常用环境变量速查表变量默认值说明PORT3001API 服务器端口TENANT_PACKAGE_DIR../examples/fintech租户包目录OPENAI_API_KEY未设置内置 Agent 与自带 Bot 的默认模型密钥OPENAI_BASE_URL未设置OpenAI 兼容端点网关/代理/自托管模型BOT_PROVIDERopenai框架 Bot 的供应商openai、anthropic或googleBOT_MODEL供应商默认框架 Bot 使用的模型OPENBOT_SINGLE_USER—单管理员模式未配置任何登录方式时必须为trueAGENT_STALL_TIMEOUT_MS未设置关闭Bot 流静默多久后强制结束本轮模板内置 60000OPENBOT_GENERATIVE_UI未设置开启设为false可禁止 Bot 生成自定义界面AUDIT_RETENTION_DAYS未设置审计日志保留天数不设则永久保留MANAGED_AGENT_AG_UI_URL未设置产品内开箱 Bot的 AG-UI 端点需配套MANAGED_AGENT_TOKENAGENT_TOOL_TOKEN未设置Bot 回调调用已授权工具时的密钥start.sh会自动生成并写回.env几个新手容易踩的坑OPENAI_BASE_URL移动的是整个部署API 服务器、agent-bot、agent-langgraph都会读取它一行配置即可把内置 Agent 和 Bot 一起指向网关。模型名原样传递网关若使用命名空间如openai/gpt-5.5BOT_MODEL和model.yaml的default_model都要写完整名称。AGENT_COMPUTER_ALLOW_PRIVATE_HOSTS仅在本地开发使用NODE_ENVproduction下设置它服务器会拒绝启动。认证配置如何为 OpenBot 设置登录方式OpenBot 提供两种模式二选一逻辑非常明确无任何身份供应商→ 必须设置OPENBOT_SINGLE_USERtrue模板默认已开启克隆即可运行配置任意一个供应商Google / Microsoft Entra / Okta→ 登录功能自动开启可同时配置多个配置供应商时还必须同时提供 4 个值缺一即启动失败变量要求BETTER_AUTH_SECRET至少 32 字符签名会话 CookieBETTER_AUTH_URL公开 API 基础地址OAuth 回调返回处INITIAL_ADMIN_EMAILS逗号分隔的管理员邮箱首次登录的唯一提权途径TRUSTED_ORIGINS逗号分隔的应用来源另需包含 OIDC 发现文档中的所有主机各供应商的回调地址格式为BETTER_AUTH_URL/api/auth/callback/provider其中 provider 为google、microsoft或okta。租户包5 个 YAML 文件完全解析 OpenBot 用租户包定义品牌、Agent、频道、模型与技能。示例包位于 examples/fintech/默认由TENANT_PACKAGE_DIR指向examples/fintech/ ├── brand.yaml # 租户与品牌必需 ├── agents.yaml # Agent 清单必需 ├── channels.yaml # 频道定义必需 ├── model.yaml # 模型与凭证引用必需 ├── knowledge.yaml # 知识来源必需 ├── skills.yaml # 技能可选 └── agents/ # 每个 Agent 一个文件可选brand.yaml租户身份与主题定义tenant.id和product_name可选skin.stylesheet注入主题 CSS仅允许:root与.dark块。参考examples/fintech/brand.yaml。agents.yaml如何定义 AI 同事每个 Agent 必需id、name、title、role_description与type两种类型类型额外必需字段说明built-insystem_prompt由本部署运行使用系统提示词remote-ag-uiendpoint外部 AG-UI 端点可接入任意 AG-UI Agent完整示例examples/fintech/agents.yaml。小技巧包内任何${NAME}都会被替换为同名环境变量${NAME:-fallback}在变量缺失时用兜底值。一份租户包因此可同时跑在本地、预发与生产环境——示例包正是靠${MANAGED_AGENT_AG_UI_URL:-}指向箱内 Bot而不强制任何配置。Agent 也可以单独放在agents/目录如 examples/fintech/agents/expense-review.yaml两个文件声明相同id会导致启动失败并点名两个文件。channels.yaml频道与 Agent 的绑定每个频道必需id、name、description、permitted_agents和allowed_groups且permitted_agents中每个条目都必须匹配一个已存在的 Agent id。参考examples/fintech/channels.yaml。model.yaml模型与凭证引用model: provider: openai credential_secret_ref: openai-api-key default_model: gpt-5.6-terracredential_secret_ref是凭证引用而非凭证值切勿把密钥写进 YAML。参考examples/fintech/model.yaml。knowledge.yaml 与 skills.yaml知识与技能knowledge.yaml声明知识来源当前支持google-drive与microsoft-onedrive两种类型可指定根目录。参考examples/fintech/knowledge.yaml。skills.yaml声明带/命令的技能slug、title、summary、instructions可选tools格式为serverId/toolName。声明工具不等于授权——Bot 能调用的永远是技能声明 ∩ 实际授权这让它天然安全。参考examples/fintech/skills.yaml。计算机与监督者进阶环境变量OpenBot 的每个 Bot 可拥有独立电脑浏览器 文件 工具相关变量变量作用AGENT_COMPUTER_URL共享计算机地址不设置则整个功能关闭COMPUTER_TOKEN每次计算机请求必须携带的密钥COMPUTER_MAX_BROWSERS同时运行的浏览器数上限默认 8COMPUTER_BROWSER_MODEheadless默认或headed虚拟显示器支持人工接管COMPUTER_SUPERVISOR_URLSUPERVISOR_TOKEN每 Bot 独立计算机容器的监督者COMPUTER_RUNTIME设为runsc可在 gVisor 下运行AGENT_COMPUTER_POLICYJSON 动作策略deny优先于allow支持enforce与dry-run模式按 Bot 出站代理写在独立的egress.env不是.env因为该文件不含部署密钥EGRESS_PROXY_DEFAULT覆盖所有 BotEGRESS_PROXY_BOT_ID为单个 Bot 指定代理用于网络归因与白名单管理。端口规划与多部署隔离服务默认端口设置变量app浏览器应用3010APP_PORTserverAPI3001SERVER_PORTagent-computer4100COMPUTER_PORTagent-bot4200BOT_PORTagent-langgraph4201LANGGRAPH_PORTsupervisor4500宿主机SUPERVISOR_PORTPostgreSQL5432POSTGRES_PORT同一 Docker 主机跑两套部署时第二套需要独立的COMPOSE_PROJECT_NAME、COMPUTER_NAMESPACE和COMPUTER_IMAGE共享 Intelligence 项目时再加一个DEPLOYMENT_ID它会被写进每个会话 id避免两个部署的对话互相混淆。端口变量与 Compose 地址定义在 docker-compose.yml配置加载逻辑在 server/src/config.ts。配置修改工作流5 步安全变更 ✅编辑对应的.env值或租户包 YAML 文件检查跨文件引用尤其是channels[].permitted_agents中的 Agent id保持凭证值与服务账号 JSON留在 YAML 之外重启 API 服务器——无效配置会阻止启动并说明原因本地开发可跑一遍校验bun run format:check bun run lint bun run typecheck bun run test 记住两条原则密钥进环境变量声明进 YAML改完就重启因为所有校验都发生在启动时。常见问题速答忘了配置登录也忘了开单用户模式服务器拒绝启动并明确告诉你缺什么——这是设计使然防止每个访客都是管理员的静默事故。AGENT_TOOL_TOKEN和MANAGED_AGENT_TOKEN会混淆吗方向相反前者是 Bot 向服务器证明身份后者是服务器向 Bot 证明身份不可互换。改了浏览器模式不生效只影响新创建的计算机容器已存在的会保留到镜像变更或容器重建。更多变量细节逐项查阅 docs/configuration.md 与 .env.example 中的逐行注释。【免费下载链接】OpenBotOpen-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.项目地址: https://gitcode.com/gh_mirrors/openb/OpenBot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考