Octop 1.0.2 配置参数详解

目标：讲清 Octop 1.0.2 的配置体系——~/.octop/config.json 全部参数键、环境变量覆盖层、数据目录各文件职责与 systemd 资源限制，并给出个人/家庭与小团队两档生产配置模板。参数语义以官方仓库 docs/configuration.md 为准（2026-10-23 取证），实际取值以 Ubuntu 24.04 实测环境的真实文件为据。

一、环境信息

• 操作系统：Ubuntu 24.04（x86_64）
• Octop 版本：1.0.2（octop version → octop v1.0.2，实测）
• 安装方式：官方一键脚本（见《Ubuntu 24.04 安装 Octop 1.0.2 指南》方案 A）
• 数据根目录：/root/.octop/（root 用户；普通用户为 ~/.octop/，可用 OCTOP_HOME 改）
• 控制平面数据库：SQLite（WAL 模式，实测存在 octop.db / octop.db-shm / octop.db-wal 三件套）
• 服务形态：octop run 前台（验证用）与 systemd 服务（octop.service，实测 active）

二、前置条件

1. 已按安装指南完成安装与初始化（octop init），可正常 octop run 或以 systemd 服务运行；
2. 能读取 ~/.octop/（root 属主时需 root 权限）；
3. 修改配置前建议先备份：octop backup create -o /var/backups/octop-$(date +%F).tar.gz；
4. 注意：除明确标注「热生效」的项外，改配置需重启服务（octop service restart 或重跑 octop run）。

三、参数查看与修改方式

3.1 三层配置来源与优先级

Octop 的运行参数按优先级从高到低取值（官方 octop run --help 原文：explicit CLI flags > OCTOP_BIND_HOST/OCTOP_PORT env > ~/.octop/config.json > launch defaults）：

修改姿势总结：临时改端口用 CLI；常驻差异用 ~/.octop/env（推荐放密钥类）；固化默认值直接编辑 config.json。除 CLI 标志外，改动都要重启进程生效。

3.2 查看当前生效配置

cat /root/.octop/config.json

实测输出（本环境全文）：

{
  "bind_host": "0.0.0.0",
  "port": 8088,
  "log_level": "info",
  "access_token_ttl_seconds": 86400,
  "login_max_attempts": 5,
  "login_lockout_seconds": 900,
  "cors_origins": [],
  "default_timezone": "Asia/Shanghai",
  "enable_dashboard": true,
  "enable_api_docs": false,
  "history_v2_enabled": false,
  "require_setup_password": true,
  "database": {
    "driver": "sqlite",
    "sqlite_path": "octop.db",
    "host": "127.0.0.1",
    "port": 5432,
    "database": "octop",
    "user": "octop"
  },
  "tls": {
    "enabled": false,
    "mode": "",
    "domains": [],
    "cert_file": "",
    "key_file": "",
    "issued_at": "",
    "expires_at": "",
    "acme_staging": false,
    "http_port": 80
  },
  "backup": {
    "auto_enabled": false,
    "schedule": "cron:0 4 * * *",
    "retention_count": 7,
    "include_config": true,
    "include_workspaces": true,
    "include_skill_packages": true,
    "include_plugins": true,
    "include_knowledge": true,
    "include_chats": false
  },
  "capabilities": {
    "mobile": {
      "enabled": false,
      "backend": "none",
      "probed_at": "2026-10-22T22:15:06Z",
      "reason": "no_binder_or_kvm"
    }
  },
  "max_upload_mb": 100,
  "browser_idle_timeout_minutes": 30
}

💡 说明：bind_host 是 0.0.0.0 是因为本环境曾用 octop run --host 0.0.0.0 启动，CLI 覆盖被持久化（见 3.1）；全新初始化后的默认值是 127.0.0.1。database.host/port/database/user 四个键在 driver=sqlite 时不生效，是为切换 PostgreSQL 预留的（见 4.4）。

3.3 数据目录各文件职责

实测 ls -la /root/.octop/ 的完整布局与职责（结合官方 configuration.md 口径）：

