> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`，不要写在文件里。 |

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

### `tls` 段

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

完整步骤见 [TLS 与服务](https://octop.mintlify.site/zh/configuration/tls-service.md)，含自签证书。

### `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_*` 覆盖。详见[备份与恢复](https://octop.mintlify.site/zh/guides/backup-restore.md)。

## 示例 config.json

```json theme={null}
{
  "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"
  }
}
```

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.