> 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 参考：所有服务器配置字段

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`           | —      | 已忽略             | 已下线。Octop 忽略该字段和 `OCTOP_HISTORY_V2_ENABLED`。启动时会把已有的 `history_v2.sqlite` 迁回原有历史表。       |
| `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`，并把文件权限限制为服务账户可读。
> 


`driver` 为 `postgresql` 时，技能包文件和知识库原文存在这个数据库里，知识库向量使用 pgvector。SQLite 仍把它们放在本地目录。建索引之前先启用 `vector` 扩展。这一版不会把已有的 SQLite 内容迁到 PostgreSQL，安装时就要选定驱动。

### `tls` 段

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

完整步骤见 [TLS 与服务](/guide/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_*` 覆盖。详见[备份与恢复](/guide/guides/backup-restore.md)。

## 示例 config.json

```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`。
> 

