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：

.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

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

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

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

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