Octop config.json 参考：所有服务器配置字段

Octop 读取 ~/.octop/config.json 进行服务器设置。从此文件配置端口、CORS、时区、数据库后端和 TLS。

Octop 首次运行时会在 ~/.octop/ 生成 config.json。之后可直接编辑该文件，无需重装。环境变量优先级始终高于文件值，导出的 OCTOP_* 会覆盖对应字段。

​

字段参考

​

核心设置

字段	类型	默认值	描述
bind_host	string	127.0.0.1	监听网卡。设为 0.0.0.0 可接受局域网或容器访问。
port	int	8088	绑定的 TCP 端口。
log_level	string	info	日志级别：debug、info、warning 或 error。
access_token_ttl_seconds	int	86400	JWT 访问令牌有效期（秒），默认 24 小时。
login_max_attempts	int	5	账户锁定前允许的失败登录次数。
login_lockout_seconds	int	900	触发锁定后的锁定时长（秒），默认 15 分钟。
cors_origins	list	[]	允许跨域请求的来源列表。留空则拒绝全部跨域。
default_timezone	string	Asia/Shanghai	页面时间戳、定时任务和 harness 使用的 IANA 时区。
enable_dashboard	bool	true	是否在 / 提供内置页面。设为 false 则只暴露 API。
enable_api_docs	bool	false	是否在 /api/docs 开放 Scalar 交互文档。开发时可开，生产建议关闭。
require_setup_password	bool	true	首次设置向导是否需要密码门。仅在使用 OCTOP_ADMIN_USERNAME 与 OCTOP_ADMIN_PASSWORD 做无人值守引导时设为 false。
max_upload_mb	int	100	聊天附件、IM 入站与知识库文档的最大上传（MiB）。小于 1 回退为 100，大于 1024 会截断为 1024。
history_v2_enabled	bool	false	可选分段历史归档。为 true 时，下一完整回合按新格式写入；关闭后仍能读取已保存的新格式。可用 OCTOP_HISTORY_V2_ENABLED 覆盖。
browser_idle_timeout_minutes	int	30	工作台拉起的本地 Chrome 空闲多少分钟后回收。登录态仍保留在磁盘 profile。可用 OCTOP_BROWSER_IDLE_TIMEOUT_MINUTES 覆盖。

​

database 段

字段	类型	默认值	描述
driver	string	sqlite	存储后端：sqlite 或 postgresql。
sqlite_path	string	octop.db	SQLite 文件路径。相对路径相对 ~/.octop/ 解析。
host	string	127.0.0.1	PostgreSQL 主机。仅在 driver 为 postgresql 时使用。
port	int	5432	PostgreSQL 端口。
database	string	octop	PostgreSQL 数据库名。
user	string	octop	PostgreSQL 用户。
password	string	""	PostgreSQL 密码。生产环境请用 OCTOP_DATABASE_PASSWORD，不要写在文件里。

生产环境不要把 PostgreSQL 密码写进 config.json，改用 OCTOP_DATABASE_PASSWORD，并把文件权限限制为服务账户可读。

​

tls 段

字段	类型	默认值	描述
enabled	bool	false	是否在 Octop 内终止 TLS。
cert_file	string	""	PEM 证书绝对路径。
key_file	string	""	PEM 私钥绝对路径。

完整步骤见 TLS 与服务，含自签证书。

​

backup 段

字段	类型	默认值	描述
auto_enabled	bool	false	是否在 octop run 内启用自动系统备份。
schedule	string	cron:0 4 * * *	cron 或 interval:<秒>，使用服务器时区。
retention_count	int	7	保留多少份 octop-auto-backup-*。不会清理手动的 octop-backup-*。
include_config	bool	true	新归档是否包含 config.json 与 env。
include_workspaces	bool	true	是否包含专家工作区。
include_skill_packages	bool	true	是否包含全局技能包。
include_plugins	bool	true	是否包含已安装插件。
include_knowledge	bool	true	是否包含知识库文件。
include_chats	bool	false	是否包含聊天记录和运行轨迹。默认关闭，避免归档过大。

可用 OCTOP_BACKUP_AUTO_ENABLED、OCTOP_BACKUP_SCHEDULE、OCTOP_BACKUP_RETENTION_COUNT 和 OCTOP_BACKUP_INCLUDE_* 覆盖。详见备份与恢复。

​

示例 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": ["https://app.example.com"],
  "default_timezone": "America/New_York",
  "enable_dashboard": true,
  "enable_api_docs": false,
  "require_setup_password": true,
  "max_upload_mb": 100,
  "backup": {
    "auto_enabled": false,
    "schedule": "cron:0 4 * * *",
    "retention_count": 7
  },
  "database": {
    "driver": "postgresql",
    "host": "127.0.0.1",
    "port": 5432,
    "database": "octop",
    "user": "octop"
  },
  "tls": {
    "enabled": true,
    "cert_file": "/etc/ssl/octop/cert.pem",
    "key_file": "/etc/ssl/octop/key.pem"
  }
}

将 "enable_api_docs": true 可在 /api/docs 打开 Scalar，便于浏览端点和发送测试请求。

修改 config.json 后需重启才生效。系统服务用 octop service restart，前台模式则停止后重新执行 octop run。