# chat-with-hermes

**ChatGPT 想，本机干。** —— 让 ChatGPT 网页版当大脑，你的机器当手脚。

ChatGPT 订阅里那个「想得很清楚」的模型，现在可以直接读你的文件、搜你的代码、跑你的命令、驱动本机的 Codex CLI。
走的是 **ChatGPT 官方自定义连接器（MCP）**，不是逆向、不是模拟点击：问答往返几秒，随时可断，全部动作留审计。

> English quickstart: [jump](#english-quickstart)

```
┌──────────────┐    MCP over HTTPS    ┌────────────────────┐   子进程    ┌──────────────┐
│ ChatGPT 网页 │ ───────────────────► │ chat-with-hermes   │ ─────────► │ bash / codex │
│  （思考）    │ ◄─────────────────── │ 本地 MCP 服务 :8770│ ◄───────── │  （执行）    │
└──────────────┘   工具结果回到上下文  └────────────────────┘    输出     └──────────────┘
                                             │
                                       data/audit.jsonl（谁在什么时候干了什么）
```

## 为什么不用 codex-with-chatgpt

[codex-with-chatgpt](https://github.com/XiaoDuoYa/codex-with-chatgpt) 是好项目：它用本地浏览器 + 控制消息把 ChatGPT 网页接进 Codex 的循环。
本项目换了那条最脆弱的路：ChatGPT 现在原生支持自定义连接器（MCP）。于是

| | codex-with-chatgpt | chat-with-hermes |
|---|---|---|
| 接入方式 | 本地浏览器 + CDP 注入控制消息 | 官方自定义连接器（MCP over HTTPS） |
| 需要登录态/配对码 | 需要 | 不需要（令牌在 URL 里） |
| 往返延迟 | 分钟级 | 秒级 |
| 依赖 | Node ≥20 + 一堆 npm 包 | **Python ≥3.11，零第三方依赖** |
| 执行器 | Codex | 文件读写 / shell / Codex，可扩展 |

## 安装

```bash
# 方式一：pipx（推荐）
pipx install git+https://github.com/00000linlin/chat-with-hermes

# 方式二：uv
uv tool install git+https://github.com/00000linlin/chat-with-hermes

# 方式三：克隆即用（免安装）
git clone https://github.com/00000linlin/chat-with-hermes && cd chat-with-hermes
./cwh doctor
```

## 三步跑起来

```bash
cwh setup        # 生成 ~/.chat-with-hermes/{config.toml, data/token.txt}
cwh start        # 起本地 MCP 服务（默认 0.0.0.0:8770）
cwh tunnel       # 自动下载 cloudflared 起隧道，打印「连接器 URL」
```

把打印出来的 URL 填进 ChatGPT：**设置 → 插件 → 添加自定义连接器** →
名称随意（如 `chat-with-hermes`）→ 服务器 URL 填那条带 `?t=` 的地址 →
身份验证选 **无身份验证** → 勾风险提示 → 创建。然后在对话里勾上它，说：

> 用 health 看看本机状态，再 grep 一下当前目录里所有 TODO。

如果你从 OpenWrt / NAS / 服务器用 CDP 自动驱动一个已登录的 ChatGPT 浏览器发消息，**每次发送前先把 ChatGPT 顶部的「聊天/工作」切到「聊天」**，否则可能落在 Work 模式而看不到自定义连接器。示例见 [`examples/chatgpt_cdp_mode.py`](examples/chatgpt_cdp_mode.py)。

## 工具（9 个）

| 工具 | 作用 | 是否需要人类批准 |
|---|---|---|
| `health` | 自检：工作区、命令策略、Codex 可用性 | 否 |
| `read_file` | 读文本文件（200KB 上限） | 否 |
| `list_dir` | 列目录 | 否 |
| `grep_files` | 正则搜代码（跳过 .git/node_modules 等） | 否 |
| `write_file` | 写文件，旧版自动备份 `.bak.<时间戳>` | 否（可关） |
| `shell` | 执行命令（bash -lc） | **白名单前缀直接跑，其余挂起等你在本机批准** |
| `codex_task` | 让本机 Codex CLI 写代码/重构/跑测试 | 否，但受 `codex.sandbox` 限制 |
| `job_get` | 查后台任务（`codex_task(background=true)`） | 否 |
| `pending_approvals` | 看哪些命令在等人批准 | 否 |

## 安全模型

三层，默认都开着：

1. **路径沙箱** —— 只能读写 `workspace.roots` 里的路径；`deny_globs` 让 `id_rsa*`、`.env`、`*.pem`、`Cookies` 这类文件即使在工作区里也读不到。
2. **命令分级** —— `shell.mode = "guard"`：白名单前缀（`ls`/`grep`/`git status`/`python3`…）直接执行；危险模式（`rm -rf /`、`mkfs`、`dd if=`…）直接拒；其余进批准队列。
3. **人类批准通道** —— ChatGPT **无法自己批准自己**。挂起的命令必须你在本机终端敲 `cwh approve <id>` 才会执行，这一条正好对得上「最后一步由人确认」的直觉。

所有工具调用（含参数、耗时、返回大小）都写进 `data/audit.jsonl`；MCP 侧请求写 `data/access.log`。
详见 [docs/security.md](docs/security.md)。

## 常用命令

```bash
cwh status          # 服务/隧道/待批准/最近访问
cwh log             # 服务日志（data/server.log）
cwh pending         # 待批准命令（--all 连历史）
cwh approve <id>    # 批准并执行
cwh reject <id>     # 拒绝
cwh selftest        # 把 9 个工具全打一遍
cwh doctor          # 体检（Python 版本、配置、端口、Codex、cloudflared）
cwh url             # 只打印连接器 URL
```

## 配置（`~/.chat-with-hermes/config.toml`）

```toml
[server]
host = "0.0.0.0"
port = 8770
data_dir = "~/.chat-with-hermes/data"

[workspace]
roots = ["/home/you/projects"]   # 想让它碰几个目录就写几行
allow_write = true

[shell]
mode = "guard"                   # guard（推荐）| auto（全放行）

[codex]
enabled = true
bin = "codex"
sandbox = "workspace-write"      # read-only | workspace-write | danger-full-access
```

## 常见问题

**ChatGPT 能自己批准命令、把自己放出去吗？**
不能。批准动作只存在于 `cwh approve` 这个本地命令里，模型侧没有对应工具。

**隧道地址每次重启都变？**
quick tunnel 免费但地址随机。要固定就用自己的域名起 named tunnel，然后把地址写进 `cwh url --base https://your.domain`。

**工具调用会不会超时？**
ChatGPT 侧一次工具调用等不了太久，超过一分钟的活请 `codex_task(background=true)` + `job_get` 轮询。

**它会看到我的 API key 吗？**
`read_file` 受沙箱 + `deny_globs` 双重限制；另外审计日志里 `token`/`key`/`secret`/`password`/`cookie` 字段一律记成 `<redacted>`。

## English quickstart

```bash
pipx install git+https://github.com/00000linlin/chat-with-hermes
cwh setup && cwh start && cwh tunnel     # prints a connector URL
```

Paste that URL into ChatGPT → Settings → Plugins → Add custom connector → Authentication: *No authentication* → Create.
Then in a chat, enable the connector and ask it to `list_dir` or `grep_files`. It reads files, runs whitelisted shell commands, and drives your local Codex CLI — anything else waits for you to run `cwh approve <id>` locally.

## License

MIT