export const meta = {
  title: '控制台配置',
  description: '控制节点的所有环境变量。',
  section: '快速开始',
  order: 35,
  slug: 'console-config',
}

# 控制台配置

控制台（控制节点）允许通过环境变量进行配置，在 `docker-compose.yml` 或容器编排工具中设置即可。

## 环境变量

### 核心

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `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。 |

#### 工具描述 / 参数描述覆盖

以下环境变量允许在不改代码的情况下改写面向模型的工具/参数文本。未设置的变量保持内置默认值。`<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`、`TIMEOUT_MS`、`REQUEST_ID` |
| `readImage` | `READ_IMAGE` | `SESSION_ID`、`FILE_PATH`、`TIMEOUT_MS` |
| `exportFile` | `EXPORT_FILE` | `SESSION_ID`、`FILE_PATH`、`TIMEOUT_MS` |

示例：

```bash
# 把 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_LOG_LEVEL` | 否 | `info` | `debug` / `info` / `warn` / `error` |
| `CONSOLE_LOG_FORMAT` | 否 | `json` | `json` / `text` |
| `CONSOLE_LOG_ADD_SOURCE` | 否 | `false` | 是否在日志中包含源文件和行号 |

## 相关文档

- [安装](/zh-CN/docs/install)
- [快速开始](/zh-CN/docs/quick-start)
- [架构](/zh-CN/docs/architecture)
