For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /cli/server-commands.md.
  • 简体中文
  • Octop 服务器命令:init、run、service 与 update

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

    octop init

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

    交互式设置
    非交互式设置
    交互式设置
    octop init

    选项

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

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


    octop run

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

    默认
    自定义主机与端口
    使用自签名证书的 HTTPS
    使用自有证书的 HTTPS
    默认
    octop run

    选项

    选项默认值描述
    --host TEXT127.0.0.1绑定主机。优先级:本参数 > OCTOP_BIND_HOST > config.json > 默认值
    --port INTEGER8088监听端口。优先级:本参数 > OCTOP_PORT > config.json > 默认值
    --reload / --no-reload关闭启用 uvicorn 自动重载(仅开发环境)
    --ssl / --no-ssl关闭启用 HTTPS
    --certfile PATH—PEM 格式 TLS 证书
    --keyfile PATH—PEM 格式 TLS 私钥
    --log-levelinfo可选:debug、info、warning、error
    注意

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

    说明

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


    octop service

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

    启动(若未安装则先安装)
    停止
    重启
    检查状态与健康
    启动(若未安装则先安装)
    octop service start
    说明

    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)见升级版本。

    检查并安装
    仅检查,不安装
    包含预发布
    检查并安装
    octop update

    选项

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

    octop captcha

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

    octop captcha reset

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


    octop migrate

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

    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 的登录导入工作台的云服务器存储:

    octop cloud import-tccli --profile default

    在工作台里授权时,Octop 也会写回 ~/.tccli。见云服务器。

    octop user

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

    改密示例:

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

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

    octop user reset-mfa <用户名>

    完整示例见 渠道与定时任务:octop user。

    octop clean

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

    仅清除 CLI 状态(保留数据)
    删除数据,保留 venv/ 和 bin/
    跳过确认提示
    仅清除 CLI 状态(保留数据)
    octop clean

    选项

    选项描述
    (默认)删除 ~/.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(固定的默认用户、专家)。

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

    子命令

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

    octop completion

    生成并安装 Shell 命令补全。

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

    运行 octop completion install 后,重新打开终端或执行 source ~/.zshrc(或 source ~/.bashrc)即可启用补全。


    octop version

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

    octop version