# codebase-memory-mcp 实战：给 Hermes 装上一个代码大脑

## 最痛的一个问题

先问一个问题：你让 AI 帮你改代码的时候，最烦什么？

对我来说，最烦的是它每次都像第一次见这个项目一样，需要重新理解代码结构。

我来描述一下这个场景：

我："把这个 Service 里查询用户的方法改一下，用 LambdaQueryWrapper 替换原来的写法。"

然后它开始读文件。先读 Service 接口，再读 ServiceImpl 实现，再读 Entity，再读 Mapper……一通操作下来，几千 Token 已经没了。好不容易读完了，它说"好的我理解了"，然后改完交差。

下一轮对话，我又让它改另一个方法。好嘛，它又把刚才读过的文件重新读一遍。

一次两次还行，一天几十次交互，光翻文件就翻掉大几万 Token。每个月 Token 账单里至少有一半是花在"AI 反复读已经读过的代码"上。

这就好比你每天去一家餐厅吃饭，每次都要跟厨师介绍一遍"我喜欢吃辣的、不要香菜、米饭少一点"。第一天厨师记住了，但第二天你又得重新说一遍。搁谁谁受得了？



## 为什么 AI 记不住代码

根本原因在于：**Hermes 的会话记忆是面向自然语言对话的，不是面向代码的。**

它记得住你上一句说了什么，但记不住"这个 Controller 的路径是什么"、"这个 Service 依赖了哪些类"、"这个接口有多少个实现"。每次都要重新去文件系统里查，每次都要重新 parse，每次都要重新理解。

那有没有办法让 AI 一次性把代码结构记下来，以后直接查呢？

有的，这就是 codebase-memory-mcp 干的事。

## codebase-memory-mcp 到底是什么

codebase-memory-mcp（全称很绕口，后面简称 CBM）是一个基于 MCP 协议的代码知识图谱服务器。GitHub 地址：https://github.com/DeusData/codebase-memory-mcp

它的工作流程是这样的：

1. 扫描你的项目目录
2. 用 tree-sitter 解析每一行代码（支持158种编程语言）
3. 把函数、类、接口、变量、路由、调用关系全部提取出来
4. 构建成一个持久化的知识图谱
5. 通过 MCP 协议暴露 14 个查询工具给 AI 使用

之后 AI 想问任何关于代码的问题，直接查知识图谱就行，不用再碰文件系统。

## 性能有多猛

来看看数据：

|指标|数据|
|--|:--:|
|解析语言数|158种|
|索引速度|Linux 内核（2800万行）3分钟|
|查询速度|亚毫秒级（<1ms）|
|Token节省|官方说 99%，实测 90%+|
|存储格式|LZ4 压缩 SQLite|
|依赖|零，单文件二进制|

我自己的 nsw-project 项目有 6 个后端服务 + 2 个前端，总共 31 万多个代码节点、213 万条调用关系，索引起来也就几秒的事。

对比一下以前的方式：

**传统方式（查文件）：**
AI 要理解 `getStatsCards` 这个方法干了啥 → 找到文件 → 打开 → 读 100 行 → 分析 → 得出结论。消耗 Token：3000+，时间：3-5 秒。

**CBM 方式（查图）：**
AI 查知识图谱 → 直接拿到方法的定义、调用者、被调用者、行号范围 → 需要详细代码再读具体行。消耗 Token：300以下，时间：<1 秒。

差距接近 10 倍。

## 14 个工具一览

装好之后，AI 手上多了 14 个工具，覆盖了代码查询的方方面面：

|工具|功能|
|--|--|
|search_graph|搜索代码图谱（函数名、类名、关键词）|
|get_code_snippet|获取某个函数或类的源代码|
|get_architecture|获取项目架构总览（模块、依赖、路由）|
|trace_path|追踪调用链（谁调了我、我调了谁）|
|search_code|结合正则搜索和知识图谱的增强搜索|
|query_graph|用 Cypher 语法查询图谱|
|index_repository|索引一个项目|
|index_status|查看索引状态|
|list_projects|列出所有已索引的项目|
|delete_project|删除索引|
|detect_changes|检测代码变更和影响范围|
|manage_adr|管理架构决策记录|
|ingest_traces|导入运行时追踪数据|
|get_graph_schema|获取图谱的结构|

其中最常用的是 `search_graph`、`trace_path` 和 `get_code_snippet`，这三个基本覆盖了日常开发 90% 的代码查询需求。

## 安装过程

CBM 的安装不算复杂，但比 RTK 多几个步骤。

### 方案一：一键安装

```sh
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
```

如果网络状况不好，这个方案可能会超时。我推荐方案二。

### 方案二：手动下载（推荐）

先去 GitHub Releases 看看最新版本：https://github.com/DeusData/codebase-memory-mcp/releases

找到 `codebase-memory-mcp-darwin-arm64.tar.gz`（Mac ARM 芯片）或对应的平台版本下载。

```sh
# 解压
tar xzf codebase-memory-mcp-darwin-arm64.tar.gz

# 复制到 PATH 里
cp codebase-memory-mcp ~/.local/bin/

# 加执行权限
chmod +x ~/.local/bin/codebase-memory-mcp
```

### 第三步：配置到 Hermes

```sh
hermes mcp add codebase-memory --command ~/.local/bin/codebase-memory-mcp
```

会检测到 14 个工具，选 Y 全部启用。

### 第四步：重启 Hermes

执行 `/reset`

### 第五步：索引项目

跟 AI 说：**"帮我索引一下这个项目"**，它就会自动扫描当前目录的代码。

也可以手动指定项目路径，在 MCP 工具里调用 `index_repository`。

## 安装 UI 可视化版

CBM 还有一个带 UI 的版本，可以在浏览器里看 3D 知识图谱。如果标准版用着觉得不够直观，可以装 UI 版：

```sh
# 下载 UI 版
curl -fSL -o /tmp/cbm-ui.tar.gz \
  "https://github.com/DeusData/codebase-memory-mcp/releases/download/v0.9.0/codebase-memory-mcp-ui-darwin-arm64.tar.gz"

# 解压安装
cd /tmp && tar xzf cbm-ui.tar.gz
cp codebase-memory-mcp ~/.local/bin/codebase-memory-mcp-ui
chmod +x ~/.local/bin/codebase-memory-mcp-ui

# 启动 UI 服务
~/.local/bin/codebase-memory-mcp-ui --ui=true --port=9749
```