~/.octop/
├── config.json              # 进程级配置（3.2 已列全文）
├── env                      # 可选 dotenv（OCTOP_DATABASE_*、API key…），启动时最先加载
├── octop.db                 # SQLite 控制平面：用户、专家、Provider、通道、会话、审计
├── octop.db-shm / -wal      # SQLite WAL 模式附属文件
├── cli_state.json           # CLI 登录态与固定默认（octop config set-user 写入）
├── repl_history             # octop chats repl 的 readline 历史
├── secrets/jwt_secret       # 32 字节随机 JWT 密钥；octop admin rotate-jwt-secret 轮换
├── agents/<agent_id>/       # 每专家工作区（SOUL.md、技能、记忆 memory.sqlite…）
├── browser-profiles/        # 浏览器自动化持久化登录态
├── security/tool_guard/     # Shell 命令允许/拒绝规则（护栏）
├── plugins/                 # 已安装第三方插件
├── ssl/                     # octop run --ssl 无证书时自动生成的自签证书
├── logs/                    # 轮转日志（service 模式）
├── octop.log                # 前台运行默认日志路径
└── venv/、bin/octop         # 安装器隔离环境与 PATH 包装器（仅方案 A）

💡 技术拓展：控制平面数据库不止 SQLite 一种，database.driver 可选：

后端	原理/特点	适用场景
SQLite（WAL）	单文件、读写锁在文件级、WAL 允许读写并发	个人/家庭、单机部署（默认）
PostgreSQL	独立数据库进程、asyncpg 连接池、多连接并发	团队级多用户并发读写、需集中备份治理

本文默认采用 SQLite（WAL）：单实例场景零运维；团队级并发或需要统一数据库治理时切 PostgreSQL（见 4.4 与 7.2 模板）。

四、config.json 核心参数分类详解

4.1 服务监听与仪表盘（bind_host / port / cors_origins / enable_dashboard）

• bind_host（默认 127.0.0.1）：监听地址。仅本机用保持默认；要给 LAN 其他设备访问改 0.0.0.0。等价环境变量 OCTOP_BIND_HOST。
• port（默认 8088）：HTTP 监听端口，0–65535，0 表示让操作系统分配空闲端口。等价 OCTOP_PORT。
• cors_origins（默认 []）：允许的跨域来源列表，仪表盘或外部前端跨域调用时才需要配置；等价 OCTOP_CORS_ORIGINS（逗号分隔）。
• enable_dashboard（默认 true）：是否在 / 提供内置 React 控制台；只做 API/IM 后端可关。等价 OCTOP_ENABLE_DASHBOARD。
• enable_api_docs（默认 false）：是否暴露 Scalar 交互式 API 文档于 /api/docs；关闭时 /api/openapi.json 仍对仪表盘可用（官方明确，生产保持 false）。

验证（改端口实例）：把 port 改为 8088 以外的值并重启后，ss -ltn | grep <端口> 应出现监听；本文实测 8088 返回 HTTP 200（见安装指南 4.5）。

4.2 认证与安全（token TTL / 登录锁定 / 验证码 / JWT 密钥）

• access_token_ttl_seconds（默认 86400）：JWT 访问令牌有效期，24 小时；等价 OCTOP_ACCESS_TOKEN_TTL。缩短可降低令牌泄露窗口。
• login_max_attempts（默认 5）+ login_lockout_seconds（默认 900）：连续失败 5 次锁定 15 分钟；等价 OCTOP_LOGIN_MAX_ATTEMPTS / OCTOP_LOGIN_LOCKOUT_SECONDS。被锁死时的逃生门：octop captcha reset 清除验证码配置回落滑块验证码。
• OCTOP_CAPTCHA_PROVIDER（默认 slider）：登录验证码类型，可选 slider、turnstile、hcaptcha、recaptcha-v3、tencent、geetest-v4；强验证码需配套 OCTOP_CAPTCHA_SITE_KEY / OCTOP_CAPTCHA_SECRET（腾讯还需 OCTOP_CAPTCHA_CAM_SECRET_ID / OCTOP_CAPTCHA_CAM_SECRET_KEY）。该组为启动快照，改后必须重启。
• require_setup_password（默认 true）：首次初始化向导是否要求设置向导密码；无人值守引导（OCTOP_ADMIN_USERNAME / OCTOP_ADMIN_PASSWORD + octop init --yes）时可置 false。
• secrets/jwt_secret：32 字节随机密钥文件，不用手改；轮换命令 octop admin rotate-jwt-secret——立即失效所有在线令牌（官方注明无零停机轮换，旧密钥原地覆盖）。

