内容
# cc-relay
[](https://pypi.org/project/cc-relay/)
[](https://pypi.org/project/cc-relay/)
[](LICENSE)
适用于 Claude Code 和 Codex 的自适应中断层。Relay 通过钩子拦截工具调用，根据您的批准历史学习，并自动决定允许哪些操作 — 只在需要实际决策时中断，并发送桌面通知，以便您不会疑惑任务为何停滞。
**核心思想：** 其他权限工具使用静态规则或每次调用大型语言模型。Relay 跟踪每个操作类型的实际批准率，并随着时间适应。在您批准 `git commit` 十次后，它将停止询问。高风险操作始终中断 — 其他操作随着使用变得更加安静。
[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
## 为什么选择 cc-relay
| | 静态允许列表 | 大型语言模型分类器 | **cc-relay** |
|---|---|---|---|
| 设置 | 手动规则维护 | 需要 API 密钥 | 零配置 |
| 从您学习 | 否 | 否 | **是** |
| 每次决策成本 | 免费 | ~$0.001/调用 | 免费 |
| 适应您的工作流程 | 否 | 否 | **是** |
| 离线工作 | 是 | 否 | **是** |
## 工作原理
```
代理即将执行工具（写入、bash、编辑、shell 命令等）
↓
PreToolUse 钩子触发 → relay 钩子 pre
↓
查找历史批准率 + 评估风险级别
↓
允许 → 工具立即执行，自动记录为已批准
中断 → 工具暂停或阻止，发送桌面通知，客户端请求您的决定
↓
用户确认 → 代理继续，PostToolUse 标记记录为已批准
用户拒绝 → 会话结束
↓
停止钩子触发 → 标记待处理记录为已拒绝 + 发送完成通知
↓
历史累积 → 相同操作类型随着时间变得更加安静
```
## 决策逻辑
| 条件 | 结果 |
|---|---|
| 高风险（删除文件、强制推送、删除表、系统路径） | 始终中断 |
| 低风险，有效权重 < 4 | 自动批准（无需基线） |
| 低风险，有效权重 ≥ 4，批准率 ≥ 90% | 自动批准 |
| 中等风险，有效权重 < 7 | 中断以建立基线 |
| 中等风险，有效权重 ≥ 7，批准率 ≥ 85% | 自动批准 |
| 其他情况 | 中断 |
批准率使用 **指数时间衰减** （半衰期：7 天）— 最近的决定比旧决定更有权重。如果您开始拒绝以前一直批准的操作， 加权批准率会迅速下降，Relay 会在几天内开始再次中断。旧批准会自然淡出，因此系统不会永久锁定为自动批准。
| 操作类型 | 描述 | 风险 |
|---|---|---|
| `file_write:system` | 写入 `/etc/`、`/usr/` 等 | 高 |
| `file_write:config` | 写入 `.env`、`.yaml`、`.toml` 等 | 中等 |
| `file_write:code` | 写入普通代码文件 | 中等 |
| `bash_write:git` | git commit / push / merge | 中等 |
| `bash_write:package_manager` | pip / uv / npm 安装 | 中等 |
| `bash_write:shell` | mv / cp / chmod 等 shell 操作 | 中等 |
| `file_delete` | rm、删除表等删除操作 | 高 |
| `bash_read` / `file_read` | 只读操作 | 低 |
## 安装
Relay 支持 **Claude Code** 和 **Codex**。将 MCP 服务器添加到代理配置中；首次启动时，Relay 会为两个客户端安装钩子：
- Claude Code 钩子：`~/.claude/settings.json`
- Codex 钩子：`~/.codex/config.toml`
**Claude Code 全局配置** — 添加到 `mcpServers` 字段的 **`~/.claude.json`**：
```json
{
"mcpServers": {
"relay": {
"type": "stdio",
"command": "uvx",
"args": ["cc-relay@latest"]
}
}
}
```
**Codex 全局配置** — 添加到 **`~/.codex/config.toml`**：
```toml
[mcp_servers.relay]
type = "stdio"
command = "uvx"
args = ["cc-relay@latest"]
```
重启代理。Relay 作为 MCP 服务器启动，并自动运行 `--install-all` 行为，因此 Claude Code 和 Codex 钩子都会保持最新。
## 卸载
```bash
uvx cc-relay --uninstall-all
```
## 通知支持
Relay 发送两种类型的桌面通知。文本根据系统语言自动切换（中文、英文、日语、韩语）。
- **中断**：当操作需要您的批准时 — 提示您返回终端
- **完成**：当代理完成响应时 — 这样您就知道任务已完成，即使您离开了
| 平台 | 实现 | 备注 |
|---|---|---|
| macOS | `osascript` | 内置，开箱即用 |
| Linux | `notify-send` | 需要桌面环境（Ubuntu/GNOME 默认） |
| Windows | `plyer` | 开箱即用 |
## MCP 工具
安装后，Relay 自动工作。您也可以直接在 Claude Code 或 Codex 中调用这些工具：
| 工具 | 描述 |
|---|---|
| `relay__get_stats_tool` | 查看所有操作类型的批准统计信息 |
| `relay__get_recent_decisions_tool` | 查看特定操作类型的最近决策历史 |
| `relay__reset_action_type_tool` | 清除操作类型的历史记录并重建基线 |
## 命令行界面
```bash
# 安装/卸载 Claude Code 和 Codex 钩子
uvx cc-relay --install-all
uvx cc-relay --uninstall-all
# 高级：仅管理一个客户端
uvx cc-relay --install
uvx cc-relay --install-codex
uvx cc-relay --uninstall
uvx cc-relay --uninstall-codex
# 查看操作类型的最近决策（默认 20）
uvx cc-relay --history bash_write:git
uvx cc-relay --history file_write:code 50
# 清除操作类型的历史记录
uvx cc-relay --reset bash_write:git
```
## 已知限制
Relay 钩子在 `--dangerously-skip-permissions` 模式下不会触发（该模式完全绕过钩子机制）。
Codex PreToolUse 钩子无法暂停内联批准提示。当 Relay 阻止 Codex 操作时，代理必须停止并等待您；如果您明确批准确切的操作并且代理重试它，Relay 会将最近的拒绝记录翻转为已批准并允许重试通过。
## 本地开发
```bash
git clone https://github.com/solost23/cc-relay
cd cc-relay
uv sync
uv run pytest
uv run mcp dev cc_relay/server.py
```
