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

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

注意

损坏的 config.json 是硬错误。Octop 会指出路径和解析位置，然后拒绝启动或改写该文件。它不会把坏文件当成空对象——那样会清掉其他设置（例如 PostgreSQL 的 database 段）并悄悄退回 SQLite。修好 JSON 后再重试。

字段参考

核心设置

字段	类型	默认值	描述
`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。

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

#字段参考

#核心设置

#database 段

#tls 段

#backup 段

#示例 config.json