4.3 日志（log_level 与轮转）

• log_level（默认 info）：可选 debug / info / warning / error；等价 OCTOP_LOG_LEVEL。
• OCTOP_LOG_RETENTION_DAYS（默认 14）：轮转文件 octop.YYYY-MM-DD.log 保留天数。
• OCTOP_LOG_MAX_BYTES（默认 104857600，100 MiB）：单文件超过即滚动（除按日轮转外）。
• OCTOP_LOG_COMPRESS（默认 true）：logrotate 式 compress + delaycompress——上一周期轮转文件 gzip 为 .gz，最新一份轮转保持明文。

4.4 控制平面数据库（database.* 与 OCTOP_DATABASE_*）

config.json 的 database 段与同名环境变量（环境变量优先）：

关键联动（官方 configuration.md 明确）：只要设置了任意 OCTOP_DATABASE_*，启动时即按配置的后端绑定（database_env_configured()）。控制平面数据库与 Agent 记忆是两层：控制平面用 PostgreSQL 时，Agent 记忆默认跟随同一 DSN（每专家独立 schema agent_<id>，需 octop-memory[langgraph-postgres] 依赖）；想让记忆留在文件，需在该专家配置中写 "memory": {"backend": {"type": "sqlite"}}。没有自动的 SQLite→PG 记忆迁移。PostgreSQL 的 vector 扩展是实例级操作（本地 compose 用 docker/postgres/init-vector.sql，托管库找 DBA 开）。

4.5 TLS（tls.* 与 --ssl）

tls.enabled 默认 false。开启途径两种：

• CLI：octop run --ssl——不传证书时自动生成自签证书存入 ~/.octop/ssl/；正式证书用 --ssl-certfile <PEM> --ssl-keyfile <PEM>；
• config.json：填 tls.enabled: true + cert_file / key_file / domains，tls.acme_staging 配合 ACME 沙箱测试，tls.http_port 为 ACME HTTP-01 验证端口（默认 80）。

4.6 上传、时区与杂项

• max_upload_mb（默认 100，范围 1–1024）：进程级上传上限，覆盖聊天附件、IM 入站文件与知识库文档；等价 OCTOP_MAX_UPLOAD_MB。注意三点：老 config.json 缺该键会自动补默认值；改后需重启；反代（如 nginx client_max_body_size）可能另有更紧的限制。Agent 工作区上传、插件 ZIP、备份包走各自独立限额。
• default_timezone（默认 Asia/Shanghai）：控制台时间显示、定时任务调度与 harness 的进程默认时区；等价 OCTOP_DEFAULT_TIMEZONE。旧键 cron_timezone 与 OCTOP_CRON_TIMEZONE 仍被兼容，新键优先。
• browser_idle_timeout_minutes（默认 30）：浏览器自动化会话空闲回收时间。
• history_v2_enabled（默认 false）：分段历史归档写格式开关（OCTOP_HISTORY_V2_ENABLED=true 开启）；只影响下一轮完整写入，已写入的新格式记录回退开关后仍可正常读。官方建议开启前阅读 versioned-history 文档评估兼容与备份边界。
• capabilities.mobile：移动客户端探测结果字段（enabled / backend / probed_at / reason），只读状态，不作为配置入口。

4.7 自动备份（backup.*）

实测默认段（见 3.2 全文）：

• backup.auto_enabled（默认 false）：自动备份总开关；开启后按 schedule 执行。
• backup.schedule（默认 cron:0 4 * * *）：cron 表达式，默认每天 04:00。
• backup.retention_count（默认 7）：保留最近 7 份。
• include_* 六项（config / workspaces / skill_packages / plugins / knowledge 默认 true；chats 默认 false）：选择打包内容，与 octop backup create 的 --no-* / --include-chats 参数一一对应——命令行一次性备份与常驻自动备份共用同一套内容语义。

4.8 插件全局开关（plugins.<id>.enabled）

