使用命令行与终端管理台
除了桌面端应用，OmniProxy 还提供可在终端直接运行的 omniproxy 命令行工具（CLI）及交互式终端管理台（TUI）。你可以用它查询状态、编写自动化脚本，或交由 AI 工具代为操作，全过程无需额外搭建或暴露另一套管理用的 HTTP 服务。
1. 确认当前 CLI 程序与数据隔离边界
在开始操作前，请先在终端运行以下命令，核对当前调用的程序路径与版本：
command -v omniproxy
omniproxy --version
omniproxy --help请务必分清“独立 CLI”与“桌面端 App”的边界：
- 请勿混用内部组件：桌面端
OmniProxy.app内部打包的 Helper 仅供 App 自身拉起后台 Runtime 使用，不能将其复制或创建符号链接出来当成独立 CLI 使用。 - 数据实例相互独立：独立 CLI 与桌面端 App 拥有各自独立的数据目录与状态边界。哪怕运行在同一台 Mac 上，两者的配置、模型来源和调用记录也不会自动互通。
- 各管各的实例：本章介绍的所有命令均用于操作独立 CLI 实例。请勿尝试用
--data-dir参数强行指向桌面端 App 的私有资料库来篡改 App 状态；如需修改桌面端 App 的配置，请直接在 App 界面中操作。
终端提示找不到 omniproxy 命令怎么办？
- 先使用独立 CLI 安装目录下的完整绝对路径运行
--version（若路径包含空格，请用双引号包裹）。 - 如需在任意目录下直接输入
omniproxy调用，请将你自己的独立 CLI 安装目录加入用户PATH环境变量，或创建自己可核对的符号链接（注意不要覆盖系统里不认识的同名程序）。 - 如果你是让桌面端 AI Agent 调用 CLI，由于 Agent 进程未必会加载你终端的 Shell 配置文件（如
.zshrc），建议直接在 Agent 中配置独立 CLI 的绝对路径。 - 移动过安装目录后，请重新检查符号链接是否失效；一切用法以当前版本的
omniproxy --help为准，不要根据过时教程盲猜path install等不存在的子命令。
2. 常用命令组速查
你可以通过 --help 逐层查看各个子命令的用法：
omniproxy sources --help
omniproxy models --help
omniproxy config --help
omniproxy gateway --help| 命令组 | 核心用途 |
|---|---|
models、sources | 管理本地模型与远程云端模型来源 |
mappings、auto | 配置模型映射（按用途、模型虚拟）与自动匹配 |
gateway、service、doctor | 查看网关能力、启停后台服务与执行系统诊断 |
config | 查询与修改实例配置项 |
retrieval、search | 管理检索来源、执行网页正文读取与关键词搜索 |
glossary、translate、redaction | 管理术语词表、运行翻译任务与配置文本脱敏 |
logs、stats、jobs | 查询调用记录、用量统计与后台任务状态 |
注意：某个子命令出现在
--help帮助列表中，不代表当前安装包已开放其全部底层能力。若执行时返回错误码capability_not_ready，说明当前发行物暂未就绪该项能力，请按实际限制处理，不能把“能打印帮助信息”当成功能已跑通。
3. 查询与修改配置的标准闭环示例
在命令行修改任何设置时，建议遵循“先查询原值 → 执行修改 → 读回验证”的三步闭环。以下以将界面外观改为深色（dark）为例：
# 1. 查询当前外观设置并记下原值
omniproxy config get ui.appearance --output json
# 2. 将外观修改为 dark
omniproxy config set ui.appearance dark --output json
# 3. 重新读取，验证修改已落盘生效
omniproxy config get ui.appearance --output json关键参数与数据目录规范
- 解析结构化输出：使用
--output json时，脚本或调用方应先检查最外层的ok是否为true，成功后再读取data字段；若ok为false，则从error中读取错误码与提示信息。对于支持流式逐行输出的命令，可使用--output jsonl。 - 语言与破坏性确认：
--lang仅控制帮助文本和人类可读提示的语言，不会改变 JSON 结构化字段名。--dry-run仅用于预演可能发生的动作，不代表操作已实际执行；--yes用于确认具有副作用或破坏性的操作，切勿在日常排错时随手加上--yes。 - 保持
--data-dir一致：如果不指定--data-dir，CLI 会读写该发行物的默认数据目录。如果你需要使用自定义的独立 CLI 数据目录，请先记下程序完整路径与目标目录路径，并在每一条查询、修改、验证命令中始终带上完全相同的--data-dir参数（切勿上一条命令带了--data-dir，下一条命令又漏掉，然后拿两个不同实例的结果做对比）。例如：
omniproxy --data-dir "/你自己的CLI数据目录" config get ui.appearance --output json(请将示例路径替换为你实际准备的 CLI 专用目录，切勿指向桌面端 App 的私有资料库，也不要拿正式工作目录测试删除操作。)
service命令的特殊限制：omniproxy service命令专门用于管理当前设备上的默认独立 CLI 服务，不接受--data-dir参数。检查默认服务状态请直接运行：
omniproxy service status --output json请勿试图给 service 命令追加自定义目录参数，也不能用它的返回结果去判断自定义目录实例或桌面端 App 是否正在运行。
4. 使用终端交互管理台（TUI）
如果你安装的独立 CLI 版本包含 TUI 模块（可先运行 omniproxy tui --help 核对当前版本是否支持），可以在交互式终端中直接运行 omniproxy tui 打开全屏终端管理台，集中管理监控、模型、来源、映射、隐私工具与系统设置。若当前安装包不支持 TUI，请直接使用普通 CLI 子命令或桌面端 App。
| 快捷键 | 功能说明 |
|---|---|
1 – 6 | 切换顶部/左侧的六大功能区域 |
Tab / Shift-Tab | 在页面元素或表单输入框之间切换焦点 |
↑ / ↓、Enter | 上下移动选中项，按回车打开详情或进入编辑 |
e / a | 在支持该操作的页面中编辑当前项（e）或新增条目（a） |
/、r | 筛选当前列表（/）、刷新当前页面数据（r） |
Ctrl-S | 保存当前表单修改 |
Esc | 返回上一级或取消编辑（若有未保存内容会提示确认是否放弃） |
?、q | 查看快捷键帮助（?）、退出 TUI 界面（q） |
TUI 操作注意事项：
- 界面与后台服务解耦：按
q退出 TUI 界面不会自动停止后台正在运行的网关服务。 - 凭据安全：在编辑 API Key 等凭据时按
Esc取消，系统会保留原先已保存的凭据不变；只有执行明确的清除操作才会删除凭据。 - 运行环境要求：TUI 必须在可交互的真实终端窗口中运行，不能与
--output json、--output jsonl或--dry-run参数混用。 - 设置区服务控制并读回核对：在 TUI 的“设置”区域，可按页面底部提示使用
s（启动服务）、x（停止服务）、t（切换开机自启）和e（编辑配置）。在 TUI 内修改配置或按过s/x后，建议退出 TUI，使用同一 CLI 程序（及相同的数据目录参数）运行omniproxy config get <键名> --output json或omniproxy service status --output json读回真实状态，不要仅凭按过快捷键就主观认定服务已启停成功。
5. 启停服务与交由 AI 自动执行
管理独立 CLI 的后台服务与健康状态时，请先阅读 omniproxy service --help 与 omniproxy doctor --help，按当前版本提供的正式入口操作，并核对目标实例的身份与实际监听端口（不要看到某个端口有响应就想当然认为它属于当前 CLI 实例）。
如果你希望让具备命令执行能力的 AI 工具替你操作 CLI，请遵循让 AI 工具帮你操作 OmniProxy中的安全流程。