> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Octop 环境变量：完整配置参考

> 使用环境变量覆盖任何 Octop config.json 字段。适用于 Docker、CI 流水线以及不希望将密钥存入文件系统的场景。

每个 `config.json` 字段都有对应环境变量。设置后优先级高于文件值，文件本身不会被改写。这适合 Docker、CI，以及不想把密钥落盘的场景。

## 变量列表

| 环境变量 | 类型 | 默认值 | 描述 |
| - | - | - | - |
| `OCTOP_HOME` | path | `~/.octop` | 安装根目录。数据库、密钥、专家工作区和插件都在这里。 |
| `OCTOP_BIND_HOST` | string | `127.0.0.1` | 监听网卡。局域网或容器访问请设为 `0.0.0.0`。 |
| `OCTOP_PORT` | int | `8088` | 绑定的 TCP 端口。 |
| `OCTOP_LOG_LEVEL` | string | `info` | 日志级别：`debug`、`info`、`warning` 或 `error`。 |
| `OCTOP_LOG_RETENTION_DAYS` | int | `14` | 保留轮转后的 `octop.log.YYYY-MM-DD` 天数。 |
| `OCTOP_LOG_MAX_BYTES` | int | `104857600`（100 MiB） | 活动日志超过该大小时轮转（同时仍按日轮转）。 |
| `OCTOP_LOG_COMPRESS` | bool | `true` | 类似 logrotate 的 `compress` + `delaycompress`：下一轮再 gzip 更早的明文轮转文件。 |
| `OCTOP_ACCESS_TOKEN_TTL` | int（秒） | `86400` | JWT 访问令牌有效期，默认 24 小时。 |
| `OCTOP_LOGIN_MAX_ATTEMPTS` | int | `5` | 锁定前允许的失败登录次数。 |
| `OCTOP_LOGIN_LOCKOUT_SECONDS` | int | `900` | 锁定持续时间（秒）。 |
| `OCTOP_DEFAULT_TIMEZONE` | IANA tz | `Asia/Shanghai` | 页面时间戳、定时任务和 harness 使用的时区。 |
| `OCTOP_CORS_ORIGINS` | 逗号分隔 | *(空)* | 允许跨域的来源列表。 |
| `OCTOP_ENABLE_DASHBOARD` | bool | `true` | 是否在 `/` 提供内置页面。 |
| `OCTOP_ENABLE_API_DOCS` | bool | `false` | 是否在 `/api/docs` 开放 Scalar。 |
| `OCTOP_REQUIRE_SETUP_PASSWORD` | bool | `true` | 首次向导是否需要密码门。无人值守请配合 `OCTOP_ADMIN_USERNAME` / `OCTOP_ADMIN_PASSWORD`。 |
| `OCTOP_DATABASE_URL` | string | *(空)* | 完整 PostgreSQL DSN，会覆盖下面各 `OCTOP_DATABASE_*` 字段。 |
| `OCTOP_DATABASE_DRIVER` | string | `sqlite` | 存储后端：`sqlite` 或 `postgresql`。 |
| `OCTOP_DATABASE_SQLITE_PATH` | path | `octop.db` | SQLite 路径。相对路径相对 `OCTOP_HOME` 解析。 |
| `OCTOP_DATABASE_HOST` | string | `127.0.0.1` | PostgreSQL 主机。仅 `OCTOP_DATABASE_DRIVER=postgresql` 时使用。 |
| `OCTOP_DATABASE_PORT` | int | `5432` | PostgreSQL 端口。 |
| `OCTOP_DATABASE_NAME` | string | `octop` | PostgreSQL 数据库名。 |
| `OCTOP_DATABASE_USER` | string | `octop` | PostgreSQL 用户。 |
| `OCTOP_DATABASE_PASSWORD` | string | *(空)* | PostgreSQL 密码。生产环境请用环境变量，不要写进 `config.json`。 |
| `OCTOP_ADMIN_USERNAME` | string | *(空)* | `octop init` 时预填的首个管理员用户名。Docker 首次启动未设置时默认为 `admin`。 |
| `OCTOP_ADMIN_PASSWORD` | string | *(空)* | `octop init` 时预填的首个管理员密码。 |
| `OCTOP_DEFAULT_PASSWORD` | string | `Octop123` | Docker / 镜像首次启动的管理员密码，写入 `/data/.octop/credential.txt`。不替代裸机设置向导。 |
| `OCTOP_ADMIN_DISPLAY_NAME` | string | *(空)* | `octop init` 时预填的首个管理员显示名。 |
| `OCTOP_HISTORY_V2_ENABLED` | bool | `false` | 为下一完整回合启用分段历史归档。 |
| `OCTOP_BROWSER_IDLE_TIMEOUT_MINUTES` | int | `30` | 工作台拉起的本地 Chrome 空闲多少分钟后回收。 |
| `OCTOP_USER` | string | *(空)* | CLI 子命令默认 `--user`。 |
| `OCTOP_AGENT` | string | *(空)* | CLI 子命令默认 `--agent`。 |
| `OCTOP_SERVICE_MODE` | string | *(自动)* | `octop service` 使用的后端：`systemd` 或 `launchd`。 |
| `OCTOP_SERVICE_SCOPE` | string | *(自动)* | Linux 上安装用户级还是系统级单元：`user` 或 `system`。 |
| `OCTOP_MAX_UPLOAD_MB` | int | `100` | 聊天附件、IM 入站与知识库文档的最大上传（MiB，范围 1–1024）。不适用于插件 ZIP、工作区上传或备份导入（备份导入上限 512 MB）。 |
| `OCTOP_BACKUP_AUTO_ENABLED` | bool | `false` | 是否在运行中的 `octop run` 内启用自动备份。 |
| `OCTOP_BACKUP_SCHEDULE` | string | `cron:0 4 * * *` | 自动备份计划。 |
| `OCTOP_BACKUP_RETENTION_COUNT` | int | `7` | 保留的自动备份份数。 |
| `OCTOP_BACKUP_INCLUDE_CONFIG` | bool | `true` | 新归档是否包含 `config.json` 与 env。 |
| `OCTOP_BACKUP_INCLUDE_WORKSPACES` | bool | `true` | 是否包含专家工作区。 |
| `OCTOP_BACKUP_INCLUDE_SKILL_PACKAGES` | bool | `true` | 是否包含全局技能包。 |
| `OCTOP_BACKUP_INCLUDE_PLUGINS` | bool | `true` | 是否包含已安装插件。 |
| `OCTOP_BACKUP_INCLUDE_KNOWLEDGE` | bool | `true` | 是否包含知识库文件。 |
| `OCTOP_BACKUP_INCLUDE_CHATS` | bool | `false` | 是否包含聊天记录和运行轨迹。 |

