---
url: https://docs.ogmabox.com/zh/reference/cli.md
description: 从命令行运行 Ogma，用作本地代理服务器、MCP 进程、无头渗透测试命令或开发后端。
---

# CLI 参考 {#cli-reference}

Ogma 的 Rust 后端可以作为本地代理服务器、嵌入式 MCP 进程或无头渗透测试命令运行。

使用打包桌面版的用户通常从应用启动 Ogma。CLI 适用于开发、自动化以及服务器式的本地测试。

## 服务器模式 {#server-mode}

```bash
ogma \
  --listen 127.0.0.1:8080 \
  --api-port 127.0.0.1:8181 \
  --data-dir ./ogma-data
```

### 常用参数 {#common-flags}

| 参数 | 默认值 | 用途 |
| --- | --- | --- |
| `--listen` | `127.0.0.1:8080` | 代理监听地址。 |
| `--api-port` | `127.0.0.1:8181` | REST API 和前端服务器地址。 |
| `--data-dir` | `./ogma-data` | 项目数据库、证书、插件、导出内容和本地状态。 |
| `--max-plugin-size` | `52428800` | 插件包的最大大小，单位为字节。 |
| `--intercept-queue-cap` | `1000` | 拦截队列的最大条目数；达到上限后转发新流量。 |
| `--ui-dir` | 未设置 | 包含已构建前端文件的目录，由 API 服务器提供服务。 |

## OAST 参数 {#oast-flags}

| 参数 | 默认值 | 用途 |
| --- | --- | --- |
| `--oast-http-port` | `8888` | HTTP 回调监听器。使用 `0` 禁用。 |
| `--oast-https-port` | `8443` | HTTPS 回调监听器。使用 `0` 禁用。 |
| `--oast-dns-port` | `5353` | DNS 回调监听器。使用 `0` 禁用。 |
| `--oast-smtp-port` | `2525` | SMTP 回调监听器。使用 `0` 禁用。 |
| `--oast-domain` | `oast.local` | 生成回调主机名时使用的域名。 |
| `--oast-public-ip` | 未设置 | OAST DNS A 记录响应返回的公网 IP。 |

## 无头渗透测试模式 {#headless-pentest-mode}

`pentest` 子命令执行发现、被动分析以及可选的主动扫描，并输出 Markdown 报告。

```bash
ogma pentest https://example.com \
  --depth 3 \
  --concurrency 10 \
  --min-severity medium \
  --output report.md
```

### 渗透测试参数 {#pentest-flags}

| 参数 | 默认值 | 用途 |
| --- | --- | --- |
| `--depth` | `3` | 发现深度。`0` 表示无限制。 |
| `--concurrency` | `10` | 最大并发请求数。 |
| `--no-active` | 禁用 | 禁用主动扫描；仅执行发现和被动分析。 |
| `--min-severity` | `medium` | 触发退出码 `1` 的最低严重程度。有效值：`info`、`low`、`medium`、`high`、`critical`。 |
| `--output` | 标准输出 | 将报告写入文件，而不是标准输出。 |

退出码：

| 代码 | 含义 |
| --- | --- |
| `0` | 已完成，且没有发现项达到严重程度阈值。 |
| `1` | 已完成，且至少一个发现项达到严重程度阈值。 |
| `2` | 运行时错误或配置错误。 |

## MCP 模式 {#mcp-mode}

可以从 Ogma 设置启动 MCP，也可以通过独立的 `ogma-mcp` 可执行文件启动。当 Ogma 启动内部 MCP 进程时，隐藏的后端参数也支持嵌入式 MCP 模式。

常规设置请参阅 [MCP 设置](../mcp-setup.md)。

### 独立 `ogma-mcp` 参数 {#standalone-ogma-mcp-flags}

```bash
ogma-mcp \
  --api-url http://127.0.0.1:8181 \
  --body-preview-bytes 2048
```

| 参数 | 环境变量 | 默认值 | 用途 |
| --- | --- | --- | --- |
| `--api-url` | `OGMA_API_URL` | `http://127.0.0.1:8181` | 正在运行的 Ogma 后端 API URL。 |
| `--body-preview-bytes` | 未设置 | `512` | 读取工具返回的正文预览的最大字节数。 |
| `--allow-write-findings` | `OGMA_MCP_ALLOW_WRITE_FINDINGS` | 禁用 | 启用发现项创建、更新、标签和证据关联。 |
| `--allow-export-data` | `OGMA_MCP_ALLOW_EXPORT_DATA` | 禁用 | 启用导出任务创建。 |
| `--allow-read-secrets` | `OGMA_MCP_ALLOW_READ_SECRETS` | 禁用 | 返回未脱敏的环境变量值。 |
| `--allow-send-requests` | `OGMA_MCP_ALLOW_SEND_REQUESTS` | 禁用 | 启用发送流量、操控浏览器、爬取、探测、测试身份验证或连接 WebSocket 的工具。 |
| `--allow-run-workflows` | `OGMA_MCP_ALLOW_RUN_WORKFLOWS` | 禁用 | 启用工作流预览、运行和取消工具。 |
| `--allow-intercept-control` | `OGMA_MCP_ALLOW_INTERCEPT_CONTROL` | 禁用 | 启用拦截队列控制、转发、丢弃和修改。 |
| `--tool-profile` | `OGMA_MCP_TOOL_PROFILE` | `full` | 旧版兼容参数。始终公布所有工具，即使旧命令传入 `core` 或 `discovery`。`--mcp-tool-profile` 是其别名。 |

MCP 将协议消息写入标准输出，因此运行日志写入标准错误。

布尔权限环境变量接受 `true` 以启用对应能力。服务器没有每分钟或每会话的活动配额；各工具的限制仍然适用。不接受已移除的配额参数。Stdio 参数独立配置该进程，不受嵌入式 MCP 设置影响。

## 开发构建 {#development-builds}

仓库根目录提供本地构建脚本：

```bash
./build-local.sh
./build-desktop-local.sh
```

测试打包的 Electron 体验时使用桌面构建。测试 API 和 Web UI 行为时使用后端/前端构建。