cli-serve

用途

cli-serve 用于从命令行管理 OmniRoute 服务器的生命周期，包括启动、停止和重启服务器，以及管理守护进程模式、端口配置、自动恢复、系统托盘集成和仪表盘打开快捷方式。

主要能力

该技能提供以下子命令：

serve：启动服务器。支持标志 --port <port>、--no-open、--daemon、--log、--no-recovery、--max-restarts <n>、--tray、--no-tray、--ready-timeout <ms>、--tls-cert <path>、--tls-key <path>。示例：omniroute serve
stop：停止正在运行的服务器。示例：omniroute stop
restart：重启服务器。支持标志 --port <port>。示例：omniroute restart
dashboard：在浏览器中打开仪表盘。支持标志 --url、--port <port>、--tui。示例：omniroute dashboard

此外，omniroute 二进制还提供服务器生命周期相关命令：omniroute（启动服务器，默认端口 20128）、omniroute --port 3000（覆盖端口）、omniroute --no-open（不自动打开浏览器）、omniroute --mcp（以 MCP 服务器模式启动，stdio 传输）、omniroute open（dashboard 的别名）、omniroute status（运行时状态：运行时间、请求数、提供商）。

使用方式

安装

npm install -g omniroute          # npm registry
# 或：使用桌面应用捆绑的二进制文件

要求 Node.js ≥22.22.2 或 ≥24。

验证安装：

omniroute --version   # 打印已安装版本
omniroute --help      # 完整命令树

连接配置

每个与服务器通信的 CLI 命令读取两个值：

Base URL：OMNIROUTE_BASE_URL 或 --base-url
API key：OMNIROUTE_API_KEY 或 --api-key

默认 base URL：http://localhost:20128

export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="sk-..."          # 来自 Dashboard → API Manager

远程服务器：

export OMNIROUTE_BASE_URL="https://your-server.com"

全局标志

--base-url <url>：为本次调用覆盖服务器 URL
--api-key <key>：为本次调用覆盖 API key
--output <format>：输出格式：table（默认）、json、jsonl、csv
--json：--output json 的简写
--non-interactive：禁用提示，用于 CI / shell 脚本
--no-open：启动时不自动打开浏览器
--port <n>：覆盖默认端口 20128
--help, -h：显示当前命令的帮助
--version, -v：打印已安装版本

输出格式

所有列表命令支持 --output：

omniroute combo list                      # 人类可读表格
omniroute combo list --output json        # JSON 数组
omniroute combo list --output jsonl       # 每行一个 JSON 对象
omniroute combo list --output csv         # 带表头的 CSV

快速开始

# 1. 启动服务器
omniroute

# 2. （首次运行）交互式设置向导
omniroute setup

# 3. 验证一切正常
omniroute doctor

适用场景

需要在本地或远程启动、停止、重启 OmniRoute 服务器
需要以守护进程模式运行服务器并配置自动恢复
需要配置端口、TLS 证书、系统托盘集成
需要打开仪表盘或查看运行时状态
需要在 CI / Docker 环境中以非交互方式完成设置
需要备份与恢复配置和数据库
需要配置开机自启（系统托盘 / 启动项）
需要通过隧道暴露本地实例（Cloudflare、Tailscale、ngrok）
需要查看日志、诊断健康状态、更新版本

限制

需要 Node.js ≥22.22.2 或 ≥24
需要安装 omniroute CLI（npm install -g omniroute 或使用桌面应用捆绑的二进制文件）
连接服务器需要正确的 Base URL 和 API key
隧道功能依赖外部工具（如 cloudflared、tailscale、ngrok）
部分恢复操作（如 reset-encrypted-columns --force）会清空加密凭据，需谨慎使用
文档未提供收费、价格或平台限制信息

错误处理

Connection refused → 服务器未运行；运行 omniroute 或 omniroute serve
401 Unauthorized → API key 错误或缺失
command not found: omniroute → 不在 PATH 中；检查 npm root -g 或重新安装
doctor 报告 SQLite 不兼容 → 在应用目录运行 npm rebuild better-sqlite3
doctor 显示 STORAGE_ENCRYPTION_KEY 缺失 → 在 .env 中设置密钥，或运行 reset-encrypted-columns --force 清空并重新输入凭据
doctor 报告原生二进制失败 → 在 OmniRoute 应用目录运行 npm rebuild better-sqlite3
tunnel create cloudflare 挂起 → 确保已安装 cloudflared：brew install cloudflare/cloudflare/cloudflared