> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Octop 服务器命令：init、run、service 与 update

这些命令控制 Octop 服务器生命周期——引导全新安装、启动服务器进程、注册为系统服务并保持最新。首次设置 Octop 时请按顺序运行；后续部署管理或升级时也会用到它们。

## `octop init`

引导 `~/.octop/`，创建 SQLite 数据库、JWT 密钥和首个管理员账户。首次启动服务器前运行一次即可。


```bash 交互式设置
octop init
```
```bash 非交互式设置
octop init --admin-username admin --admin-password mypassword1 --yes
```


### 选项

| 选项                          | 环境变量                       | 描述                     |
| --------------------------- | -------------------------- | ---------------------- |
| `--admin-username TEXT`     | `OCTOP_ADMIN_USERNAME`     | 首个管理员账户的用户名            |
| `--admin-password TEXT`     | `OCTOP_ADMIN_PASSWORD`     | 首个管理员账户的密码             |
| `--admin-display-name TEXT` | `OCTOP_ADMIN_DISPLAY_NAME` | 首个管理员账户的显示名称           |
| `--force`                   | —                          | 引导前清空已有 `~/.octop/` 内容 |
| `--yes`                     | —                          | 跳过所有交互式提示              |


> **说明**
> 
> `octop init` 对数据库是幂等的——在已有安装上再次运行是安全的，只会应用缺失的迁移。使用 `--force` 可清空 `~/.octop/` 并完全重新开始。
> 


***

## `octop run`

使用 uvicorn 在前台启动 Octop 服务器。单进程同时提供 Web 控制台、HTTP/SSE API 和 IM 渠道监听。


```bash 默认
octop run
```
```bash 自定义主机与端口
octop run --host 0.0.0.0 --port 8088
```
```bash 使用自签名证书的 HTTPS
octop run --ssl
```
```bash 使用自有证书的 HTTPS
octop run --ssl --certfile /path/cert.pem --keyfile /path/key.pem
```


### 选项

| 选项                       | 默认值         | 描述                                                     |
| ------------------------ | ----------- | ------------------------------------------------------ |
| `--host TEXT`            | `127.0.0.1` | 绑定主机。优先级：本参数 > `OCTOP_BIND_HOST` > `config.json` > 默认值 |
| `--port INTEGER`         | `8088`      | 监听端口。优先级：本参数 > `OCTOP_PORT` > `config.json` > 默认值      |
| `--reload / --no-reload` | 关闭          | 启用 uvicorn 自动重载（仅开发环境）                                 |
| `--ssl / --no-ssl`       | 关闭          | 启用 HTTPS                                               |
| `--certfile PATH`        | —           | PEM 格式 TLS 证书                                          |
| `--keyfile PATH`         | —           | PEM 格式 TLS 私钥                                          |
| `--log-level`            | `info`      | 可选：`debug`、`info`、`warning`、`error`                    |


> **注意**
> 
> 生产环境请勿使用 `--reload`。自动重载会在文件变更时重启进程，仅用于本地开发。
> 



> **说明**
> 
> 传入 `--host` 或 `--port` 会在 uvicorn 启动前把该值写入 `config.json`。损坏的 `config.json` 是硬错误——Octop 不会合并进空对象，以免清掉文件其余内容。
> 


***

## `octop service`

将 Octop 注册为系统服务，以便开机自启并在后台运行。


```bash 启动（若未安装则先安装）
octop service start
```
```bash 停止
octop service stop
```
```bash 重启
octop service restart
```
```bash 检查状态与健康
octop service status
```



> **说明**
> 
> `octop service` 会自动检测平台：Linux 使用 **systemd**，macOS 使用 **launchd**。`status` 子命令会探测 HTTP 健康端点，失败时打印日志提示。可通过 `--scope user` 或 `--scope system`（或 `OCTOP_SERVICE_SCOPE`）强制作用域。在 Linux 上，`start` 和 `restart` 会安装 systemd drop-in（`octop.service.d/10-nofile.conf`），设置 `LimitNOFILE=65535`。主 unit 文件不会被改写，除非文件缺失或传入 `--force-install`。要撤销：删除该 drop-in，然后执行 `systemctl daemon-reload && systemctl restart octop`。
> 


***

## `octop update`

检查 PyPI 上是否有更新的 Octop 版本并自动安装。默认**只查稳定版**。页面**管理 → 应用设置 → 应用更新**同样如此，除非你打开预发布。按安装方式升级（页面、脚本、Docker、飞牛OS）见[升级版本](/guide/guides/upgrade.md)。


```bash 检查并安装
octop update
```
```bash 仅检查，不安装
octop update --check
```
```bash 包含预发布
octop update --allow-prerelease
```


### 选项

