> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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`             | —       | 已忽略                            | 已下线。Octop 忽略该变量，并在启动时迁移已有的 v2 归档。                                                                                |
| `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`                        | 是否包含聊天记录和运行轨迹。                                                                                                   |
| `OCTOP_PORTAL_ORIGIN`                  | origin  | `https://octop.cloud`          | 插件市场与专家市场的目录源站。只写协议、主机和端口。空字符串会关闭远程目录。见[插件与专家市场](/guide/guides/private-market.md)。                               |
| `OCTOP_MARKET_REMOTE_ORIGIN`           | origin  | `https://download.octop.cloud` | 目录条目 `download_url` 允许的安装包源站。只写协议、主机和端口。见[插件与专家市场](/guide/guides/private-market.md)。                             |
| `SKILL_MARKET_ORIGIN`                  | origin  | `https://api.skillhub.cn`      | 技能搜索、榜单和 ZIP 下载的源站。只写协议、主机和端口。见[技能市场](/guide/guides/skill-market.md)。                                            |
| `SKILLSET_ORIGIN`                      | origin  | `https://api.skillhub.cn`      | **从技能市场导入**时读取技能集的源站。只写协议、主机和端口。见[技能市场](/guide/guides/skill-market.md)。                                          |
| `OCTOP_CHECKPOINT_BACKUP_BEFORE_PRUNE` | string  | `first`                        | 定时清理检查点之前，写出 `memory.sqlite.pre-prune.bak`。`always` 每次清理前都重写备份，写不出就跳过清理。`off` 不备份。                               |
| `OCTOP_CHECKPOINT_BACKUP_KEEP_DAYS`    | int     | `7`                            | 这份检查点备份保留的天数。`0` 表示不自动过期。                                                                                        |

## Docker `.env` 示例

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


```bash .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
```
```yaml 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`）。
> 

