控制台配置

控制台（控制节点）同时支持 config.toml 配置文件和环境变量。

配置文件

设置 CONSOLE_CONFIG_FILE 可以显式指定配置文件。未设置时，控制台会依次查找程序文件同目录和当前工作目录下的 config.toml；未找到文件时，继续使用环境变量和内置默认值启动。

配置优先级为：环境变量 > config.toml > 内置默认值。TOML 键名由环境变量名移除 CONSOLE_ 前缀并转换为小写得到，例如 CONSOLE_HTTP_ADDR 对应 http_addr；嵌套表则对应以下划线连接的环境变量名。

http_addr = ":8089"
grpc_addr = ":50051"
db_path = "./db/onlyboxes-console.db"
log_level = "info"

[mcp_tool.python_exec]
description = "在沙箱中执行 Python 代码。"

建议继续通过环境变量提供 hash_key、dashboard_password、jit_signing_key、export_file_sk 等密钥。全部可用配置请参考带注释的配置模板。

环境变量

核心

变量	必填	默认值	说明
`CONSOLE_HASH_KEY`	是		用于哈希 worker 密钥和访问令牌的 HMAC 密钥
`CONSOLE_HTTP_ADDR`	否	`:8089`	Dashboard 和 REST API 监听地址
`CONSOLE_GRPC_ADDR`	否	`:50051`	Worker gRPC 监听地址

数据库

变量	必填	默认值	说明
`CONSOLE_DB_PATH`	否	`./db/onlyboxes-console.db`	SQLite 数据库文件路径
`CONSOLE_DB_BUSY_TIMEOUT_MS`	否	`5000`	SQLite 繁忙超时（毫秒）
`CONSOLE_TASK_RETENTION_DAYS`	否	`30`	已完成任务记录的保留天数

初始管理员账户

以下变量仅在首次启动且不存在管理员账户时生效，后续启动会被忽略。

变量	必填	说明
`CONSOLE_DASHBOARD_USERNAME`	否	初始管理员用户名
`CONSOLE_DASHBOARD_PASSWORD`	否	初始管理员密码
`CONSOLE_INITIAL_ADMIN_API_KEY`	否	显式指定的初始管理员 API 密钥

账户

变量	必填	默认值	说明
`CONSOLE_ENABLE_REGISTRATION`	否	`false`	允许管理员注册非管理员账户

工具管理

变量	必填	默认值	说明
`CONSOLE_HIDDEN_TOOLS`	否		逗号分隔的 MCP 内部 capability ID 隐藏列表（`echo`、`pythonExec`、`terminalExec`、`computerUse`、`readImage`、`exportFile`）。这里始终填写内置 ID，不要填 `CONSOLE_MCP_TOOL_<TOOL>_NAME` 改名后的对外 name。被隐藏的工具不会出现在 `tools/list` 中，但如果客户端已知工具名，仍可继续调用。
`CONSOLE_MCP_TOKEN_QUERY_PARAM`	否	`token`	`/mcp` URL token 兜底鉴权使用的查询参数名，供无法设置自定义请求头的客户端使用。仍推荐优先使用 Bearer header。
`CONSOLE_COMPUTER_USE_SESSION_ID_PREFIX`	否	`CU:`	大小写敏感的前缀，使 `readImage` 与 `exportFile` 将后缀解释为当前账号的 Worker System ID。修改会改变 session ID 的解释方式，通常不建议修改。空值或全空白值会回退到 `CU:` 并记录 warning。TOML 键为 `computer_use_session_id_prefix`。

工具描述 / 参数描述覆盖

以下环境变量允许在不改代码的情况下改写面向模型的工具/参数文本。未设置的变量保持内置默认值。<TOOL> 段使用 UPPER_SNAKE_CASE（例如 pythonExec → PYTHON_EXEC）；<PARAM> 段是参数 snake_case JSON 键的全大写形式（例如 session_id → SESSION_ID）。