## Docker `.env` 示例

在 `docker-compose.yml` 旁创建 `.env`：

```bash .env theme={null}
# 网络
OCTOP_BIND_HOST=0.0.0.0
OCTOP_PORT=8088

# 数据库（PostgreSQL）
OCTOP_DATABASE_DRIVER=postgresql
OCTOP_DATABASE_HOST=postgres
OCTOP_DATABASE_PORT=5432
OCTOP_DATABASE_NAME=octop
OCTOP_DATABASE_USER=octop
OCTOP_DATABASE_PASSWORD=change-me-in-production

# 首次管理员引导
OCTOP_ADMIN_USERNAME=admin
OCTOP_ADMIN_PASSWORD=change-me-in-production

# 时区与日志
OCTOP_DEFAULT_TIMEZONE=America/New_York
OCTOP_LOG_LEVEL=info
```

```yaml docker-compose.yml（片段） theme={null}
services:
  octop:
    image: octop:latest
    env_file: .env
    environment:
      - OCTOP_DATABASE_DRIVER
      - OCTOP_DATABASE_HOST
      - OCTOP_DATABASE_PORT
      - OCTOP_DATABASE_NAME
      - OCTOP_DATABASE_USER
      - OCTOP_DATABASE_PASSWORD
    ports:
      - "${OCTOP_PORT:-8088}:8088"
    volumes:
      - octop_data:/root/.octop
```

> [!NOTE]
>
> 使用 Docker Compose 时，请把 `OCTOP_DATABASE_*` 写进 `docker/.env`，**并**在 `docker-compose.yml` 的 `environment:` 下列出这些键。Compose 的 `.env` 只用于插值，未列出的键不会进入容器；写入挂载卷内的 `~/.octop/env` 同样生效。

> [!WARNING]
>
> 生产环境不要把 `OCTOP_DATABASE_PASSWORD` 或 `OCTOP_ADMIN_PASSWORD` 写进 `config.json`。把它们放在环境变量或密钥管理器中，并确保 `.env` 不进版本库。将 `config.json` 权限限制为服务账户（`chmod 600 ~/.octop/config.json`）。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.