plugins.<id>.enabled 是插件的全局开关（管理端入口：仪表盘 Admin → Plugins）。内置（bundled）插件在 init 与每次启动时被复制到 ~/.octop/plugins/，初始 enabled: false；bundled_plugins_seeded 记录已提供过哪些内置插件，防止卸载后下次启动又回来。该段不在默认 config.json 中，装过/启用过插件后出现。

五、环境变量总表

下表整理自官方 docs/configuration.md「Environment overrides」（2026-10-23 取证），每个变量设置后覆盖 config.json 同名键，未设置则保持文件值不动；非法整数值会被记日志并忽略（沿用磁盘默认）：

配套约定（官方口径）：~/.octop/env 是 dotenv 文件，仪表盘「Advanced → Environment variables」写入它；保存会整文件替换并从进程环境移除被删的键（系统级/systemd 注入的键不受影响）。每个运行中的 Agent 继承这些键；Agent 工作区的 .env（新专家在 {workspace}/.octop/.env）可再覆盖同一键（工作区优先），但 OCTOP_* / HOME / USER 不允许被工作区 .env 覆盖。Tavily / Brave 等搜索类工具的 Key 放全局 ~/.octop/env，不要只放单个专家的 .env。

六、systemd 资源限制参数

octop service start / restart 会随主单元安装资源保护 drop-in（实测 systemctl status octop 可见 10-nofile.conf, 15-resource-limits.conf 两枚）：

• 10-nofile.conf：LimitNOFILE=65535（用户级单元受进程硬上限约束，systemd 无法突破）；
• 15-resource-limits.conf：MemoryHigh=60%、MemoryMax=75%（物理内存百分比）、MemorySwapMax=512M、OOMPolicy=kill、30 秒重启延迟、10 分钟内最多 3 次启动。

按机器预算覆盖的方法（官方推荐）：

[Service]
MemoryHigh=5G
MemoryMax=6G
MemorySwapMax=512M

写到 systemctl edit octop.service 生成的 override.conf（排序在托管默认之后，服务升级不被冲掉），改完 octop service restart 生效。实测本环境进程常驻内存约 260.6 MB（systemctl status octop 回显），8 GB 内存服务器足够跑 Octop 本体 + 小模型推理端点。若反复启动失败撞上 10 分钟 3 次的限速，先修根因，再 systemctl reset-failed octop.service（系统级服务去掉 --user）。

七、生产配置模板

7.1 个人/家庭档（SQLite，8 GB 内存，NVMe SSD，单机直连）

~/.octop/config.json（在默认值基础上只动必要项）：

{
  "bind_host": "0.0.0.0",
  "port": 8088,
  "log_level": "info",
  "access_token_ttl_seconds": 43200,
  "login_max_attempts": 5,
  "login_lockout_seconds": 900,
  "cors_origins": [],
  "default_timezone": "Asia/Shanghai",
  "enable_dashboard": true,
  "enable_api_docs": false,
  "require_setup_password": true,
  "max_upload_mb": 100,
  "database": { "driver": "sqlite", "sqlite_path": "octop.db" },
  "backup": {
    "auto_enabled": true,
    "schedule": "cron:0 4 * * *",
    "retention_count": 7,
    "include_chats": true
  }
}

~/.octop/env（敏感项全部走 env，不进 config.json）：

OCTOP_BIND_HOST=0.0.0.0
OCTOP_CAPTCHA_PROVIDER=slider
OCTOP_DATABASE_DRIVER=sqlite
OCTOP_LOG_RETENTION_DAYS=14

要点：单机 SQLite + WAL、每日 04:00 自动备份且带上聊天记录（include_chats: true）、令牌缩到 12 小时、LAN 监听 0.0.0.0 但不做公网暴露。浏览器自动化开启时给 systemd 加 MemoryMax=4G 级别的上限防 Chromium 吃满内存。

7.2 小团队档（PostgreSQL，16 GB 内存，SSD，独立 DB 实例）

~/.octop/config.json：