变量	必填	默认值	说明
`CONSOLE_MCP_TOOL_<TOOL>_NAME`	否	内置	覆盖工具在 `tools/list` 中暴露的 `name`（即 `tools/call` 的路由键）。必须匹配 `^[a-zA-Z0-9_-]{1,64}$`；空串/非法字符会回退默认并打印 warn。若覆盖值与其他工具的内置默认名冲突（例如把 `ECHO_NAME` 设为 `pythonExec`）也会回退。改名后客户端需重新拉取 `tools/list`，否则用旧名调用 `tools/call` 会 404。`CONSOLE_HIDDEN_TOOLS` 仍填内部 capability ID（`echo`），不填改名后的值。
`CONSOLE_MCP_TOOL_<TOOL>_TITLE`	否	内置	覆盖工具在 `tools/list` 与 `annotations.title` 中展示的标题。空串会回退默认并打印一条 warning 日志。
`CONSOLE_MCP_TOOL_<TOOL>_DESCRIPTION`	否	内置	覆盖工具的 `description`。空串会回退默认并打印一条 warning 日志。
`CONSOLE_MCP_TOOL_<TOOL>_PARAM_<PARAM>_DESCRIPTION`	否	内置	覆盖 `inputSchema.properties.<param>` 中单个参数的 `description`。设置为空字符串会从 `tools/list` 中隐藏该参数：该键会从 `properties` 与 `required` 中移除，且 schema 的 `additionalProperties` 会被翻转为 `true`，MCP/HTTP 调用方依然可以传入该字段（handler 仍能收到）。每隐藏一个参数都会在启动时打印一条 `WARN hiding MCP tool parameter ... required=<bool>` 日志。如果被隐藏的参数原本是 required，模型将无法构造合法调用。

支持的 <TOOL> 段及其 <PARAM> 取值：

工具	`<TOOL>`	`<PARAM>` 取值
`echo`	`ECHO`	`MESSAGE`、`TIMEOUT_MS`
`pythonExec`	`PYTHON_EXEC`	`CODE`、`TIMEOUT_MS`
`terminalExec`	`TERMINAL_EXEC`	`COMMAND`、`SESSION_ID`、`CREATE_IF_MISSING`、`LEASE_TTL_SEC`、`TIMEOUT_MS`
`computerUse`	`COMPUTER_USE`	`COMMAND`、`WORKER_ID`、`TIMEOUT_MS`、`REQUEST_ID`
`readImage`	`READ_IMAGE`	`SESSION_ID`、`FILE_PATH`、`TIMEOUT_MS`
`exportFile`	`EXPORT_FILE`	`SESSION_ID`、`FILE_PATH`、`TIMEOUT_MS`

示例：

# 把 echo 改名为 ping，覆盖描述，并隐藏 terminalExec 的 session_id 参数
CONSOLE_MCP_TOOL_ECHO_NAME="ping"
CONSOLE_MCP_TOOL_ECHO_DESCRIPTION="ping-only echo"
CONSOLE_MCP_TOOL_TERMINAL_EXEC_PARAM_SESSION_ID_DESCRIPTION=""

导出文件对象存储

以下变量用于启用 MCP exportFile 工具。只有当以下环境变量被配置后，该工具才会注册到 tools/list。

CONSOLE_EXPORT_FILE_ENDPOINT
CONSOLE_EXPORT_FILE_REGION
CONSOLE_EXPORT_FILE_BUCKET_NAME
CONSOLE_EXPORT_FILE_EXPORT_PREFIX
CONSOLE_EXPORT_FILE_AK
CONSOLE_EXPORT_FILE_SK

变量	必填	默认值	说明
`CONSOLE_EXPORT_FILE_ENDPOINT`	否		用于预签名上传/下载的 S3 兼容 endpoint URL
`CONSOLE_EXPORT_FILE_REGION`	否		显式签名 Region
`CONSOLE_EXPORT_FILE_BUCKET_NAME`	否		目标 Bucket 名称
`CONSOLE_EXPORT_FILE_EXPORT_PREFIX`	否		追加到每个导出对象 Key 前的前缀
`CONSOLE_EXPORT_FILE_AK`	否		用于预签名的 Access Key
`CONSOLE_EXPORT_FILE_SK`	否		用于预签名的 Secret Key
`CONSOLE_EXPORT_FILE_UPLOAD_PRESIGN_TTL_SEC`	否	`900`	上传预签名 URL 的有效期（秒）
`CONSOLE_EXPORT_FILE_DOWNLOAD_PRESIGN_TTL_SEC`	否	`3600`	下载预签名 URL 的有效期（秒）
`CONSOLE_EXPORT_RETURN_SCHEMA`	否	`ALL`	控制 `exportFile` 返回哪些字段：`ALL`（`signed_url` + `object_key` + `filename`）、`SIGNED_URL`（仅 `signed_url`）、`OBJECTKEY`（仅 `object_key` + `filename`，跳过下载 URL 生成）