浏览器打开 `http://localhost:9749`，就能看到项目的 3D 知识图谱了。函数调用关系、模块依赖、热点代码一目了然，比自己翻代码直观多了。

## 实际使用体验

说几个让我觉得"这玩意儿真值"的场景。

**场景一：改代码前先看影响范围**

我之前改了一个工具类的公共方法，改完之后总觉得心里没底，怕影响别的模块。以前的做法是全局搜索这个方法名，然后一个个打开调用的地方看。

有了 CBM 之后，我直接让 AI 查调用链，不到一秒就返回了所有调用者的列表和文件位置。确认没有影响之后才放心改了。

**场景二：找 API 路由**

新同事想看看项目里有哪些 API 接口，以前我得让他去翻 Controller 代码。现在直接问 CBM，它返回了 998 条路由的完整列表，GET/POST/PUT/DELETE 一目了然。

**场景三：理解老代码**

项目里有些老代码是几年前的人写的，逻辑比较绕。以前要读半天才能搞清楚它在干嘛。

现在直接查知识图谱，函数的调用关系、数据流向、依赖的服务，一张图就看明白了。大大降低了理解老代码的心智负担。

## 技术原理浅析

CBM 的底层用的是 tree-sitter 来做代码解析。tree-sitter 是一个增量解析库，跟传统编译器的区别是：它不会把代码编译成抽象语法树然后扔掉，而是维护一个可以增量更新的语法树。

这样 CBM 就能做到：

1. **首次索引**：完整扫描所有文件，建立知识图谱
2. **增量更新**：你改了某个文件，它只需要重新解析这个文件，不用全量重扫
3. **跨文件关联**：通过函数名、类名、模块名建立跨文件的调用关系

图谱存储在 LZ4 压缩的 SQLite 数据库里，索引完成后内存会自动释放，不占运行时资源。

## 注意事项

1. CBM 的二进制文件比较大（260MB 左右），但只占磁盘空间，不占内存
2. 首次索引需要一点时间，后续只用增量更新，速度很快
3. 所有代码数据存在本地，不会上传任何第三方
4. 如果项目文件变更有自动 watcher 可以检测变化
5. CBM 支持 43 种 AI 客户端，不止 Hermes，Claude Code、Codex 都能用

## 总结

CBM 是我最近装的最值得的 MCP 工具。它解决了一个很本质的问题：AI 不应该反复做已经做过的工作。

代码结构这种东西，索引一次就够了。以后每次查询都从图谱里拿结果，又快又省 Token。

对于项目规模比较大的兄弟（尤其是微服务架构、多模块项目），这个工具的性价比极高。装一次，每次对话都在省 Token。

codebase-memory-mcp 实战：给 Hermes 装上一个代码大脑

# RTK 使用指南：如何把 Hermes 的 Token 消耗砍掉八成

## 起因：月初看了一眼账单

上个月月初，我习惯性地查了一下 API 账单，一看数字差点没把早饭喷出来——光 Token 费用就干了大几百。

我寻思我也没干啥啊，不就是每天跟 Hermes 聊聊天、改改代码、跑跑测试吗？怎么 Token 就跑得跟流水一样？

后来仔细琢磨了一下，发现问题出在终端输出上。



## Token 到底花在哪了

我跟 Hermes 的交互模式大概是这样的：

我让它改个代码 → 它执行 `mvn compile` 看编译结果 → 编译输出刷刷刷几百行 → 这几百行全算 Token → 它看完之后再回我一句话 → 这句话也算 Token。

一来一回，一个编译命令就能烧掉两三千 Token。一天下来几十次终端操作，Token 就这么悄无声息地流走了。

更坑的是，很多时候 AI 根本不需要看完整的编译输出来判断"编译是否成功"。它只需要知道"BUILD SUCCESS"还是"BUILD FAILED"就够了。但工具不管这些，原封不动把几百行输出全塞给 AI。

这就像你去饭店点菜，服务员把整个厨房的菜单、食材清单、厨师排班表全给你端上来了，就为了让你说一句"我要一份鱼香肉丝"。浪费，太浪费了。

## RTK 是什么

RTK 全称 Rust Token Killer，是一个用 Rust 写的开源工具，GitHub 地址是 https://github.com/rtk-ai/rtk。

它的核心功能就一个：**在终端输出到达 AI 之前，先把输出压缩一遍。**

怎么压缩呢？不是简单粗暴地砍掉一半字符，而是智能识别输出类型，用最精简的方式呈现同样的信息。

比如 `ls -la` 的输出，原本是：

```
-rw-r--r--  1 weizhenwang  staff   776 Jul 22 03:01 AbnormalService.java
-rw-r--r--  1 weizhenwang  staff   878 Jul 22 03:01 AdsInfoService.java
```

RTK 压缩后变成：

```
644  AbnormalService.java  776B
644  AdsInfoService.java  878B
```

owner、group、日期这些信息在绝大多数场景下 AI 根本用不着，砍掉完全不影响理解。文件权限（644）保留是因为有时候排查问题确实需要看权限。

类似地，git diff 的输出会被压缩成只有变更行摘要；编译日志会被去掉时间戳和重复的 warning；docker ps 的输出会被精简到只剩关键字段。

## 实测效果

我用了一个星期后统计了一下数据：

|场景|压缩前|压缩后|节省比例|
|--|:--:|:--:|:--:|
|ls -la 大目录|~500 tokens|~80 tokens|84%|
|git status|~300 tokens|~50 tokens|83%|
|mvn compile 完整输出|~3500 tokens|~400 tokens|89%|
|docker ps -a|~400 tokens|~60 tokens|85%|
|PostgreSQL 查询结果（20行）|~2000 tokens|~300 tokens|85%|
|git diff|~1500 tokens|~200 tokens|87%|

日均 Token 消耗直接从50万降到了10万左右。换算成人民币，每个月省下来的钱够吃好几顿火锅了。

## 安装配置

