内容
# 安全代理 CLI MCP
> 默认情况下，无 YOLO 的代理间工作流。
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](package.json)
安全代理 CLI MCP 封装了本地的 **Claude CLI** 和 **Codex CLI**，作为模型上下文协议工具。它为 MCP 客户端提供了一种受控的方式来请求本地编码代理进行审查、验证和任务，而无需暴露通用 shell，也无需默认执行。
在以下情况下使用：
- 本地 MCP 桥接 Claude 和 Codex CLI，而不是远程代理服务。
- 在运行任何操作之前，预览命令。
- 检查项目允许列表的真实路径，而不是广泛的文件系统访问。
- 对称的 Claude 和 Codex 工具，适用于 OpenClaw、mcporter 和其他 MCP 客户端。
这适用于希望具有安全默认值的嵌套代理工作流的开发人员和代理操作员。无聊就是在这里工作。
> 独立项目。 不隶属于 Anthropic、OpenAI、OpenClaw 或模型上下文协议项目。
## 它做什么
安全代理 CLI MCP 封装了两个 stdio MCP 服务器：
| 包 | 二进制文件 | 包装 | 目的 |
| --- | --- | --- | --- |
| `@safe-agent-cli-mcp/claude-cli-mcp` | `claude-cli-mcp-server` | 本地 `claude` CLI | Claude 代码审查和任务工作流 |
| `@safe-agent-cli-mcp/codex-cli-mcp` | `codex-cli-mcp-server` | 本地 `codex` CLI | Codex CLI 审查和任务工作流 |
核心钩子很简单：您的主要代理可以将第二个本地编码代理作为工具调用，但包装器会首先返回命令预览，检查工作目录是否在允许列表中，避免 shell 字符串，并且需要显式写入门控才能执行任务。
## 功能
- **默认干运行：** 审查、任务和验证流程在执行前返回确切的命令和参数。
- **真实路径 cwd 允许列表：** `cwd` 和 `allowedRoots` 使用 `realpath` 解析，这会阻止常见的符号链接逃逸。
- **无 shell 启动：** CLI 通过 `spawn(command, args)` 运行，带有 `shell: false`，而不是 `sh -c`。
- **命令预览：** 验证和干运行响应显示将运行的内容，包括 cwd、参数、超时、沙箱和策略标志。
- **写入门控：** `claude_task` 和 `codex_task` 除非同时存在 `dryRun: false` 和 `allowWrites: true`，否则拒绝实际执行。
- **输出编辑：** 常见的承载令牌、API 密钥、GitHub 令牌和可选的电子邮件地址会尽力屏蔽。
- **Claude 和 Codex 对等性：** 匹配的状态、配置、验证、审查和任务工具适用于两个 CLI。
- **OpenClaw 和插件友好：** 包括 `.mcp.json`、`.claude-plugin/plugin.json`、插件元数据和示例。
- **mcporter 示例：** 包括可复制的 `mcporter call` 示例，用于验证和干运行审查流程。
## 架构
```text
MCP 客户端
调用 safe-claude 或 safe-codex 进行 stdio
验证输入、cwd、模型、超时、沙箱和写入门控
默认返回命令预览
可选地在没有 shell 的情况下启动本地 claude 或 codex
```
在 [`docs/architecture.md`](docs/architecture.md) 中了解更多。
## 工具表
| 服务器 | 工具 | 执行行为 | 主要用途 |
| --- | --- | --- | --- |
| Claude | `claude_status` | 仅运行 `claude --version` | 检查本地 CLI 可用性 |
| Claude | `claude_config` | 无代理任务执行 | 检查净化配置和检测到的 CLI 路径 |
| Claude | `claude_validate` | 绝不运行 Claude 任务 | 验证输入并返回将运行的 argv |
| Claude | `claude_review` | 干运行优先，读取导向保护文本 | 默认情况下请求 Claude 审查而无需编辑 |
| Claude | `claude_task` | 干运行优先，写入门控要求实际执行 | 请求 Claude 执行本地任务 |
| Codex | `codex_status` | 仅运行 `codex --version` | 检查本地 CLI 可用性 |
| Codex | `codex_config` | 无代理任务执行 | 检查净化配置和检测到的 CLI 路径 |
| Codex | `codex_validate` | 绝不运行 Codex 任务 | 验证输入并返回将运行的 argv |
| Codex | `codex_review` | 干运行优先，仅只读沙箱 | 默认情况下请求 Codex 审查而无需写入 |
| Codex | `codex_task` | 干运行优先，写入门控要求实际执行 | 请求 Codex 执行本地任务 |
## 快速入门
先决条件：
- 节点版本 20 或更高。
- 本地安装并认证 Claude CLI 和/或 Codex CLI（如果您计划执行实际运行）。
- 可以启动 stdio 服务器的 MCP 客户端。
```bash
git clone https://github.com/<owner>/safe-agent-cli-mcp.git
cd safe-agent-cli-mcp
npm install
npm run typecheck
npm run build
npm test
```
从示例中创建被忽略的本地配置文件：
```bash
cp packages/claude-cli-mcp/claude-mcp.config.example.json packages/claude-cli-mcp/claude-mcp.config.json
cp packages/codex-cli-mcp/codex-mcp.config.example.json packages/codex-cli-mcp/codex-mcp.config.json
```
在实际使用之前设置狭窄的项目根目录：
```json
{
"allowedRoots": ["/path/to/project"]
}
```
然后将您的 MCP 客户端指向一个或两个已构建的 stdio 服务器。安装路径是启动 MCP 服务器的机器上的存储库的绝对路径：
```json
{
"mcpServers": {
"safe-claude": {
"command": "node",
"args": ["/path/to/safe-agent-cli-mcp/packages/claude-cli-mcp/dist/index.js"]
},
"safe-codex": {
"command": "node",
"args": ["/path/to/safe-agent-cli-mcp/packages/codex-cli-mcp/dist/index.js"]
}
}
}
```
更多客户端代码片段请参见 [`examples/`](examples/)。
## 示例
### 干运行审查
```json
{
"cwd": "/path/to/project",
"prompt": "检查身份验证流程是否存在明显的错误。",
"dryRun": true
}
```
调用以下任一：
- `claude_review`
- `codex_review`
响应包含已解析的命令、argv、cwd、超时、输出上限、模型或沙箱设置和允许列表。在 `dryRun` 为 true 时，它不会运行下游 CLI。
### 执行前验证
```json
{
"cwd": "/path/to/project",
"prompt": "检查此任务是否被允许。",
"dryRun": true,
"timeoutSeconds": 120
}
```
调用以下任一：
- `claude_validate`
- `codex_validate`
验证在自动化流程中有用，因为它在不启动嵌套代理的情况下检查形状和策略。
### 显式允许任务运行
```json
{
"cwd": "/path/to/project",
"prompt": "更新新解析器行为的测试。",
"dryRun": false,
"allowWrites": true
}
```
两个字段对于任务执行都是必需的。如果缺少任一字段，`claude_task` 和 `codex_task` 将拒绝运行。
### mcporter 示例
```bash
mcporter tools safe-codex
mcporter tools safe-claude
mcporter call safe-codex codex_validate '{"cwd":"/path/to/project","prompt":"Review this code","dryRun":true}'
mcporter call safe-claude claude_validate '{"cwd":"/path/to/project","prompt":"Review this code","dryRun":true}'
```
参见 [`examples/mcporter/call-examples.md`](examples/mcporter/call-examples.md)。
## OpenClaw 插件用法，可选
此存储库包含 OpenClaw 兼容的打包层：
- `.claude-plugin/plugin.json` 允许 OpenClaw 将存储库检测为 Claude 兼容包。
- `.mcp.json` 使用 `${CLAUDE_PLUGIN_ROOT}` 占位符注册 `safe-claude` 和 `safe-codex`。
- `plugin/openclaw.plugin.json` 是未来原生插件流程的元数据。
先构建和验证：
```bash
npm install
npm run build
npm run validate:plugin
```
可选的本地注册，只有在您审查命令并选择安装插件后运行：
```bash
openclaw plugins install --link .
openclaw plugins enable safe-agent-cli-mcp
openclaw plugins inspect safe-agent-cli-mcp --json
```
不要手动编辑实时 OpenClaw 配置。使用 OpenClaw CLI 命令进行注册和删除。插件说明位于 [`plugin/README.md`](plugin/README.md)，OpenClaw 示例位于 [`examples/openclaw/`](examples/openclaw/)。
## 安全模型摘要
安全代理 CLI MCP 在通用 shell 工具的情况下减少了爆炸半径，但它不是一个正式的沙箱或 DLP 系统。
| 控制 | 它做什么 | 警告 |
| --- | --- | --- |
| 干运行默认 | 返回命令预览而不执行下游 CLI | 调用者仍然可以请求实际执行 |
| 真实路径 cwd 允许列表 | 需要 `cwd` 解析为配置的根目录 | 它控制进程启动目录，而不是下游 CLI 可能读取的每个文件 |
| 无 shell | 使用 `spawn(command, args)` 带有 `shell: false` | 下游 CLI 有其自己的行为和工具策略 |
| 写入门控 | 任务工具需要 `dryRun: false` 加上 `allowWrites: true` | 审查工具由包装器策略保护，而不是 OS 级别隔离 |
| Codex 沙箱标志 | 默认情况下，审查为 `read-only`，任务为 `workspace-write` | Codex `read-only` 是一种写入安全控制，而不是完全读取隔离的证明 |
| Claude 权限模式 | 默认情况下，使用 Claude CLI 权限行为，并阻止 Bash/Edit/Write 进行审查 | Claude 权限语义委托给已安装的 Claude CLI |
| 编辑 | 屏蔽通用令牌模式和可选电子邮件 | 仅限于尽力而为，不要在提示中发送机密 |
在使用敏感存储库中的实际执行之前，请参见 [`SECURITY.md`](SECURITY.md) 和 [`docs/security-model.md`](docs/security-model.md)。
## 限制
- 这不是一个正式的沙箱、容器、VM、策略引擎或机密边界。
- Codex `read-only` 应被视为一种防止写入的控制，而不是保证读取隔离。
- Claude 权限行为取决于已安装的 Claude CLI 和您的本地配置。`bypassPermissions` 在此处不是默认设置。
- 编辑是基于模式的尽力而为。
- 下游 CLI 行为可能会随着版本的更新而变化。在需要重现性的地方，请固定并测试 CLI 版本。
- 该项目是独立的，与 Anthropic、OpenAI、OpenClaw 或模型上下文协议项目无关。
## 比较
| 能力 | 通用 shell MCP | 一次性提示脚本 | 安全代理 CLI MCP |
| --- | ---: | ---: | ---: |
| 暴露任意 shell 命令 | 是 | 通常否 | 否 |
| 默认先干运行 | 很少 | 有时 | 是 |
| 显示确切的命令预览 | 有时 | 有时 | 是 |
| 真实路径 cwd 允许列表 | 很少 | 有时 | 是 |
| Claude 和 Codex 特定标志 | 否 | 有限 | 是 |
| 可写入工具门控 | 很少 | 自定义 | 是 |
| 输出编辑 | 很少 | 自定义 | 是 |
| OpenClaw 包元数据 | 否 | 否 | 是 |
| 最佳拟合 | 最大灵活性 | 狭窄的本地工作流 | 受控的嵌套代理调用 |
有关更长的版本，请参见 [`docs/comparison.md`](docs/comparison.md)。
## ClawHub 和 GitHub 发布
GitHub 存储库：<https://github.com/udaymanish6/openclaw-safe-agent-cli-mcp>
存储库的结构适用于 GitHub 和 ClawHub 展示，包括资产、示例、文档、包元数据和 OpenClaw 插件文件。在添加 npm 或 ClawHub 徽章之前，请确认最终的注册名称、URL 和发布权限。本 README 故意避免伪造的已发布状态徽章。
## 常见问题
### 这是否安装了 Claude 或 Codex？
不。它包装本地 CLI。请单独安装并认证 Claude CLI 和/或 Codex CLI。
### 干运行是否意味着无法出现任何问题？
干运行意味着此包装器不会启动下游任务。您的 MCP 客户端仍会收到命令预览和元数据，如果显式请求，则可以进行实际执行。
### 为什么 `allowedRoots` 默认为空？
公共默认值不应授予对主目录或工作区的访问权限。仅添加您希望包装器使用的项目根目录。
### 我可以使用 Claude 或 Codex 吗？
是的。仅注册您需要的服务器。
### 是否可以将其公开暴露在互联网上？
不。这些服务器设计用于本地 stdio MCP 使用。不要将它们暴露为公共网络服务。
### 审查工具可以写入文件吗？
包装器配置审查工具为只读且默认为干运行。Codex 审查仅限于 `read-only`；Claude 审查添加了保护文本并拒绝 Bash/Edit/Write 工具。这是包装器在下游 CLI 周围的策略，而不是正式的沙箱。
### 为什么不直接给代理一个 shell？
因为 shell 是一个命令执行原语。该项目公开了一个较小的接口，带有验证、预览、允许的 cwd 和工具特定的安全门控。
## 开发
```bash
npm install
npm run typecheck
npm run build
npm test
npm run validate:plugin
```
有用文件：
- [`packages/shared/src/index.ts`](packages/shared/src/index.ts)：cwd 验证、编辑、命令执行和响应帮助程序。
- [`packages/claude-cli-mcp/src/index.ts`](packages/claude-cli-mcp/src/index.ts)：Claude 工具定义和验证。
- [`packages/codex-cli-mcp/src/index.ts`](packages/codex-cli-mcp/src/index.ts)：Codex 工具定义和验证。
- [`tests/`](tests/)：干运行、允许列表、模型、写入门控和编辑测试。
- [`CONTRIBUTING.md`](CONTRIBUTING.md)：贡献说明。
贡献应保持核心承诺完整：无通用 shell、干运行优先、显式写入门控和狭窄的本地配置。
## 许可证
MIT。参见 [`LICENSE`](LICENSE)。