JIT Token 认证

变量	必填	默认值	说明
`CONSOLE_JIT_SIGNING_KEY`	否		JIT Token（`obx_jit_v1.*`）的 HMAC-SHA256 签名密钥。未设置时完全禁用 JIT 认证。
`CONSOLE_DASHBOARD_JIT_SIGNING_KEY`	否		Dashboard JIT Token（`obx_dashboard_jit_v1.*`）的 HMAC-SHA256 签名密钥。必须与 `CONSOLE_JIT_SIGNING_KEY` 不同。未设置时禁用 Dashboard JIT 认证。

Worker 管理

变量	必填	默认值	说明
`CONSOLE_HEARTBEAT_INTERVAL_SEC`	否	`5`	期望的 worker 心跳间隔（秒）
`CONSOLE_OFFLINE_TTL_SEC`	否	`15`	worker 静默多少秒后标记为离线
`CONSOLE_REPLAY_WINDOW_SEC`	否	`60`	请求去重的重放窗口（秒）
`CONSOLE_WORKER_CONNECTION_CONFLICT_POLICY`	否	`REPLACE`	同一 worker 已连接时的处理策略：`REPLACE` 断开已有连接并接受新连接；`REJECT` 保留已有连接并拒绝新连接

公开预览代理

以下变量用于启用公开预览代理。在 Nginx 与 Worker 代理入口就绪前应保持禁用。完整部署流程参考公开预览代理。

变量	必填	默认值	说明
`CONSOLE_PROXY_ENABLED`	否	`false`	是否启用公开预览代理
`CONSOLE_PROXY_PUBLIC_BASE_DOMAIN`	否		预览 URL 的基域名，例如 `public-preview.example.com`；需要 wildcard DNS/TLS
`CONSOLE_PROXY_PUBLIC_SCHEME`	否	`https`	预览 URL 协议；仅接受 `http` 或 `https`，生产环境应使用 `https`，可信本地开发可设为 `http`
`CONSOLE_PROXY_INTERNAL_AUTH_TOKEN`	否		Nginx 与 Console 之间共享的内部鉴权 Token；建议通过环境变量提供而非写入配置文件
`CONSOLE_PROXY_ALLOWED_WORKER_CIDRS`	否		逗号分隔的 Worker 代理入口 CIDR 白名单；只接受单播 IP，不接受主机名、loopback、unspecified 或白名单外地址
`CONSOLE_PROXY_ALLOWED_WORKER_PORTS`	否		逗号分隔的 Worker 代理端口白名单
`CONSOLE_PROXY_ALLOWED_DIRECT_DOMAINS`	否	`e2b.app`	逗号分隔的 E2B 直连域名后缀白名单；应收窄到部署实际使用的 E2B 域名
`CONSOLE_PROXY_ROUTE_TTL_SEC`	否	`86400`	预览路由 TTL（秒），最大 `604800`（7 天）；超出时 Console 拒绝启动
`CONSOLE_PROXY_ROUTE_KEY_LENGTH`	否	`26`	新生成 route key 的长度，范围 `8..26`；修改后已有路由仍然有效。低于 `16` 位仅建议用于可信本地或低风险环境
`CONSOLE_PROXY_ROUTE_MAX_PER_ACCOUNT`	否	`16`	单个账号最多保留的有效预览路由数量
`CONSOLE_PROXY_ROUTE_MAX_PER_SESSION`	否	`2`	单个终端 Session 最多保留的有效预览路由数量

日志

变量	必填	默认值	说明
`CONSOLE_LOG_LEVEL`	否	`info`	`debug` / `info` / `warn` / `error`
`CONSOLE_LOG_FORMAT`	否	`json`	`json` / `text`
`CONSOLE_LOG_ADD_SOURCE`	否	`false`	是否在日志中包含源文件和行号