RTK 的安装简单到离谱，就两条命令。

### 安装

Mac用户：

```sh
brew install rtk
```

Linux用户可以去 GitHub Releases 下载对应的二进制。

### 配置到 Hermes

```sh
rtk init --agent hermes
```

这条命令会在 `~/.hermes/plugins/rtk-rewrite/` 下创建一个插件，以后所有终端命令都会先经过 RTK 再返回给 AI。

### 重启生效

```sh
/reset
```

## 怎么验证它在工作

重启后随便执行一个长输出的命令，看输出格式就知道了。

正常 `ps aux` 的输出长这样：

```
USER               PID  %CPU %MEM      VSZ    RSS   TT  STAT STARTED      TIME COMMAND
weizhenwang      44053  34.9  2.7 1890953888 457824   ??  S     3:03AM   0:37.98 /Users/weizhenwang/...
```

RTK 压缩后的输出长这样：

```
weizhenwang      44053  34.9  2.7  ??  S     3:03AM  /Users/weizhenwang/...
```

看到区别了吗？VSZ、RSS、TIME 这些不太常用的列被去掉了，但 PID、CPU、MEM、COMMAND 这些关键信息都保留了。

如果哪天你觉得某个命令的输出被压缩得太厉害，可以在命令前面加环境变量跳过 RTK：

```sh
RTK_OFF=1 你的命令
```

## 深度使用技巧

### 配合 codebase-memory-mcp 效果翻倍

RTK 压缩的是终端输出，codebase-memory-mcp 压缩的是代码查询。两个一起用，Token 消耗能降到原来的十分之一以下。

### 不同场景的压缩策略

RTK 对不同类型的输出有不同的压缩策略：

- 文件列表类：保留权限、大小、文件名，去掉时间、owner
- Git 类：保留变更摘要，去掉上下文
- 编译类：保留错误和警告摘要，去掉成功行
- 日志类：保留关键信息，去掉时间戳和重复行
- 进程列表类：保留 PID、CPU、内存、命令，去掉次要列

### 如果输出乱码了怎么办

极少数情况下 RTK 的压缩可能会导致输出格式异常。这时候可以：

1. 用 `RTK_OFF=1` 临时跳过
2. 去 GitHub 给 RTK 提 issue，作者回复挺快的

## RTK 和传统压缩方案的区别

之前也有人用脚本压缩终端输出，但基本都是简单的行数截断或者关键词过滤。RTK 不一样：

1. **智能识别输出类型** — 它能识别出这是 `ls`、`git`、`docker` 还是 `ps` 的输出，针对不同类型用不同的压缩策略
2. **保持信息完整性** — 该留的信息一个不少，不该留的果断砍掉
3. **零配置零维护** — 装上就能用，不用写规则不用调参数
4. **Rust 写的** — 速度快，内存占用低，不用担心影响 Hermes 性能

## 关于 Token 费用的一点碎碎念

现在 AI 模型的 API 价格虽然一直在降，但对于重度用户来说，Token 费用依然是一笔不容忽视的开支。



我之前看到一个群友的做法很有意思——他把每个月 Token 省下来的钱单独记一笔账，年底一看，省出来的钱够买一台新 MacBook 了。

我虽然没有他那么夸张，但 RTK 省下来的钱确实让我每个月少了一笔"看起来不多但加起来挺吓人"的开支。

## 总结

- RTK 是给 Hermes 省 Token 的神器
- 安装只要两行命令，零配置
- 实测能省 60-90% 的终端输出 Token
- 配合其他优化手段效果更佳
- Rust 写的，稳定高效

搞 AI 写代码的兄弟，这玩意儿建议人手一个。省下来的都是真金白银。

RTK 使用指南：如何把 Hermes 的 Token 消耗砍掉八成

# 给 Hermes 装上搜索引擎：Tavily 完整配置指南

## 从一次尴尬的对话说起

事情是这样的。上个月我在搞 nsw-project 那个股票分析平台，需要查一下2026年一季报A股半导体行业的营收数据。我跟 Hermes 说："帮我查查最近半导体板块的业绩情况。"

然后它沉默了。过了一会儿回了一句："抱歉，我无法访问互联网，建议你手动搜索。"



淦。

那一刻我意识到，Hermes 默认就是个离线大脑——它聪明，但它不联网。你跟它聊编程、聊算法、聊你项目里的代码逻辑，它都能侃侃而谈。但你要它查个新闻、搜个财报、看看最新的行业动态，它就抓瞎了。

当时我就想，这不行啊。我搞股票分析的，每天不看新闻、不查数据，那还玩个毛线？

于是开始折腾怎么让 Hermes 能上网查东西。

## 第一回合：浏览器工具

一开始我发现 Hermes 自带一个浏览器工具，可以打开网页。心想这不就结了嘛，让它开浏览器去百度搜不就完了？

太年轻了。

实际用起来是这样的：我说"帮我查查今天的A股热点"，它就开始启动浏览器，等页面加载，等渲染，等出现搜索结果……这一套下来少说十几秒，多则半分钟。而且百度谷歌这种网站对机器人不太友好，经常弹出验证码，然后就卡住了。

更坑的是，每次搜索都要重复这个流程，没有缓存，没有会话保持，效率低到令人发指。

## 什么是 Tavily

后来在一个 Hermes 交流群里有个老哥提到了 Tavily。我去了解了一下，发现这玩意儿简直就是给 AI 量身定做的搜索引擎。

Tavily（https://app.tavily.com）是一家专门做 AI Agent 搜索服务的公司。他们的 API 和传统的搜索引擎最大的区别在于：

**传统搜索引擎（百度/谷歌）是给人看的。**
你搜一个关键词，它返回10个蓝色链接，每个链接有一段摘要。人看了能理解，但 AI 看了就头疼——它得一个个打开链接去读内容，费时费钱。

**Tavily 是给 AI 吃的。**
你给它一个查询，它直接返回整理好的结构化数据——标题、内容摘要、来源URL、相关图片，一步到位。AI 拿到手就能用，不用再折腾。

而且它支持中文搜索，搜出来的结果都是新浪财经、新华网、东方财富、知乎这些国内源，不是那种机翻的外文内容。这对我们搞A股的来说简直是刚需。

