内容
# Hermes + Claude 代码
**Hermes 代理 → Claude 代码，通过任何与 OpenAI 兼容的 API。**
将编码任务直接输送到 Claude 代码，从您的 AI 代理，路由通过任何代理（OpenRouter，VansRouter，LiteLLM，9Router）或直接提供商（OpenAI，Anthropic，Gemini 等）。
```
┌─────────────┐ MCP/stdio ┌──────────────┐ HTTP/JSON ┌─────────────┐
│ Hermes │ ◄─────────────────► │ cc-mcp- │ ◄───────────► │ Any │
│ 代理 │ │ server.py │ │ OpenAI- │
│ （AI 代理） │ 8 种工具暴露 │ │ /v1/chat/ │ 兼容 │
└─────────────┘ │ + wrapper │ completions │ API │
└──────────────┘ └─────────────┘
```
---
## ⚡ 一键设置：交给您的 AI 代理
将以下代码块复制并粘贴到任何 AI 代理中。它将自动设置所有内容。
```
您有权访问我的服务器。我想将我的 AI 代理连接到 Claude 代码。
1. 克隆此仓库：
git clone https://github.com/<您的用户名>/hermes-claude-code.git ~/.hermes-claude-code
2. 运行安装程序：
cd ~/.hermes-claude-code && bash setup/install.sh
3. 使用 API 详细信息创建 .env：
cat > ~/.hermes-claude-code/.env << 'EOF'
CC_BASE_URL=http://localhost:20126/v1
CC_API_KEY=sk-xxxxx
CC_MODEL_OPUS=opus-level
CC_MODEL_SONNET=sonnet-level
CC_MODEL_HAIKU=haiku-level
EOF
4. 加载它并重启 Hermes：
source ~/.hermes-claude-code/.env
hermes gateway restart
5. 验证：
hermes mcp list # 应该显示 'claude-code' 及工具
claude-code-run.sh -m haiku -w /tmp "print('hello from CC')"
6. 从您的代理使用 - 8 种 MCP 工具已准备就绪：
cc_haiku(task, workdir) # 快速修复，拼写错误，一行代码
cc_sonnet(task, workdir) # 功能， refactoring，PR 审查
cc_opus(task, workdir) # 架构，深度调试，复杂推理
cc_image(task, image_path) # OCR，收据提取
cc_continue(task, workdir) # 恢复上一会话
cc_save_session(...) # 持久化结果
cc_daemon_dispatch(...) # 发起并忘记长时间任务
cc_daemon_check(task_id) # 检查守护进程状态
完成。您现在正在与可以委托编码给 Claude 代码的代理进行交互。
```
就是这样。您的代理将处理其余部分。
---
## 功能
- **提供商无关** - 设置两个环境变量（`CC_BASE_URL` + `CC_API_KEY`），它适用于任何与 OpenAI 兼容的后端。
- **3 种成本层级** - `haiku` 用于廉价的快速修复，`sonnet` 用于日常工作，`opus` 用于复杂问题。
- **同步 + 异步** - MCP 工具阻塞，超时为 24 小时；守护进程调度是即发即忘的。
- **自动项目初始化** - 如果缺少 `git init` + CLAUDE.md 及 Karpathy 风格的指南。
- **管道输入** - `git diff | claude-code-run.sh "review this"`。
- **tmux REPL** - 交互式多轮 Claude 代码会话。
- **零个人数据** - 所有路径使用 `Path.home()` 或环境变量。
## 先决条件
- [Claude 代码 CLI](https://docs.anthropic.com/en/docs/claude-code/overview) (`npm install -g @anthropic-ai/claude-code`)
- 与 OpenAI 兼容的 API 端点（VansRouter，9Router，OpenRouter，LiteLLM，Anthropic，OpenAI...）
- Python 3.10+
- Hermes 代理（用于 MCP 集成）
## 手动设置
```bash
git clone https://github.com/<您的用户名>/hermes-claude-code.git ~/.hermes-claude-code
cd ~/.hermes-claude-code
bash setup/install.sh
# 使用您的 API 配置编辑 .env
nano .env
# 重启 Hermes
hermes gateway restart
```
或按照 [`docs/MANUAL_SETUP.md`](docs/MANUAL_SETUP.md) 进行逐步手动设置。
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `CC_BASE_URL` | 是 | `http://localhost:20126/v1` | 与 OpenAI 兼容的 API 端点 |
| `CC_API_KEY` | 是* | — | API 密钥 |
| `CC_DB_PATH` | 替代* | — | 包含 API 密钥的 SQLite DB（VansRouter/9Router） |
| `CC_DB_KEY_NAME` | 否 | `Claude 代码` | SQLite 中的 API 密钥名称 |
| `CC_MODEL_OPUS` | 否 | `opus-level` | opus 层级的模型名称 |
| `CC_MODEL_SONNET` | 否 | `sonnet-level` | sonnet 层级的模型名称 |
| `CC_MODEL_HAIKU` | 否 | `haiku-level` | haiku 层级的模型名称 |
| `CC_MODEL_DELEGATE` | 否 | `delegate` | 守护进程委托的模型名称 |
| `CC_MODEL_HIGH_THINK` | 否 | `high-think` | 高推理的模型名称 |
| `CC_MODEL_IMAGE` | 否 | `image` | 视觉/OCR 的模型名称 |
| `CC_SKIP_GIT_INIT` | 否 | — | 设置为 `1` 以跳过自动 git 初始化 |
*\*设置 `CC_API_KEY` 或 `CC_DB_PATH`。如果两者都没有，则包装器会报错。*
## 用法
### 从任何 AI 代理（MCP 工具）
工具 | 用途 | 最适合
-----|---------|---------
`cc_haiku` | 快速修复 | 拼写错误，一行代码，格式，简单脚本
`cc_sonnet` | 核心开发 | 功能，refactoring，测试，PR 审查
`cc_opus` | 重量级工作 | 架构，安全审计，深度调试
`cc_image` | 视觉/OCR | 收据文本，截图分析
`cc_continue` | 恢复 | 跟进上一 CC 会话
### 从终端
```bash
# 基本
./scripts/claude-code-run.sh -m sonnet -w /project "添加测试"
# 管道输入
git diff | ./scripts/claude-code-run.sh -m haiku -b 0.02 "审查更改"
# 流式输出
./scripts/claude-code-run.sh -m sonnet -s -w /project "调试此代码"
# 交互式 tmux REPL
./scripts/claude-code-run.sh -T -w /project "实现功能"
# 恢复上一会话
./scripts/claude-code-run.sh -c -w /project "跟进 PR"
```
### 守护进程（后台任务）
```bash
# 分派重量级任务（立即返回）
python3 scripts/cc-daemon-manager.py dispatch "重构身份验证" /project opus
# 稍后检查状态
python3 scripts/cc-daemon-manager.py check <task_id>
# 列出所有任务
python3 scripts/cc-daemon-manager.py list
```
## 后端示例
| 后端 | `CC_BASE_URL` |
|---------|---------------|
| VansRouter（本地） | `http://localhost:20126/v1` |
| 9Router（本地） | `http://localhost:20127/v1` |
| OpenRouter | `https://openrouter.ai/api/v1` |
| LiteLLM | `http://localhost:4000/v1` |
| Anthropic 直接 | `https://api.anthropic.com/v1` |
| OpenAI 直接 | `https://api.openai.com/v1` |
## 工作原理
1. 您的 AI 代理调用 MCP 工具（例如 `cc_sonnet`）
2. **cc-mcp-server.py** 接收它并委托给 `claude-code-run.sh`
3. **claude-code-run.sh** 解析 API 密钥，设置 `OPENAI_BASE_URL`，启动 `claude` CLI
4. **Claude 代码** 通过您配置的 API 运行任务
5. 结果通过链条流回
## 文件结构
```
hermes-claude-code/
├── README.md # 此文件 + AI 提示模板
├── LICENSE # MIT
├── .gitignore
├── scripts/
│ ├── claude-code-run.sh # 主要 CLI 包装器（提供商无关）
│ ├── cc-mcp-server.py # MCP stdio 服务器，用于 Hermes
│ ├── cc-daemon-manager.py # 后台任务调度器
│ └── cc-daemon-start.sh # 守护进程启动器模板
├── setup/
│ └── install.sh # 一键安装程序
└── docs/
├── MODEL_TIERS.md # 模型层级参考
├── TROUBLESHOOTING.md # 常见问题和修复
└── MANUAL_SETUP.md # 逐步手动设置
```
## 许可证
MIT