{
  "bind_host": "0.0.0.0",
  "port": 8088,
  "log_level": "info",
  "access_token_ttl_seconds": 28800,
  "login_max_attempts": 5,
  "login_lockout_seconds": 900,
  "default_timezone": "Asia/Shanghai",
  "enable_dashboard": true,
  "enable_api_docs": false,
  "require_setup_password": true,
  "max_upload_mb": 200,
  "database": {
    "driver": "postgresql",
    "host": "192.168.1.100",
    "port": 5432,
    "database": "octop",
    "user": "octop"
  },
  "backup": {
    "auto_enabled": true,
    "schedule": "cron:0 3 * * *",
    "retention_count": 14
  }
}

~/.octop/env：

OCTOP_DATABASE_DRIVER=postgresql
OCTOP_DATABASE_HOST=192.168.1.100
OCTOP_DATABASE_PORT=5432
OCTOP_DATABASE_NAME=octop
OCTOP_DATABASE_USER=octop
OCTOP_DATABASE_PASSWORD=<生产库密码，仅放 env 不落 config.json>
OCTOP_CAPTCHA_PROVIDER=tencent
OCTOP_CAPTCHA_SITE_KEY=<腾讯验证码 CaptchaAppId>
OCTOP_CAPTCHA_SECRET=<腾讯验证码 AppSecretKey>

要点：团队并发读写走 PostgreSQL（asyncpg 连接池）；config.json 里不落 password 明文（官方生产建议），凭据只进 env 文件并收紧权限（chmod 600 ~/.octop/env）；上传上限按知识库文档体量放大到 200 MB 且反代同步调大；Agent 记忆默认跟随 PG 同一 DSN（每专家 schema），要留文件记忆的专家单独写 "memory": {"backend": {"type": "sqlite"}}；转发公网前启用强验证码与 TLS。

八、常见问题（FAQ）

Q1：改了 config.json 不生效？ 除 CLI 标志外一切改动需重启进程：systemd 形态 octop service restart；前台形态 Ctrl+C 后重跑 octop run。验证码组（OCTOP_CAPTCHA_*）是启动快照，同样要重启。

Q2：环境变量和 config.json 谁赢？ 同名键环境变量恒胜；~/.octop/env 在进程启动最早期加载，因此 systemd Environment= 与 shell 导出的变量若也同名，后加载的 dotenv 会替换同键（官方明确 dotenv 保存会整文件替换并清理被删键）。

Q3：PG 密码能不能写进 config.json？ 向导以离散字段配置 PG 时可能把 database.password 写入 config.json（便利本地首启）；生产环境官方建议只留 OCTOP_DATABASE_PASSWORD 或含密码的 OCTOP_DATABASE_URL，并限制 config.json 文件权限。

Q4：控制平面切了 PostgreSQL，Agent 记忆会自动跟着进库吗？ 会——默认记忆复用同一 DSN（每专家独立 schema）。想留在文件，须在专家配置写 "memory": {"backend": {"type": "sqlite"}}；没有自动 SQLite→PG 记忆迁移，切换前先 octop backup。

Q5：上传大文件被拒？ 先查 max_upload_mb（默认 100 MB，改后重启）；再查反向代理 body 限制（nginx client_max_body_size）；Agent 工作区上传/插件 ZIP/备份包不在此限额内。

Q6：写错整数值会怎样？ 非法整数被记日志并忽略，沿用磁盘默认值；不会导致启动失败。

Q7：忘记管理员密码或被登录锁定？ 管理员本地重置：octop user passwd <用户名>；锁定时间未到又急着进，octop captcha reset 清验证码配置回落默认滑块。

Q8：JWT 密钥泄漏了怎么办？ 立即 octop admin rotate-jwt-secret，所有在线令牌即刻失效（原地覆盖，无零停机轮换，用户需重新登录）。

九、参考链接

• 官方配置文档（本文参数语义来源）：https://github.com/TencentCloud/Octop/blob/main/docs/configuration.md
• 数据库后端 ADR：https://github.com/TencentCloud/Octop/blob/main/docs/adr/002-database-backends.md
• 单进程模型 ADR：https://github.com/TencentCloud/Octop/blob/main/docs/adr/001-single-process-model.md
• 环境变量示例：https://github.com/TencentCloud/Octop/blob/main/.env.example
• 站内系列：《Octop 介绍与选型指南》、《Ubuntu 24.04 安装 Octop 1.0.2 指南》、《Octop 1.0.2 常用 CLI 命令详解》