## Tavily 凭什么比浏览器搜索强

我实际用了一个月，列一下 Tavily 和浏览器搜索的差距：

|对比项|浏览器搜索|Tavily|
|--|--|--|
|速度|15-30秒|1-3秒|
|Token消耗|加载整个页面，动不动几千Token|只返回摘要，几百Token搞定|
|稳定性|容易被反爬、验证码拦截|API调用，稳定得一匹|
|并发|一次只能搜一个|可以批量查多个关键词|
|中文支持|看网站心情|专门优化过中文内容|
|免费额度|无|1000次/月|

这差距，说一个是自行车一个是高铁不过分吧。

## 搜索质量实测

光说不练假把式，上点实际搜索结果。

我让配置好 Tavily 的 Hermes 搜"2026年A股一季报情况"，它直接返回了新浪财经的实时报道，里面有详细数据：

- A股5503家公司披露了一季报
- 营收总和17.68万亿，同比增长4.66%
- 净利润1.59万亿，同比增长6.59%
- 半导体、有色金属、硬件设备营收增速居前

这些数据都是实时从新浪财经抓的，不是 AI 瞎编的。做股票分析的都懂，这种实时数据的准确性有多重要。

然后又试了搜新华网的报道，也能正常返回，内容质量很高。

## 配置过程

说了这么多，该上干货了。配置 Tavily 其实就四步，三五分钟搞定。

### 第一步：注册账号拿 Key

打开 https://app.tavily.com ，注册一个账号。进后台 Dashboard 就能看到你的 API Key，一串以 `tvly-` 开头的字符串。复制下来。

免费版每个月有1000次搜索额度，个人日常使用完全够用。如果不够可以升级付费版，也不贵。

### 第二步：配置环境变量

把 API Key 加到 Hermes 的环境变量里：

```sh
echo 'TAVILY_API_KEY=tvly-你的key' >> ~/.hermes/.env
```

### 第三步：设置搜索引擎后端

告诉 Hermes 用 Tavily 而不是默认的浏览器搜索：

```sh
hermes config set web.backend tavily
```

### 第四步：确保工具集已启用

确认 `web` 工具集是开的：

```sh
hermes config set toolsets '["hermes-cli", "computer_use", "web"]'
```

### 第五步：重启生效

执行 `/reset` 或者关掉 Hermes 重开。

## 验证配置成功

重启后直接问一个需要联网的问题：

> "2026年A股一季报营收增长最快的行业是哪些？"

如果它给你返回了具体的行业数据和增速（比如半导体30.89%、有色金属30.73%这些），就说明 Tavily 生效了。如果它说"我无法联网"，那就是哪步没配对。

## 实际使用体验

配置好 Tavily 之后，我现在跟 Hermes 的交互方式完全变了。

以前查资料：我手动搜索 → 看结果 → 总结 → 告诉 Hermes 让它分析。
现在查资料：直接问 Hermes → 它自己搜 → 它自己分析 → 给我答案。

比如写股票分析报告的时候，我直接说：

"帮我查一下最近锂电板块的新闻，结合一季报数据分析一下行业趋势。"

它会自己先去搜锂电相关的新闻，再结合数据库里的财报数据，综合给你出一份分析。全程不用我动手，体验比之前好了不知道多少倍。

## 写在最后

给 AI 装上搜索引擎，就像给盲人装上了眼睛。之前 Hermes 只能处理你喂给它的信息，现在它能自己去抓信息了。

对搞股票、做分析、追热点的兄弟来说，这个配置属于"不装亏了"的级别。1000次免费查询说实话挺够用的，我天天查各种股票数据，一个月也没用完。

还没搞的兄弟建议花五分钟搞一下，体验提升巨大。搞完了你会发现，以前那个一问三不知的 Hermes，突然就变成百事通了。

给 Hermes 装上搜索引擎：Tavily 完整配置指南

# Hermes Agent 接入个人微信（WeChat）完整指南

## 前言

Hermes Agent 是一个开源 AI 代理框架，支持通过网关（Gateway）接入 20+ 消息平台，包括个人微信。本文将详细介绍从零开始将 Hermes 连接到你的微信账号的全流程，亲测可用。

> 本文基于 Hermes Agent 官方 v2.x 版本编写。官方文档：https://hermes-agent.nousresearch.com/docs



---

## 一、前置条件

在开始前，请确保满足以下条件：

|条件|说明|
|--|--|
|一个个人微信账号|用于扫码登录|
|Hermes Agent 已安装|确保 `hermes` 命令可用|
|Python 依赖|`aiohttp`、`cryptography`、`qrcode`|

检查并安装依赖：

```sh
pip install aiohttp cryptography qrcode
```

---

## 二、配置步骤

### 2.1 运行配置向导

Hermes 提供了交互式配置向导，一键完成微信接入：

```sh
hermes gateway setup
```

在菜单中选择 **Weixin / WeChat**（找到对应序号输入）。

向导会自动完成以下步骤：

1. 向腾讯 iLink Bot API 请求二维码
2. 在终端显示二维码（并提供 URL 备用）
3. 等待你用手机微信扫码
4. 提示在手机上确认登录
5. 自动保存账号凭据

扫码确认后，你会看到类似输出：

```
微信连接成功，account_id=xxxxxx@im.bot
```

> **什么是 iLink Bot？** 微信适配器使用的是腾讯官方的 **iLink Bot API**，扫码后创建一个 bot 身份。这个身份以 `@im.bot` 结尾，**不是**你的个人微信号本身。

### 2.2 验证凭据

登录成功后，凭据会自动保存在以下位置：

```sh
ls ~/.hermes/weixin/accounts/
# 输出示例: c21e7890e3ae@im.bot.json
```

查看凭据内容：

```json
{
  "token": "...",
  "base_url": "https://ilinkai.weixin.qq.com",
  "user_id": "...@im.wechat",
  "saved_at": "2026-07-18T05:58:27Z"
}
```

同时 `~/.hermes/.env` 中会自动写入环境变量：

```sh
WEIXIN_ACCOUNT_ID=c21e7890e3ae@im.bot
WEIXIN_TOKEN=...
WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
```