| 选项                     | 描述                                  |
| ---------------------- | ----------------------------------- |
| `--check / --no-check` | 仅报告可用版本，不安装                         |
| `--yes` / `-y`         | 跳过确认提示                              |
| `--verbose` / `-v`     | 打印安装器输出                             |
| `--allow-prerelease`   | 检查和安装时包含 alpha / beta / rc / dev 版本 |

***

## `octop captcha`

对照本地数据库清除已保存的登录验证码设置。当云验证码配置错误（密钥不对、厂商不可达、主机名未加白名单）导致所有人无法进入页面时使用——设置页本身也需要登录。

```bash
octop captcha reset
```

登录会回退到内置滑块。这条命令**不会**改环境文件里的 `OCTOP_CAPTCHA_*`；如果锁定是它们造成的，请自行取消。若 `octop run` 已在运行，请重启。

***

## `octop migrate`

把 OpenClaw 或 Hermes Agent 的配置迁进一位专家。这条命令会短暂拉起进程内服务。如果 `octop run` 已在运行，迁完后重启它，新的提供商和通道才会加载。逐步操作见[从 OpenClaw 迁移](/guide/migrate/openclaw.md)和[从 Hermes Agent 迁移](/guide/migrate/hermes.md)。

```bash
octop --agent <id> migrate openclaw --dry-run
octop --agent <id> migrate hermes --from /srv/hermes --skip channels
```

| 来源  | 迁到哪里                                      |
| --- | ----------------------------------------- |
| 模型  | 提供商；还没有默认模型时，一并写入默认模型                     |
| 文件  | 工作区里的 `SOUL.md`、`USER.md`、`MEMORY.md` 等说明 |
| 技能  | 那位助手自己的技能，不含 Hermes 自带技能                  |
| MCP | 当前用户的自定义 MCP                              |
| 通道  | 专家上的对应通道，创建时为**停用**                       |

再跑一次会跳过已经存在的内容。`--overwrite` 会替换工作区文件、技能和默认模型。提供商、MCP 和通道不会被覆盖。通道保持停用，避免旧助手和 Octop 同时回复同一个机器人。`--dry-run` 不写任何文件。有条目失败时退出码为 1。

## `octop cloud`

把本机腾讯云 CLI 的登录导入工作台的云服务器存储：

```bash
octop cloud import-tccli --profile default
```

在工作台里授权时，Octop 也会写回 `~/.tccli`。见[云服务器](/guide/guides/cloud-hosts.md)。

## `octop user`

`octop user` 子命令全部离线操作本地数据库：`create`、`list`、`set-email`、`passwd`、`role`、`disable`、`delete`、`reset-mfa`。CLI **没有** `login` 子命令，也不往 `cli_state.json` 写 JWT。固定默认用户用 `octop config set-user`。

改密示例：

```bash
octop user passwd <用户名> --password <密码>
```

清掉验证器、通行密钥和恢复码，不改密码：

```bash
octop user reset-mfa <用户名>
```

完整示例见 [渠道与定时任务：octop user](/cli/channel-cron-commands.md#octop-user)。

## `octop clean`

重置 CLI 状态，或删除 `~/.octop` 下的数据并保留安装运行时。**具有破坏性**——运行前请仔细阅读帮助。


```bash 仅清除 CLI 状态（保留数据）
octop clean
```
```bash 删除数据，保留 venv/ 和 bin/
octop clean --all
```
```bash 跳过确认提示
octop clean --all --yes
```


### 选项

| 选项          | 描述                                                                 |
| ----------- | ------------------------------------------------------------------ |
| （默认）        | 删除 `~/.octop/cli_state.json`（固定的 `default_user` / `default_agent`） |
| `--all`     | 删除 `~/.octop` 下的数据，保留 `venv/` 和 `bin/`                             |
| `--yes`     | 跳过确认提示                                                             |
| `--dry-run` | 只打印将删除的路径                                                          |


> **注意**
> 
> `octop clean --all` 会删除数据库、工作区和配置，并保留安装运行时。操作前请确保已运行 `octop backup create`。
> 


***

## `octop config`

查看或编辑 `~/.octop/cli_state.json`（固定的默认用户、专家）。


```bash 查看当前 CLI 状态
octop config show
```
```bash 固定默认 --user
octop config set-user admin
```


### 子命令

| 子命令        | 描述            |
| ---------- | ------------- |
| `show`     | 打印当前 CLI 状态   |
| `set-user` | 固定默认 `--user` |

***

## `octop completion`

生成并安装 Shell 命令补全。


```bash 输出 bash 补全脚本
octop completion show --shell bash
```
```bash 输出 zsh 补全脚本
octop completion show --shell zsh
```
```bash 安装到 ~/.zshrc 或 ~/.bashrc
octop completion install
```



> **提示**
> 
> 运行 `octop completion install` 后，重新打开终端或执行 `source ~/.zshrc`（或 `source ~/.bashrc`）即可启用补全。
> 


***

## `octop version`

打印已安装的 octop 版本。与全局选项 `-v, --version` 等效。

```bash
octop version
```
