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

每个 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_CAPTCHA_PROVIDER`	slug	`slider`	登录验证码：`slider`、`turnstile`、`hcaptcha`、`recaptcha-v3` 或 `tencent`。已保存的 `recaptcha`（v2）仍可用，但不再出现在列表中。启动时快照，改完需重启。
`OCTOP_CAPTCHA_SITE_KEY`	string	(空)	公钥（腾讯云为 CaptchaAppId）。环境快照为强校验提供方时必填。
`OCTOP_CAPTCHA_SECRET`	string	(空)	校验密钥（腾讯云为 AppSecretKey）。不会记入日志；`GET /api/envs` 会打码。
`OCTOP_CAPTCHA_CAM_SECRET_ID`	string	(空)	仅腾讯云：用于 `DescribeCaptchaResult` 的 CAM SecretId。环境快照为 `tencent` 时必填。
`OCTOP_CAPTCHA_CAM_SECRET_KEY`	string	(空)	仅腾讯云：CAM SecretKey。不会记入日志；`GET /api/envs` 会打码。
`OCTOP_CAPTCHA_V3_MIN_SCORE`	float	`0.5`	`recaptcha-v3` 最低分数。管理页面此项只读。
`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	(空)	Docker / 镜像首次启动的管理员密码，写入 `/data/.octop/credential.txt`。未设置时自动生成 16 位随机密码；弱密码或常见密码会回退为随机密码，首次初始化不会因此失败。不替代裸机设置向导。
`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：

.env

docker-compose.yml（片段）

.env

# 网络
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

# 首次管理员引导（Docker 入口脚本读取 OCTOP_DEFAULT_PASSWORD）
OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=change-me-in-production

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

docker-compose.yml（片段）

services:
  octop:
    image: octop:latest
    env_file: .env
    environment:
      - OCTOP_ADMIN_USERNAME
      - OCTOP_DEFAULT_PASSWORD
      - 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

说明

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

注意

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

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

#变量列表

#Docker .env 示例

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

变量列表

Docker `.env` 示例