---

## 三、启动网关

### 3.1 启动

确保微信配置就绪后，启动 Hermes 网关：

```sh
hermes gateway run
```

网关启动后会自动长轮询微信消息。正常情况下日志会显示：

```
[gateway] ready
[Weixin] Connected
```

### 3.2 验活

用手机微信给 bot 发一条消息。如果配置正确，Hermes 会收到消息并回复。

首次消息会触发**配对流程**——Hermes 会返回一个配对码，需要在终端批准：

```sh
hermes pairing approve weixin <PAIRING_CODE>
```

批准后，你的微信账号就与 Hermes 绑定了，后续消息自动响应。

---

## 四、额外配置

### 4.1 设置 Home Channel

Home Channel 是 Hermes 发送定时任务结果、跨平台消息的默认聊天窗口。在微信中回复：

```
/sethome
```

或直接在 `.env` 中配置：

```sh
WEIXIN_HOME_CHANNEL=your_user_id@im.wechat
WEIXIN_HOME_CHANNEL_NAME=Home
```

### 4.2 访问策略

你可以控制谁可以向 bot 发消息：

```sh
# 只允许指定用户
WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2
```

|策略|说明|
|--|--|
|`open`|任何人可发私信（默认）|
|`allowlist`|仅白名单用户|
|`disabled`|关闭私信|
|`pairing`|配对模式|

---

## 五、功能特性

### 支持的功能

|功能|说明|
|--|--|
|私信聊天|✅ 支持|
|群聊|⚠️ 有限制（见下方）|
|图片消息|✅ 支持收发|
|视频消息|✅ 支持收发|
|文件消息|✅ 支持收发|
|语音消息|✅ 支持（有文字转录则提取）|
|Markdown 回复|✅ 自动格式化|
|输入状态提示|✅ 显示"正在输入…"|

### 架构特点

- **长轮询传输**：无需公网 IP 或 webhook
- **AES-128-ECB 加密 CDN**：所有媒体传输自动加解密
- **消息去重**：5 分钟滑动窗口
- **自动重试与退避**：从瞬时错误恢复

---

## 六、注意事项与限制

### ⚠️ iLink Bot 身份限制

扫码登录后连接的是 **iLink bot 身份**（`xxx@im.bot`），而非你的个人微信号。这意味着：

1. **不能加入普通微信群**：bot 身份无法像普通联系人一样被邀请进群
2. **群消息基本不可用**：iLink 通常不向 bot 推送群事件
3. **@ 提及自己 vs @ 提及 bot**：在群里 @ 你自己的微信号 ≠ @ bot
4. **私信（DM）是主要使用方式**：私信功能完全正常

### 其他限制

- 需要电脑保持 Hermes gateway 运行
- 依赖 iLink API 的可用性
- 媒体文件有大小限制（受 CDN 限制）

---

## 七、常见问题

### Q: 扫码后提示"已过期"怎么办？

重新运行 `hermes gateway setup` 重新扫码。

### Q: 收不到微信消息？

确保 gateway 正在运行，检查日志：

```sh
grep weixin ~/.hermes/logs/gateway.log | tail -20
```

### Q: 想要连接多个微信账号？

重复运行 `hermes gateway setup` 并选择 Weixin，或者查看官方文档的 multi-account 配置。

### Q: 和 OpenClaw 的微信方案有什么区别？

Hermes 使用的是腾讯官方的 iLink Bot API，而 OpenClaw 使用相同的底层协议但需额外安装插件。Hermes 原生内置支持，开箱即用。

---

## 八、总结

Hermes Agent 接入微信的整体流程非常简洁：

1. 装依赖 → 2. 运行 `hermes gateway setup` 扫码 → 3. 启动 gateway → 4. 配对批准 → 完成

整个过程只需几分钟，无需公网服务器、无需 webhook、无需额外插件。Hermes 的原生支持让微信集成变得轻松高效。

Hermes Agent 接入个人微信（WeChat）完整指南

# cpolar 内网穿透完全指南

> **cpolar** - 安全、稳定、快速的内网穿透工具  
> **版本**: 最新稳定版  
> **适用系统**: macOS / Linux / Windows / NAS  
> **文档更新日期**: 2026-04-13

---

## 1. cpolar 简介

### 1.1 什么是 cpolar？

cpolar 是一款强大的内网穿透工具，可以将本地服务器安全地暴露到公网，支持：
- **HTTP/HTTPS 隧道**：Web 服务穿透
- **TCP 隧道**：SSH、远程桌面、数据库等
- **FTP 隧道**：文件传输服务
- **WebSockets**：实时通信应用



### 1.2 核心特性

✅ **全球基础设施** - 多个数据中心，选择最佳节点  
✅ **安全可靠** - 支持 TLS 加密、IP 白名单、密码保护  
✅ **简单易用** - Web UI 和命令行双界面  
✅ **跨平台** - 支持 Windows、macOS、Linux、NAS  
✅ **免费套餐** - 提供基础的免费穿透服务  
✅ **自定义域名** - 支持绑定自己的域名  

### 1.3 应用场景

- 🌐 本地 Web 开发测试
- 💻 远程访问家中电脑
- 📱 移动端调试接口
- 🗄️ 数据库远程管理
- 🎮 游戏服务器搭建
- 📡 IoT 设备远程访问

---

## 2. 系统要求

### 2.1 macOS

- **系统版本**: macOS 10.14 (Mojave) 或更高
- **包管理器**: Homebrew
- **权限**: 管理员权限（sudo）

### 2.2 Linux

- **发行版**: Ubuntu 16.04+、CentOS 7+、Debian、树莓派等
- **初始化系统**: systemd
- **架构**: amd64、i386、arm、arm64、mips 等

### 2.3 Windows

- **系统版本**: Windows 7 或更高
- **权限**: 管理员权限

### 2.4 网络要求

- 稳定的互联网连接
- 防火墙允许出站连接

---

## 3. macOS 安装教程

### 3.1 安装 Homebrew（如果尚未安装）

**方法一：官方安装（推荐）**

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

安装完成后配置环境变量：

```bash
# Apple Silicon (M1/M2/M3)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Intel Mac
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"
```

