| title: CLI 参考 | |
| # CLI 参考 | |
| 本页介绍 Koharu 桌面二进制暴露的命令行参数。 | |
| Koharu 使用同一个二进制来支持： | |
| - 桌面启动 | |
| - 本地 Headless Web UI | |
| - 本地 HTTP API | |
| - 内置 MCP 服务器 | |
| ## 常见用法 | |
| ```bash | |
| # macOS / Linux | |
| koharu [OPTIONS] | |
| # Windows | |
| koharu.exe [OPTIONS] | |
| ``` | |
| ## 参数 | |
| | 参数 | 含义 | | |
| | --- | --- | | |
| | `-d`, `--download` | 预取运行时库与默认视觉 / OCR 栈，然后退出 | | |
| | `--cpu` | 即使检测到 GPU，也强制使用 CPU | | |
| | `-p`, `--port <PORT>` | 把本地 HTTP 服务绑定到指定端口，而不是随机端口 | | |
| | `--host <HOST>` | 把 HTTP 服务绑定到指定主机，而不是默认的 `127.0.0.1` | | |
| | `--headless` | 不启动桌面 GUI，仅运行本地服务 | | |
| | `--debug` | 输出面向调试的控制台日志 | | |
| ## 行为说明 | |
| 有些参数影响的不只是启动外观： | |
| - 不传 `--port` 时，Koharu 会选择一个随机本地端口 | |
| - 不传 `--host` 时，Koharu 仅绑定 `127.0.0.1`，所以 API 只能从同一台机器访问 | |
| - 使用 `--headless` 时，不打开 Tauri 窗口，但仍然提供 Web UI 与 API | |
| - 使用 `--download` 时，预取完依赖后即退出，不会继续常驻 | |
| - 使用 `--cpu` 时，视觉栈和本地 LLM 都不会使用 GPU 加速 | |
| 当你设置了固定端口后，主要本地端点是： | |
| - `http://localhost:<PORT>/` | |
| - `http://localhost:<PORT>/api/v1` | |
| - `http://localhost:<PORT>/mcp` | |
| ## 常见模式 | |
| 在固定端口启动 Headless Web UI： | |
| ```bash | |
| koharu --port 4000 --headless | |
| ``` | |
| 使用纯 CPU 推理： | |
| ```bash | |
| koharu --cpu | |
| ``` | |
| 提前下载运行时包： | |
| ```bash | |
| koharu --download | |
| ``` | |
| 在固定端口启动本地 MCP 端点： | |
| ```bash | |
| koharu --port 9999 | |
| ``` | |
| 然后让 MCP 客户端连接： | |
| ```text | |
| http://localhost:9999/mcp | |
| ``` | |
| 显式启用调试日志： | |
| ```bash | |
| koharu --debug | |
| ``` | |
| 绑定到所有网络接口，让局域网内的其他机器也能访问 Web UI 与 API： | |
| ```bash | |
| koharu --host 0.0.0.0 --port 4000 --headless | |
| ``` | |
| 这是在容器或虚拟机中运行 Koharu、且桌面客户端位于另一台主机时的常见模式。任何不同于 `127.0.0.1` 的地址都会刻意暴露给网络，因此只有当你确实需要非环回访问时，才设置 `--host`。 | |