跳转到主要内容
配置分为控制平面进程、local 保存的部署设置、Session 行为与 guest 环境、各 Connection 的 Provider 配置。它们作用范围不同,不能把云账户密钥放进 Session env 来替代 Connection。

控制平面进程

下表依据 main.ts、部署模式、本地发现及隧道。除内部就绪逻辑更新临时 ingress 地址外,这些启动配置变更需要重启服务。表中默认值是入口读取默认值,local 保存设置可能继续加工它们。 hosted 启动要求明确的数据库、匹配密钥、已存在 owner Token 和不含认证信息、查询、fragment 或路径的 HTTPS 凭据 origin;不允许开发隧道。失败分别可为 invalid_deployment_mode、hosted_identity_and_storage_required、hosted_master_key_invalid、hosted_https_ingress_required、hosted_owner_identity_required。不存在自动 hosted 账户引导;见自托管。 监听端口经 Number(...) 转换后传给服务器,不提供对所有非法值统一的配置错误码。端口冲突、无效主机和监听失败按底层错误处理。改 HOST 不自动配置 TLS、身份或反向代理。

local 保存的部署配置

文件为所选数据目录中的 deployment.json,由设置 schema校验。local 启动读取它;直接 hosted 入口不读取这份 local 设置。托管启动器会应用保存设置,因此 hosted 部署应按自托管指南使用明确进程配置,不能混用 local 引导。 配置示例(外部域名为占位,需先完成真实路由):
configure 整体替换配置,不做部分合并;省略字段回到默认。结果包含 revision 和 restart_required: true,不自动重启。无效保存文件导致 deployment_configuration_invalid,并发修改可能产生 deployment_configuration_busy 或 deployment_configuration_changed。先查询当前值,不能通过删除锁或覆盖 revision 绕过竞争。

标准代理环境变量

下表变量都是可选的进程环境字符串,启动时生效;修改运维输入后需要重启。local 启动器和直接 local 入口会先组装保存配置,直接 hosted 启动则不经过这一步,直接把环境传给出站 dispatcher。代理 URL 含认证信息时按敏感数据处理,不放入公开诊断;主机绕过列表通常非秘密,但可能暴露内部名称。 最后一行说明 Hexagon 包装层的行为,不保证所有 Provider SDK 或外部程序都以相同方式解释环境变量。隧道包装层仅在特定传输失败分类、且未禁用回退时尝试去代理重试,不重试所有隧道失败。 依据:local 环境组装、出站 dispatcher、Cloudflare 包装层。这些配置控制平面传输,不配置 Sandbox 网络策略,也不授予账户权限。

代理与优先级

local 的 deploymentEnvironment 按 HTTPS_PROXY → https_proxy → 保存的 outbound_proxy 选择代理。HTTP 代理优先 HTTP_PROXY、http_proxy,再回退所选代理。NO_PROXY 优先于 no_proxy,并与保存列表及 127.0.0.1,localhost 合并。显式环境存在时,即使是空字符串也可能遮蔽保存值。 HEXAGON_ACCESS_URL 优先于保存的 external URL;存在有效外部地址时不启动临时隧道。没有外部地址时,显式 HEXAGON_ACCESS_TUNNEL 优先于 ingress mode。local 配置函数将 NODE_USE_ENV_PROXY 写为 1;因此不能承诺在该启动路径中设置 0 就关闭全部代理。直接 hosted 路径的出站配置则会在该值为 0 时选择直接连接。 local 存在代理且未显式设置 HEXAGON_ACCESS_EGRESS_PROXY_URL 时,会用所选代理填充该值;HEXAGON_ACCESS_EGRESS_HOSTS 缺省填入 api.siliconflow.com,api.minimaxi.com,api.minimax.io,api.minimax.chat。这只描述凭据访问代理路径,不授予应用账户权限,也不是 Sandbox 的网络 allowlist。高级网络参数见网络指南,不要把应用级网络策略与进程代理混淆。

冲突配置如何取值

下列示例描述 local 的 deploymentEnvironment 函数,假定只有表中列出的输入;继承的 shell 环境变量可能改变结果。示例域名是保留地址,不代表可用的 ingress 服务。检查变量名称与 origin 时不要打印凭据。 空代理字段不是“关闭所有代理”的通用开关:继承的其他 HTTP(S) 变量和独立的受保护上游路由仍可能生效。hosted 启动不调用这个 local 组装函数;它的出站 dispatcher 直接遵循 NODE_USE_ENV_PROXY=0。

独立的受保护上游路由

以下可选设置适用于两种部署模式。在启动进程前设置,运维修改后重启生效。local 组装函数可能按前文规则补默认值;直接 hosted 启动没有保存配置的回退逻辑。 代理选择和端点校验见受保护传输实现。只填写代理 URL 而没有匹配主机,不会让所有受保护请求都经该代理。主机匹配但代理 URL 使用其他 scheme 时产生 credential_egress_proxy_invalid;URL 格式错误可能直接产生解析器错误。选择这个可信代理意味着由它负责 DNS 约束,其策略应由运维控制。

应用保存配置的变更

准备完整的目标 JSON,包括需要保留的字段,再运行 npm run local -- configure /absolute/path/deployment.json。例如用仅包含 {"ingress":{"mode":"disabled"}} 的配置替换原有配置,会删除保存的出站代理,并将 no_proxy 重置为 []。重启后 shell 覆盖值仍可能生效。 命令以私有文件保存并返回 restart_required: true,不会重启运行实例。按本地工作区指南安排重启,再检查健康与就绪状态,并验证实际访问路径。管理监听健康不能证明凭据 ingress 可用。发生 revision 冲突时,先读取最新配置并核对自己的修改意图,不盲目重试过时的整份替换。

Session 配置与 guest 环境

variables 是 env 的替代输入;同时提供 variables 和非空 env 会产生 ambiguous_variables。名称匹配 [A-Za-z_][A-Za-z0-9_]{0,127};拒绝 HEXAGON_、OPENCODE_、PI_ 前缀以及 PORT、NODE_OPTIONS、PYTHONPATH、PYTHONHOME、LD_PRELOAD、LD_LIBRARY_PATH。值不含 NUL;数量和字节限制见限制。不要通过 guest env 绕过控制平面凭据存储。 源码:Session schema、环境 schema、初始化。更改定义时创建新 Session,不能假定保存配置或重启会改变已有 Session 的固定行为。

客户端与 Provider 配置

SDK 的 URL/Token 构造参数属于客户端。示例中的 HEXAGON_API_URL、HEXAGON_API_TOKEN 是示例程序主动读取的环境变量,不是控制平面自动创建身份的开关。Hexagon.local() 根据显式数据目录、工作区描述文件和用户发现文件定位本地身份;不要修改文件权限以绕过私有身份检查。 各 Provider 配置位于 Connection 的 config,凭据由受管 Secret 或 OAuth 保存。字段、默认值和权限验证范围见集成目录,不能把它们作为全局部署环境变量。测试专用 TEST_DATABASE_URL 不选择普通服务数据库。 本页核对当前读取逻辑,未更改运行实例或重新启动服务。下一步:安装、自托管、网络。