**方法二：国内镜像安装（网络不佳时使用）**

```bash
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"
```

> 💡 **提示**: 执行后选择镜像，建议选择镜像 2（速度较快）

验证安装：

```bash
brew --version
```

### 3.2 安装 cpolar

```bash
# 添加 cpolar 源并安装
brew tap probezy/core && brew install cpolar
```

验证安装：

```bash
cpolar version
```

### 3.3 配置 Token

1. 登录 [cpolar 官网](https://dashboard.cpolar.com)
2. 点击左侧"验证"菜单
3. 复制你的认证 Token
4. 在终端执行：

```bash
cpolar authtoken xxxxxxx
```

将 `xxxxxxx` 替换为你的实际 Token。

### 3.4 安装系统服务

```bash
# 安装服务
sudo cpolar service install

# 启动服务
sudo cpolar service start

# 查看服务状态
sudo cpolar service status
```

### 3.5 访问 Web UI

在浏览器中打开：

```
http://127.0.0.1:9200
```

使用你的 cpolar 账号登录即可开始使用。

---

## 4. Linux 安装教程

### 4.1 一键安装脚本（推荐）

**国内用户：**

```bash
curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash
```

**国外用户：**

```bash
curl -sL https://git.io/cpolar | sudo bash
```

### 4.2 验证安装

```bash
cpolar version
```

### 4.3 配置 Token

```bash
cpolar authtoken xxxxxxx
```

### 4.4 简单穿透测试

```bash
cpolar http 8080
```

按 `Ctrl+C` 退出测试。

### 4.5 配置系统服务

```bash
# 设置开机自启
sudo systemctl enable cpolar

# 启动服务
sudo systemctl start cpolar

# 查看服务状态
sudo systemctl status cpolar
```

### 4.6 查看隧道状态

访问：https://dashboard.cpolar.com/status

### 4.7 安装说明

- **默认安装路径**: `/usr/local/bin/cpolar`
- **配置文件路径**: `/usr/local/etc/cpolar/cpolar.yml`
- 安装脚本会自动配置 systemd 服务，支持开机自启
- 首次安装会创建两个样例隧道（web 和 ssh）

---

## 5. Windows 安装教程

### 5.1 下载安装包

1. 访问 [cpolar 官网下载页](https://www.cpolar.com/download)
2. 下载 Windows 版本的 zip 压缩包
3. 解压得到安装程序

### 5.2 安装

双击安装包，一路默认安装即可。

### 5.3 配置 Token

打开命令提示符（CMD）或 PowerShell：

```bash
cpolar authtoken xxxxxxx
```

### 5.4 启动服务

cpolar 会自动安装为 Windows 服务并启动。

### 5.5 访问 Web UI

浏览器访问：

```
http://127.0.0.1:9200
```

---

## 6. 初始配置

### 6.1 注册 cpolar 账号

1. 访问 [cpolar 官网](https://www.cpolar.com)
2. 点击"注册"按钮
3. 填写邮箱和密码
4. 完成邮箱验证

### 6.2 获取 Authtoken

1. 登录 [cpolar 控制台](https://dashboard.cpolar.com)
2. 点击左侧"验证"菜单
3. 复制你的 Token

### 6.3 配置 Token

```bash
cpolar authtoken your-token-here
```

### 6.4 验证配置

```bash
# 查看配置信息
cpolar config

# 或查看配置文件
cat ~/.cpolar/cpolar.yml
```

---

## 7. Web UI 使用指南

### 7.1 登录 Web UI

```
http://127.0.0.1:9200
```

使用 cpolar 账号密码登录。

### 7.2 创建 HTTP 隧道

1. 点击左侧"隧道管理" → "创建隧道"
2. 填写配置：
   - **隧道名称**: 自定义名称
   - **协议**: HTTP
   - **本地地址**: `127.0.0.1:8080`（你的本地服务端口）
   - **域名类型**: 
     - 随机域名（免费）
     - 二级子域名（需配置）
     - 自定义域名（需绑定）
3. 点击"创建"
4. 启动隧道

### 7.3 创建 TCP 隧道

1. 点击"创建隧道"
2. 填写配置：
   - **协议**: TCP
   - **本地地址**: `127.0.0.1:22`（SSH）或 `127.0.0.1:3389`（远程桌面）
   - **端口类型**: 
     - 随机端口（免费）
     - 固定端口（需预留）
3. 点击"创建"并启动

### 7.4 创建 FTP 隧道

1. 点击"创建隧道"
2. 选择协议：FTP
3. 配置本地 FTP 服务地址
4. 启动隧道

### 7.5 配置二级子域名

1. 进入"隧道管理" → "预留"
2. 点击"二级子域名"
3. 输入你想要的子域名名称
4. 点击"预留"
5. 在隧道配置中使用该子域名

### 7.6 配置自定义域名

1. 进入"隧道管理" → "预留"
2. 点击"自定义域名"
3. 输入你的域名
4. 按照提示配置 DNS CNAME 记录：
   ```
   CNAME your-domain.com -> xxx.cpolar.cn
   ```
5. 等待 DNS 生效（通常 10 分钟内）
6. 在隧道中使用自定义域名

### 7.7 配置固定 TCP 端口

1. 进入"预留"页面
2. 点击"TCP 端口"
3. 预留你需要的端口
4. 在 TCP 隧道配置中使用该端口

---

## 8. 命令行使用指南

### 8.1 创建 HTTP 隧道

```bash
# 基本用法
cpolar http 8080

# 指定子域名
cpolar http -subdomain=myapp 8080

# 指定自定义域名
cpolar http -hostname=example.com 8080

# 启用 HTTPS
cpolar http -bind-tls=true 8080

# 同时支持 HTTP 和 HTTPS
cpolar http -bind-tls=both 8080
```

### 8.2 创建 TCP 隧道

```bash
# 基本用法（随机端口）
cpolar tcp 22

# 使用预留端口
cpolar tcp -remote-addr=12345 22

# 指定地区
cpolar tcp -region=cn_vip 22
```

### 8.3 创建 FTP 隧道

```bash
cpolar tcp 21
```

### 8.4 查看隧道状态

```bash
# 查看运行中的隧道
cpolar status

# 或在 Web UI 查看
# http://127.0.0.1:4040/status
```

### 8.5 使用配置文件启动

```bash
# 使用默认配置文件
cpolar start-all

# 启动特定隧道
cpolar start web
cpolar start ssh

# 指定配置文件路径
cpolar start-all --config=/path/to/cpolar.yml
```

### 8.6 帮助命令

```bash
# 查看所有命令
cpolar --help

# 查看子命令帮助
cpolar http --help
cpolar tcp --help
```

---

## 9. 隧道类型详解

### 9.1 HTTP 隧道

**适用场景**: Web 应用、API 服务、前端开发

```bash
# 示例：暴露本地 3000 端口的 Web 服务
cpolar http 3000

# 输出示例：
# Forwarding  http://abc123.cpolar.cn -> 127.0.0.1:3000
# Forwarding  https://abc123.cpolar.cn -> 127.0.0.1:3000
```

**特性**:
- ✅ 自动支持 HTTP 和 HTTPS
- ✅ 支持域名绑定
- ✅ 支持 Host 重写
- ✅ 支持 WebSockets

### 9.2 TCP 隧道

**适用场景**: SSH、远程桌面、数据库、游戏服务器

```bash
# SSH 远程访问
cpolar tcp 22

# MySQL 数据库
cpolar tcp 3306

# 远程桌面
cpolar tcp 3389

# Minecraft 服务器
cpolar tcp 25565
```

**输出示例**:
```
Forwarding  tcp://6.tcp.cpolar.top:12345 -> 127.0.0.1:22
```

连接方式：
```bash
# SSH 连接
ssh user@6.tcp.cpolar.top -p 12345

# MySQL 连接
mysql -h 6.tcp.cpolar.top -P 12345 -u root -p
```

### 9.3 FTP 隧道

**适用场景**: 文件传输服务

```bash
cpolar tcp 21
```

> 💡 **注意**: FTP 需要额外配置被动模式端口范围

---

## 10. 高级功能

### 10.1 TLS 隧道

#### 加密的 TLS 连接

```bash
cpolar tls 443
```

#### 通过 TLS 隧道运行非 HTTP 服务

```bash
cpolar tls -hostname=secure.example.com 8443
```

### 10.2 IP 白名单

限制只有特定 IP 可以访问你的隧道：

**Web UI 配置**:
1. 进入隧道配置
2. 找到"IP 白名单"选项
3. 添加允许的 IP 地址或范围：
   - 单个 IP: `192.168.1.100`
   - IP 段: `192.168.1.0/24`

### 10.3 密码保护

为隧道添加基本的 HTTP 认证：

```bash
cpolar http -auth="username:password" 8080
```

### 10.4 请求检查和重放

访问 Web UI 的检查界面：

```
http://127.0.0.1:4040
```

功能：
- 📊 查看所有请求
- 🔍 检查请求头、消息体
- 🔄 重放请求（用于调试）

### 10.5 泛域名支持

支持通配符域名：

```bash
cpolar http -hostname="*.example.com" 8080
```

### 10.6 WebSockets 支持

HTTP 隧道自动支持 WebSockets：

```bash
cpolar http 3000
# WebSocket 连接: ws://abc123.cpolar.cn/ws
```

### 10.7 出站代理

如果你的网络需要代理上网：

```bash
export HTTPS_PROXY=http://proxy-server:8080
cpolar http 8080
```

---

## 11. 配置文件详解

### 11.1 配置文件位置

| 系统 | 路径 |
|------|------|
| macOS | `~/.cpolar/cpolar.yml` |
| Linux | `/usr/local/etc/cpolar/cpolar.yml` |
| Windows | `C:\Users\用户名\.cpolar\cpolar.yml` |

### 11.2 配置选项说明

```yaml
# 认证令牌
authtoken: "your-token-here"

# 日志级别：debug、info、warn、error
log_level: info

# 日志文件路径
log: /var/log/cpolar.log

# Web UI 地址
web_addr: 127.0.0.1:9200

# 区域选择
region: cn_vip

# 隧道定义
tunnels:
  # Web 服务隧道
  web:
    proto: http
    addr: 8080
    subdomain: myapp
  
  # SSH 隧道
  ssh:
    proto: tcp
    addr: 22
    remote_addr: 12345
  
  # 数据库隧道
  mysql:
    proto: tcp
    addr: 3306
    remote_addr: 23456
    ip_whitelist:
      - 192.168.1.0/24
```

### 11.3 示例配置文件

```yaml
authtoken: "xxxxxxxxxxxxxxx"
region: cn_vip

tunnels:
  # 本地开发服务器
  dev:
    proto: http
    addr: 3000
    subdomain: mydev
  
  # SSH 远程访问
  ssh:
    proto: tcp
    addr: 22
    remote_addr: 10234
  
  # 远程桌面
  rdp:
    proto: tcp
    addr: 3389
    remote_addr: 20345
```

### 11.4 同时运行多个隧道

```bash
# 启动所有隧道
cpolar start-all

# 启动特定隧道
cpolar start web ssh

# 后台运行
nohup cpolar start-all &
```

---

## 12. 后台服务管理

### 12.1 macOS 服务管理

```bash
# 安装服务
sudo cpolar service install

# 启动服务
sudo cpolar service start

# 停止服务
sudo cpolar service stop

# 重启服务
sudo cpolar service restart

# 查看状态
sudo cpolar service status

# 卸载服务
sudo cpolar service uninstall
```

### 12.2 Linux 服务管理

```bash
# 开机自启
sudo systemctl enable cpolar

# 启动服务
sudo systemctl start cpolar

# 停止服务
sudo systemctl stop cpolar

# 重启服务
sudo systemctl restart cpolar

# 查看状态
sudo systemctl status cpolar

# 查看日志
sudo journalctl -u cpolar -f
```

### 12.3 Windows 服务管理

```bash
# 以服务方式启动
cpolar service start

# 停止服务
cpolar service stop
```

或在"服务"管理工具中管理 cpolar 服务。

---

## 13. 常见问题与故障排查

### 13.1 无法访问 cpolar Web UI

**问题**: 访问 `http://127.0.0.1:9200` 无法打开

**解决方案**:

```bash
# 1. 检查 cpolar 是否运行
ps aux | grep cpolar

# 2. 检查端口是否被占用
lsof -i :9200

# 3. 修改 Web UI 端口
# 编辑配置文件 ~/.cpolar/cpolar.yml
web_addr: 127.0.0.1:9201

# 4. 重启服务
sudo cpolar service restart
```

### 13.2 登录失败，用户不一致

**问题**: Web UI 登录提示用户不一致

**解决方案**:
1. 确保使用注册时的邮箱和密码
2. 检查是否区分大小写
3. 尝试在官网重置密码

### 13.3 修改 Web UI 默认端口

编辑配置文件：

```bash
nano ~/.cpolar/cpolar.yml
```

修改：
```yaml
web_addr: 127.0.0.1:9200  # 改为你想要的端口
```

重启服务：
```bash
sudo cpolar service restart
```

### 13.4 SSH TCP 连接不通

**常见问题**:

1. **端口未开放**: 检查是否使用预留端口
2. **防火墙拦截**: 检查本地防火墙设置
3. **SSH 服务未启动**: 
   ```bash
   # macOS
   sudo systemsetup -setremotelogin on
   
   # Linux
   sudo systemctl start sshd
   ```

4. **连接命令错误**:
   ```bash
   # 正确格式
   ssh user@服务器地址 -p 端口号
   ```

### 13.5 配置自定义域名报错

**检查清单**:

- [ ] 域名已正确添加 CNAME 记录
- [ ] DNS 已生效（可使用 `nslookup` 检查）
- [ ] 域名已在控制台预留
- [ ] 隧道配置中使用了正确的 hostname

```bash
# 检查 DNS
nslookup your-domain.com
```

### 13.6 隧道离线

**排查步骤**:

1. 检查网络连接
2. 验证 Token 是否正确
3. 查看日志：
   ```bash
   # Linux
   sudo journalctl -u cpolar -f
   
   # 查看日志文件
   tail -f /var/log/cpolar.log
   ```
4. 重启服务

### 13.7 远程桌面连接问题

#### Windows 10 家庭版设置

1. 启用远程桌面（需升级到专业版或使用第三方工具）
2. 设置用户名密码
3. 防火墙放行 3389 端口

#### 连接提示"凭证不工作"

**解决方案**:
1. 使用 Microsoft 账户登录
2. 或在本地账户设置密码
3. 使用 `用户名@计算机名` 格式

### 13.8 CORS 与 HTTP 基本身份验证

如果遇到 CORS 问题，在隧道配置中添加：

```yaml
tunnels:
  web:
    proto: http
    addr: 8080
    host_header: rewrite
    inspect: true
```

---

## 14. 完全卸载

### 14.1 macOS 卸载

```bash
# 1. 停止服务
sudo cpolar service stop

# 2. 卸载服务
sudo cpolar service uninstall

# 3. 删除 cpolar
brew uninstall cpolar
brew untap probezy/core

# 4. 删除配置文件
rm -rf ~/.cpolar

# 5. 删除日志（如果存在）
rm -rf ~/Library/Logs/cpolar
```

### 14.2 Linux 卸载

```bash
# 方法一：使用卸载脚本
curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash -s -- --remove

# 方法二：手动卸载
# 1. 停止服务
sudo systemctl stop cpolar
sudo systemctl disable cpolar

# 2. 删除服务文件
sudo rm /etc/systemd/system/cpolar.service
sudo systemctl daemon-reload

# 3. 删除程序
sudo rm /usr/local/bin/cpolar

# 4. 删除配置
sudo rm -rf /usr/local/etc/cpolar

# 5. 删除日志
sudo rm -rf /var/log/cpolar.log
```

### 14.3 Windows 卸载

1. 打开"控制面板" → "程序和功能"
2. 找到 cpolar
3. 点击"卸载"
4. 删除残留配置：
   ```
   C:\Users\用户名\.cpolar
   ```

### 14.4 验证卸载

```bash
# 确认命令不存在
which cpolar
# 应返回空

# 确认进程不存在
ps aux | grep cpolar
# 应只有 grep 进程
```

---

## 15. 最佳实践

### 15.1 安全建议

✅ **使用强密码** - 为重要服务添加认证  
✅ **配置 IP 白名单** - 限制访问来源  
✅ **使用 HTTPS** - 加密传输数据  
✅ **定期更新** - 保持 cpolar 最新版本  
✅ **监控日志** - 定期检查访问日志  

### 15.2 性能优化

```yaml
# 优化配置示例
log_level: warn  # 生产环境使用 warn 或 error
log: /dev/null   # 不需要日志时禁用
```

### 15.3 开发工作流

```bash
# 1. 启动本地开发服务器
npm run dev  # 或 python manage.py runserver

# 2. 在另一个终端启动 cpolar
cpolar http 3000

# 3. 将生成的 URL 分享给测试人员
# https://abc123.cpolar.cn

# 4. 在 4040 端口监控请求
# http://127.0.0.1:4040
```

### 15.4 生产环境部署

```bash
# 1. 使用配置文件
cpolar start-all --config=/etc/cpolar/production.yml

# 2. 设置为系统服务
sudo systemctl enable cpolar
sudo systemctl start cpolar

# 3. 监控服务状态
sudo systemctl status cpolar
```

### 15.5 常用命令速查

```bash
# 快速启动 HTTP 隧道
cpolar http 8080

# 快速启动 TCP 隧道
cpolar tcp 22

# 查看所有隧道
cpolar status

# 查看帮助
cpolar --help

# 更新配置
cpolar config

# 查看版本
cpolar version
```

---

## 📚 更多资源

- **官方网站**: https://www.cpolar.com
- **控制台**: https://dashboard.cpolar.com
- **完整文档**: https://www.cpolar.com/docs
- **下载页面**: https://www.cpolar.com/download
- **价格方案**: https://www.cpolar.com/pricing
- **技术支持**: support@cpolar.com

---

## 📝 文档维护

- **最后更新**: 2026-04-13
- **版本**: v1.0
- **反馈**: 如有问题，请访问官方文档或联系技术支持

---

**祝你使用愉快！** 🎉