# 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
- **反馈**: 如有问题，请访问官方文档或联系技术支持

---

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

cpolar 内网穿透完全指南

# Hermes Agent macOS 安装、配置与使用完全指南

> **Hermes Agent** - 由 Nous Research 开发的自我改进型 AI 智能体  
> **版本**: 最新稳定版  
> **适用系统**: macOS (支持 Apple Silicon 和 Intel)  
> **文档更新日期**: 2026-04-13

---

## 1. 系统要求

### 硬件要求
- **处理器**: Apple Silicon (M1/M2/M3) 或 Intel 处理器
- **内存**: 最低 4GB RAM，推荐 8GB+
- **存储**: 至少 2GB 可用磁盘空间
- **网络**: 稳定的互联网连接



### 软件要求
- **macOS**: 12.0 (Monterey) 或更高版本
- **Python**: 3.11 或更高版本
- **Homebrew**: 最新稳定版
- **终端**: Terminal.app、iTerm2 或 Warp

### 支持的模型提供商
- Nous Portal
- OpenRouter (200+ 模型)
- z.ai/GLM
- Kimi/Moonshot
- MiniMax
- OpenAI
- Anthropic
- 自定义 API 端点

---

## 2. 前置准备

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

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

安装完成后，根据提示将 Homebrew 添加到 PATH：

```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
brew --version
```

### 2.2 安装 Python 3.11+

```bash
# 使用 Homebrew 安装 Python
brew install python@3.11

# 验证安装
python3.11 --version

# 设置默认 Python 版本（可选）
brew link python@3.11
```

### 2.3 安装 uv（推荐的 Python 包管理器）

```bash
# 使用官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 重新加载 shell 配置
source ~/.zshrc

# 验证安装
uv --version
```

### 2.4 安装其他依赖（可选）

```bash
# Git（用于版本管理和更新）
brew install git

# wget（下载工具）
brew install wget

# tree（目录结构查看）
brew install tree
```

---

## 3. 安装步骤

### 方式一：一键安装脚本（推荐）

```bash
# 下载并执行安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

安装脚本会自动：
- 检测操作系统和架构
- 安装必要的系统依赖
- 创建虚拟环境
- 安装 Hermes Agent 及其依赖
- 配置环境变量

### 方式二：手动安装（适合高级用户）

```bash
# 1. 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 2. 创建虚拟环境
uv venv venv --python 3.11
source venv/bin/activate

# 3. 安装所有功能（包含语音等额外依赖）
uv pip install -e ".[all]"

# 4. 验证安装
python -m pytest tests/ -q
```

### 安装后配置

```bash
# 重新加载 shell 配置
source ~/.zshrc  # 或 source ~/.bashrc

# 验证安装
hermes --version

# 运行诊断工具
hermes doctor
```

---

## 4. 初始配置

### 4.1 运行设置向导

```bash
hermes setup
```

设置向导会引导你完成：
1. **选择 LLM 提供商**: OpenRouter、OpenAI、Anthropic 等
2. **配置 API Key**: 输入你的 API 密钥
3. **选择默认模型**: 设置默认使用的 AI 模型
4. **配置工具**: 选择启用哪些工具
5. **设置消息平台**（可选）: Telegram、Discord 等

### 4.2 手动配置 API Key

```bash
# 设置 OpenRouter API Key
hermes config set openrouter_api_key "your-api-key-here"

# 设置 OpenAI API Key
hermes config set openai_api_key "your-api-key-here"

# 设置 Anthropic API Key
hermes config set anthropic_api_key "your-api-key-here"
```

### 4.3 选择模型

```bash
# 交互式选择模型
hermes model

# 或直接指定模型
hermes model openrouter:anthropic/claude-3.5-sonnet
```

### 4.4 配置文件位置

Hermes 的配置文件位于：
```bash
~/.hermes/config.yaml        # 主配置文件
~/.hermes/tools/             # 工具配置
~/.hermes/skills/            # 技能文件
~/.hermes/memories/          # 记忆文件
```

查看配置：
```bash
cat ~/.hermes/config.yaml
```

---

## 5. 基本使用

### 5.1 启动交互模式

```bash
# 启动终端交互界面
hermes
```

### 5.2 常用命令

在交互模式下，可以使用以下斜杠命令：

| 命令 | 功能 | 示例 |
|------|------|------|
| `/new` 或 `/reset` | 开始新对话 | `/new` |
| `/model` | 切换模型 | `/model openrouter:gpt-4` |
| `/personality` | 设置人格 | `/personality assistant` |
| `/retry` | 重试最后一次响应 | `/retry` |
| `/undo` | 撤销最后一次交互 | `/undo` |
| `/compress` | 压缩上下文 | `/compress` |
| `/usage` | 查看使用统计 | `/usage` |
| `/skills` | 浏览可用技能 | `/skills` |
| `/tools` | 查看启用的工具 | `/tools` |
| `/help` | 查看帮助 | `/help` |

### 5.3 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `Ctrl+C` | 中断当前任务 |
| `Ctrl+D` | 退出 Hermes |
| `↑/↓` | 浏览命令历史 |
| `Tab` | 自动补全命令 |
| `Ctrl+R` | 搜索命令历史 |

### 5.4 查看帮助

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

# 查看子命令帮助
hermes model --help
hermes tools --help
hermes config --help
```

---

## 6. 高级功能

### 6.1 工具系统

Hermes 内置 40+ 工具，可以执行各种任务：

```bash
# 查看可用工具
hermes tools

# 启用/禁用特定工具
hermes tools enable shell
hermes tools disable web_search
```

#### 常用工具集

- **Shell**: 执行 shell 命令
- **Web Search**: 网络搜索
- **File System**: 文件操作
- **Python**: 执行 Python 代码
- **Browser**: 网页浏览
- **Git**: Git 操作

### 6.2 终端后端

支持多种终端后端：

```bash
# 本地执行（默认）
hermes config set terminal_backend local

# Docker 容器
hermes config set terminal_backend docker

# SSH 远程
hermes config set terminal_backend ssh
hermes config set ssh_host "user@remote-server"

# Daytona（无服务器）
hermes config set terminal_backend daytona
```

### 6.3 子代理（Subagents）

可以生成隔离的子代理进行并行工作：

```
# 在对话中使用
/spawn 帮我分析这个数据集并生成报告
```

### 6.4 上下文文件

项目上下文文件会影响每次对话：

```bash
# 创建项目上下文文件
echo "这是一个 Python 数据分析项目" > .hermes-context

# 上下文文件会自动加载到对话中
```

---

## 7. 多平台集成

### 7.1 消息网关

Hermes 可以同时作为多个消息平台的机器人：

```bash
# 启动网关设置向导
hermes gateway setup

# 启动网关
hermes gateway start
```

### 7.2 Telegram 集成

```bash
# 配置 Telegram
hermes gateway setup telegram

# 需要提供的信息：
# - Bot Token（从 @BotFather 获取）
# - 允许的用户 ID
```

**获取 Telegram Bot Token**:
1. 在 Telegram 中搜索 `@BotFather`
2. 发送 `/newbot` 命令
3. 按照提示创建机器人
4. 复制获得的 Token

### 7.3 Discord 集成

```bash
# 配置 Discord
hermes gateway setup discord

# 需要提供的信息：
# - Bot Token
# - 允许的服务器 ID
# - 允许的频道 ID
```

**获取 Discord Bot Token**:
1. 访问 [Discord Developer Portal](https://discord.com/developers/applications)
2. 创建新应用
3. 在 "Bot" 页面创建机器人并复制 Token
4. 启用必要的 Intents（Message Content Intent 等）

### 7.4 其他平台

```bash
# Slack
hermes gateway setup slack

# WhatsApp
hermes gateway setup whatsapp

# Signal
hermes gateway setup signal

# Email
hermes gateway setup email
```

### 7.5 网关管理

```bash
# 查看网关状态
hermes gateway status

# 停止网关
hermes gateway stop

# 重启网关
hermes gateway restart
```

---

## 8. 技能系统

### 8.1 技能是什么？

技能是 Hermes 的核心特性之一：
- **自动创建**: 完成复杂任务后自动保存为技能
- **自我改进**: 使用过程中自动优化
- **持久化**: 跨会话保留
- **可共享**: 可以从 Skills Hub 下载社区技能

### 8.2 查看和管理技能

```bash
# 查看已安装的技能
hermes skills

# 查看特定技能详情
hermes skills view <skill-name>

# 启用/禁用技能
hermes skills enable <skill-name>
hermes skills disable <skill-name>

# 删除技能
hermes skills delete <skill-name>
```

### 8.3 使用技能

```bash
# 列出可用技能
/skills

# 使用特定技能
/<skill-name>

# 在对话中自动触发
# 当检测到相关任务时，技能会自动激活
```

### 8.4 从 Skills Hub 安装技能

访问 [Skills Hub](https://skills.hermes-agent.com) 浏览社区技能：

```bash
# 安装技能（假设命令）
hermes skills install <skill-url-or-id>

# 更新所有技能
hermes skills update
```

### 8.5 创建自定义技能

技能文件位于 `~/.hermes/skills/`：

```yaml
# ~/.hermes/skills/my-skill.yaml
name: my-custom-skill
description: "描述这个技能的用途"
triggers:
  - "触发关键词1"
  - "触发关键词2"
instructions: |
  这里是技能的详细指令
  可以包含多行文本
tools:
  - shell
  - python
```

---

## 9. 定时任务

### 9.1 创建定时任务

Hermes 内置 cron 调度器：

```bash
# 创建定时任务（自然语言）
hermes cron add "每天早上 9 点发送今日待办事项"

# 创建定时任务（cron 表达式）
hermes cron add "0 9 * * *" "发送每日报告"

# 查看所有定时任务
hermes cron list
```

### 9.2 管理定时任务

```bash
# 暂停任务
hermes cron pause <task-id>

# 恢复任务
hermes cron resume <task-id>

# 删除任务
hermes cron delete <task-id>

# 立即执行任务
hermes cron run <task-id>
```

### 9.3 常见定时任务示例

```bash
# 每日备份
hermes cron add "0 2 * * *" "备份重要文件到云存储"

# 每周报告
hermes cron add "0 17 * * 5" "生成本周工作总结报告"

# 每月审计
hermes cron add "0 10 1 * *" "执行系统安全检查"

# 每小时提醒
hermes cron add "0 * * * *" "提醒我喝水和休息"
```

---

## 10. 故障排查

### 10.1 诊断工具

```bash
# 运行完整诊断
hermes doctor
```

诊断工具会检查：
- Python 版本
- 依赖包完整性
- 配置文件语法
- API Key 有效性
- 网络连接

### 10.2 常见问题

#### 问题 1: `command not found: hermes`

**解决方案**:
```bash
# 重新加载 shell 配置
source ~/.zshrc

# 或检查 PATH
echo $PATH

# 如果 Hermes 不在 PATH 中，手动添加
echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

#### 问题 2: API Key 错误

**解决方案**:
```bash
# 检查 API Key 是否正确配置
hermes config get openrouter_api_key

# 重新设置 API Key
hermes config set openrouter_api_key "your-api-key"
```

#### 问题 3: 依赖冲突

**解决方案**:
```bash
# 重新创建虚拟环境
cd ~/.hermes
rm -rf venv
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all]"
```

#### 问题 4: 权限问题

**解决方案**:
```bash
# 修复文件权限
chmod -R 755 ~/.hermes
chown -R $(whoami) ~/.hermes
```

### 10.3 查看日志

```bash
# 查看 Hermes 日志
tail -f ~/.hermes/logs/hermes.log

# 查看网关日志
tail -f ~/.hermes/logs/gateway.log
```

### 10.4 重置配置

```bash
# 备份当前配置
cp -r ~/.hermes ~/.hermes.backup

# 删除配置（谨慎操作）
rm -rf ~/.hermes

# 重新运行设置向导
hermes setup
```

---

## 11. 更新升级

### 11.1 使用内置更新命令

```bash
# 更新到最新版本
hermes update

# 查看当前版本
hermes --version
```

### 11.2 手动更新

```bash
# 如果使用 Git 安装
cd hermes-agent
git pull origin main
source venv/bin/activate
uv pip install -e ".[all]"

# 重启服务（如果网关在运行）
hermes gateway restart
```

### 11.3 回滚到旧版本

```bash
# 查看可用版本
git tag

# 切换到特定版本
git checkout v1.2.3
uv pip install -e ".[all]"
```

---

## 12. 完全卸载

### 12.1 停止所有服务

```bash
# 停止网关
hermes gateway stop

# 查看并终止所有 Hermes 进程
ps aux | grep hermes
kill -9 <PID>
```

### 12.2 删除 Hermes 文件

```bash
# 删除 Hermes 安装目录
rm -rf ~/.hermes

# 删除源代码（如果是从 Git 克隆的）
rm -rf ~/hermes-agent

# 删除虚拟环境（如果单独创建）
# 通常在 ~/.hermes/venv 中
```

### 12.3 清理环境变量

```bash
# 编辑 shell 配置文件
nano ~/.zshrc  # 或 nano ~/.bashrc

# 删除以下行（如果存在）：
# export PATH="$HOME/.hermes/bin:$PATH"
# source ~/.hermes/venv/bin/activate

# 重新加载配置
source ~/.zshrc
```

### 12.4 清理 Homebrew 依赖（可选）

```bash
# 清理未使用的依赖
brew autoremove

# 清理缓存
brew cleanup
```

### 12.5 删除 launchd 服务（如果创建了）

```bash
# 查看是否存在 launchd 服务
launchctl list | grep hermes

# 停止并删除服务
launchctl stop com.nousresearch.hermes
launchctl unload ~/Library/LaunchAgents/com.nousresearch.hermes.plist
rm ~/Library/LaunchAgents/com.nousresearch.hermes.plist
```

### 12.6 验证卸载

```bash
# 确认命令不存在
which hermes
# 应该返回空或 "hermes not found"

# 确认目录已删除
ls -la ~/.hermes
# 应该返回 "No such file or directory"
```

---

## 13. 常见问题 FAQ

### Q1: Hermes Agent 和 OpenClaw 有什么区别？

**A**: Hermes Agent 是 OpenClaw 的继任者，增加了：
- 自我改进的学习循环
- 自动技能创建和优化
- 跨会话记忆
- 更好的多平台支持
- 内置定时任务调度

### Q2: 可以在 M1/M2/M3 Mac 上运行吗？

**A**: 完全可以。Hermes 支持 Apple Silicon 架构，安装脚本会自动检测并配置。

### Q3: 必须使用 OpenRouter 吗？

**A**: 不是。支持多种提供商：OpenAI、Anthropic、Kimi、MiniMax 等，也可以配置自定义 API 端点。

### Q4: 如何在后台运行网关？

**A**: 使用 `nohup` 或创建 launchd 服务：

```bash
# 使用 nohup
nohup hermes gateway start > /dev/null 2>&1 &

# 或创建 launchd 服务（推荐）
cat > ~/Library/LaunchAgents/com.nousresearch.hermes.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.nousresearch.hermes</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/$(whoami)/.hermes/venv/bin/hermes</string>
        <string>gateway</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.nousresearch.hermes.plist
```

### Q5: 如何备份我的配置和记忆？

**A**:
```bash
# 备份整个 Hermes 目录
tar -czf hermes-backup-$(date +%Y%m%d).tar.gz ~/.hermes

# 或只备份重要文件
cp -r ~/.hermes/config.yaml ~/hermes-config-backup/
cp -r ~/.hermes/memories ~/hermes-memories-backup/
cp -r ~/.hermes/skills ~/hermes-skills-backup/
```

### Q6: 可以离线使用吗？

**A**: 部分功能可以。本地工具（shell、文件系统）可以离线使用，但 AI 对话需要网络连接来调用 LLM API。

### Q7: 如何迁移到另一台 Mac？

**A**:
```bash
# 旧 Mac 上备份
tar -czf hermes-backup.tar.gz ~/.hermes

# 传输到新 Mac（使用 scp、AirDrop 等）
scp hermes-backup.tar.gz user@new-mac:~

# 新 Mac 上恢复
tar -xzf hermes-backup.tar.gz
hermes doctor  # 验证配置
```

### Q8: 如何保护 API Key 安全？

**A**:
```bash
# 使用环境变量而不是直接写在配置中
export OPENROUTER_API_KEY="your-key"

# 在 config.yaml 中引用
# openrouter_api_key: ${OPENROUTER_API_KEY}

# 将环境变量添加到 .zshrc
echo 'export OPENROUTER_API_KEY="your-key"' >> ~/.zshrc

# 设置配置文件权限
chmod 600 ~/.hermes/config.yaml
```

### Q9: 如何自定义提示词（Prompt）？

**A**: 编辑人格文件：

```bash
# 查看可用的人格
ls ~/.hermes/personalities/

# 创建自定义人格
cat > ~/.hermes/personalities/my-assistant.md << EOF
你是一个专业的编程助手，擅长：
- Python 开发
- 系统架构设计
- 代码审查和优化

你的回答应该：
1. 简洁明了
2. 提供代码示例
3. 解释关键概念
EOF

# 使用自定义人格
/personality my-assistant
```

### Q10: 性能优化建议？

**A**:
```bash
# 1. 使用更快的模型
hermes model openrouter:google/gemini-flash

# 2. 减少工具数量
hermes tools disable <unused-tools>

# 3. 定期压缩上下文
/compress  # 在对话中

# 4. 使用本地模型（如果有 GPU）
hermes config set model_endpoint "http://localhost:8080"

# 5. 限制对话历史长度
hermes config set max_context_turns 20
```

---

## 📚 更多资源

- **官方文档**: https://hermes-agent.nousresearch.com/docs
- **GitHub 仓库**: https://github.com/NousResearch/hermes-agent
- **Skills Hub**: https://skills.hermes-agent.com
- **Discord 社区**: https://discord.gg/nous-research
- **问题反馈**: https://github.com/NousResearch/hermes-agent/issues

---

## 📝 文档维护

- **最后更新**: 2026-04-13
- **版本**: v1.0

---

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

Hermes Agent macOS 安装、配置与使用完全指南

# Mac M2 系统：用Homebrew安装Colima并配置Docker镜像加速（超详细避坑版）

作为Mac M2用户，在本地开发中离不开Docker环境，但Docker Desktop不仅体积臃肿、后台资源占用高，还存在商业授权限制，对于追求轻量、高效的开发者来说并不友好。而Colima作为一款基于Lima构建的轻量级容器运行时工具，完美适配Apple Silicon（M1/M2系列）架构，开源免费、资源占用低，还能无缝对接Docker CLI，成为Mac M2用户替代Docker Desktop的最优解。

本文将详细讲解：如何在Mac M2系统上通过Homebrew安装Colima、启动Docker服务，以及最关键的——基于Colima配置文件，配置指定的3个Docker镜像加速地址，彻底解决国内拉取Docker镜像慢、超时的问题，全程步骤可复制，新手也能轻松上手。

## 一、前言：为什么选择Colima？

在Mac M2上使用Colima，相比Docker Desktop有3个核心优势，也是我放弃Docker Desktop的关键原因：



- 轻量高效：Colima基于轻量Linux虚拟机（Lima）运行，默认仅占用2GB内存，启动速度快，不会像Docker Desktop那样常驻后台占用大量系统资源，尤其适合MacBook Air等资源受限设备；

- 开源免费：采用MIT开源协议，无任何商业授权限制，个人开发、企业使用都无需担心版权问题，避免了Docker Desktop商业版的付费困扰；

- 原生适配：完美支持Mac M2的ARM64架构，无需依赖Rosetta转译，可直接运行ARM版本容器，同时也支持通过Rosetta启用x86容器兼容模式，兼顾性能与兼容性；

- 无缝兼容：启动Colima后，可直接使用标准Docker CLI命令（docker run、docker pull等），无需额外配置，迁移成本几乎为零。

本次我们将完成：Homebrew安装Colima → 安装Docker CLI → 启动Colima（Docker服务） → 配置3个指定镜像加速 → 验证加速生效，全程实操无冗余，附避坑指南。

## 二、前置准备：确认系统与Homebrew环境

### 2.1 系统要求（Mac M2专属）

确保你的Mac M2系统版本 ≥ macOS 10.15（Catalina），Apple Silicon架构原生支持，无需额外配置兼容性。可通过「关于本机」查看系统版本，若版本过低，建议先升级系统（避免Colima启动失败）。

### 2.2 安装Homebrew（必做）

Colima和Docker CLI均通过Homebrew安装，若你的Mac未安装Homebrew，执行以下命令一键安装（复制到终端直接运行）：

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

安装过程中会提示输入电脑密码（用于授权Homebrew安装依赖），等待5-10分钟（取决于网络速度），出现“Installation successful”即安装完成。

安装完成后，执行以下命令验证Homebrew是否正常工作，避免后续安装失败：

```bash
brew doctor  # 检查Homebrew环境（无报错即正常）
brew update  # 更新软件包索引，确保下载最新版本
```

## 三、核心步骤：安装Colima与Docker CLI

注意：Colima仅提供Docker运行时环境（相当于Docker Engine），还需要安装Docker CLI（命令行工具）才能执行docker相关命令，两者缺一不可。

### 3.1 安装Colima

在终端执行以下命令，通过Homebrew安装Colima（当前最新稳定版本，适配Mac M2）：

```bash
brew install colima
```

安装过程中，Homebrew会自动安装Colima的依赖（如Lima虚拟机），无需手动干预，等待安装完成即可。Colima安装完成后，可通过以下命令查看版本，验证安装成功：

```bash
colima version
```

若输出类似“colima version 0.10.0”（版本号可能不同），说明Colima安装成功。

### 3.2 安装Docker CLI

执行以下命令，安装Docker命令行工具（Docker CLI）：

```bash
brew install docker docker-compose
```

docker-compose用于管理多容器应用，建议一起安装，后续开发中会用到。安装完成后，验证Docker CLI版本：

```bash
docker --version  # 查看Docker CLI版本
docker-compose --version  # 查看Docker Compose版本
```

输出类似“Docker version 29.0.1, build 7d4bcd8”即安装成功。此时Docker CLI已安装，但由于还未启动Colima（Docker运行时），执行docker相关命令会提示“无法连接Docker守护进程”，属于正常现象，下一步启动Colima即可解决。

## 四、启动Colima，激活Docker服务

Colima启动后，会自动创建一个轻量Linux虚拟机，在其中启动Docker守护进程，并自动配置Docker上下文（无需手动切换），启动命令非常简单。

### 4.1 基础启动（默认配置）

在终端执行以下命令，启动Colima（默认配置：2核CPU、2GB内存，足够日常开发使用）：

```bash
colima start
```

首次启动时，Colima会下载Lima虚拟机镜像（约几百MB），速度取决于网络，耐心等待即可。启动成功后，终端会输出类似以下日志：

```bash
INFO[0001] starting colima                              
INFO[0001] runtime: docker                              
INFO[0004] starting ...                                  context=vm
INFO[0012] provisioning ...                              context=docker
INFO[0015] starting ...                                  context=docker
INFO[0020] ready
```

出现“ready”即表示Colima启动成功，Docker服务已激活。

### 4.2 自定义资源配置（推荐，适配Mac M2）

若你的Mac M2配置较高（如16GB内存），可在启动时指定CPU、内存和磁盘大小，提升Docker运行性能，命令如下（按需调整参数）：

```bash
colima start --cpu 4 --memory 8 --disk 40
```

参数说明：

- --cpu 4：分配4核CPU（Mac M2默认8核，建议分配4-6核）；

- --memory 8：分配8GB内存（建议不超过系统内存的一半，避免影响Mac正常使用）；

- --disk 40：分配40GB磁盘空间（用于存储Docker镜像和容器数据）。

### 4.3 验证Colima与Docker连接正常

Colima启动后，执行以下命令，验证Docker服务是否正常工作：

```bash
docker run hello-world
```

若输出“Hello from Docker!”相关内容，说明Colima与Docker CLI连接正常，Docker服务已完全激活，可以正常使用Docker命令了。

补充：Colima的常用管理命令（后续会用到）：

```bash
colima stop        # 优雅停止Colima（推荐，会保存容器状态）
colima stop --force # 强制停止Colima（用于异常状态）
colima restart     # 重启Colima
colima status      # 查看Colima运行状态
colima delete      # 彻底删除Colima实例（谨慎使用，会删除镜像和容器）
```

## 五、关键步骤：配置Docker镜像加速（重点避坑）

这是本文的核心的部分！国内直接拉取Docker官方镜像（Docker Hub、GHCR）速度极慢，甚至会超时失败，我们需要配置指定的3个镜像加速地址，实现快速拉取。

注意：Colima的Docker配置**不使用传统的/etc/docker/daemon.json文件**，而是通过自身的配置文件（colima.yaml）管理，修改后重启Colima即可生效，这也是很多新手容易踩坑的地方——误以为和Linux系统的Docker配置方式一致，导致配置无效。

### 5.1 明确要配置的3个镜像加速地址

本次需要配置的3个镜像加速地址，覆盖了Docker Hub和GHCR的加速，适配日常所有镜像拉取场景：

- 腾讯云加速：https://mirror.ccs.tencentyun.com（通用Docker Hub加速，稳定快速）；

- DaoCloud Docker Hub加速：https://docker.m.daocloud.io（专门优化Docker Hub镜像拉取）；

- DaoCloud GHCR加速：https://ghcr.m.daocloud.io（解决GHCR镜像拉取超时问题）。

### 5.2 编辑Colima配置文件（核心操作）

Colima的默认配置文件路径为：~/.colima/default/colima.yaml，我们需要在这个文件中添加镜像加速配置，步骤如下：

#### 步骤1：停止Colima（必须先停止，否则配置修改无效）

```bash
colima stop
```

#### 步骤2：打开Colima配置文件

使用nano编辑器打开配置文件（简单易操作，适合新手），命令如下：

```bash
nano ~/.colima/default/colima.yaml
```

打开后，你会看到配置文件的默认内容（包含注释和默认配置），其中有一行“docker: {}”，这就是我们需要修改的地方。

#### 步骤3：添加镜像加速配置（严格注意缩进！）

YAML格式对缩进要求**极端严格**，错一个空格就会导致Colima启动失败（这是最常见的坑），请务必按照以下格式修改：

找到文件中的“docker: {}”，将其替换为以下内容（复制粘贴即可，确保缩进正确）：

```yaml
# Docker daemon configuration that maps directly to daemon.json.
# https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file.
# NOTE: some settings may affect Colima's ability to start docker. e.g. `hosts`.
#
# EXAMPLE - disable buildkit
# docker:
#   features:
#     buildkit: false
#
# EXAMPLE - add insecure registries
# docker:
#   insecure-registries:
#     - myregistry.com:5000
#     - host.docker.internal:5000
#
# Colima default behaviour: buildkit enabled
# Default: {}
docker:
  registry-mirrors:
    - https://mirror.ccs.tencentyun.com
    - https://docker.m.daocloud.io
    - https://ghcr.m.daocloud.io
```

⚠️ 避坑提醒（必看）：

- 必须使用**空格缩进**，不能用Tab键（Tab缩进会导致配置解析失败）；

- “docker:”顶格写，后面加一个空格（YAML语法要求）；

- “mirrors:”前面缩进2个空格，后面加一个空格；

- 每个加速地址前面缩进4个空格，以“- ”开头（横杠后面加一个空格）；

- 加速地址不能有多余的符号（如引号、逗号），直接复制粘贴即可。

若你不确定缩进是否正确，可直接删除原有的“docker: {}”，复制上面的完整配置（从“docker:”开始），粘贴到配置文件中，确保格式和上面一致。

#### 步骤4：保存并退出编辑器

nano编辑器的保存退出操作：

1. 按键盘上的「Control + O」（字母O，不是数字0），弹出保存提示，按「回车」确认保存；

2. 按「Control + X」，退出nano编辑器，回到终端。

### 5.3 重启Colima，使加速配置生效

配置修改完成后，执行以下命令重启Colima，加载新的镜像加速配置：

```bash
colima start
```

重启过程和首次启动类似，等待出现“ready”即重启成功，此时镜像加速配置已生效。

## 六、验证镜像加速是否生效（必做）

配置完成后，一定要验证加速是否生效，避免配置错误导致白忙活，执行以下命令即可快速验证：

```bash
docker info | grep -A 5 "Registry Mirrors"
```

若输出以下内容（包含我们配置的3个加速地址），说明镜像加速配置**完全生效**：

```bash
Registry Mirrors:
  https://mirror.ccs.tencentyun.com/
  https://docker.m.daocloud.io/
  https://ghcr.m.daocloud.io/
```

补充：测试加速效果（可选）

我们可以拉取一个常用镜像（如nginx），测试加速后的拉取速度：

```bash
docker pull nginx
```

若拉取速度从原来的几KB/s提升到几十MB/s，甚至上百MB/s，说明加速效果明显，配置成功。

也可以测试GHCR镜像拉取（之前容易超时），验证DaoCloud GHCR加速是否生效：

```bash
docker pull ghcr.io/github/super-linter:latest
```

若能正常拉取，无超时提示，说明GHCR加速配置成功。

## 七、常见问题与避坑指南（Mac M2专属）

在操作过程中，新手可能会遇到一些问题，这里整理了最常见的3个问题及解决方案，帮你快速避坑。

### 问题1：Colima启动失败，提示“Job for docker.service failed”

✅ 原因：colima.yaml配置文件语法错误（90%是缩进错误，比如用了Tab、缩进不一致），导致Docker守护进程无法启动。

✅ 解决方案：

1. 强制停止Colima：`colima stop -f`；

2. 重新编辑配置文件：`nano ~/.colima/default/colima.yaml`；

3. 严格按照本文5.2节的格式，重新添加镜像加速配置（确保用空格缩进，无Tab）；

4. 保存退出后，重新启动Colima：`colima start`。

若仍失败，可执行`colima delete default -f`删除异常实例，再重新执行`colima start`（会重建实例，不会删除本地镜像和容器）。

### 问题2：验证加速时，未显示配置的3个镜像地址

✅ 原因：Colima未加载新的配置，或配置文件路径错误。

✅ 解决方案：

1. 确认配置文件路径正确：必须是`~/.colima/default/colima.yaml`（default是Colima的默认实例名称）；

2. 重新停止并重启Colima：`colima stop && colima start`；

3. 若仍未显示，执行重建实例命令：`colima delete default -f && colima start`，重建后重新配置加速。

### 问题3：Docker命令提示“Cannot connect to the Docker daemon”

✅ 原因：Colima未启动，或Docker上下文未自动切换。

✅ 解决方案：

1. 启动Colima：`colima start`；

2. 查看Docker上下文：`docker context ls`，确保当前上下文为“colima”；

3. 若上下文不是colima，执行`docker context use colima`切换，再重新执行Docker命令。

### 问题4：之前安装过Docker Desktop，导致Colima启动失败

✅ 原因：Docker Desktop残留的socket文件（/private/var/run/docker.sock）与Colima冲突。

✅ 解决方案：彻底卸载Docker Desktop，删除残留文件：

```bash
# 删除残留socket文件
sudo rm /private/var/run/docker.sock
# 停止并重启Colima
colima stop -f && colima start
```

## 八、总结

对于Mac M2用户来说，Colima + Docker CLI的组合，是替代Docker Desktop的最优解——轻量、开源、免费，且适配性拉满。本文通过详细的步骤，完成了从Homebrew安装Colima、Docker CLI，到启动Colima服务、配置指定镜像加速的全过程，重点强调了YAML配置的缩进问题（最容易踩坑），以及常见问题的解决方案。

核心要点回顾：

- Colima配置Docker镜像加速，需修改~/.colima/default/colima.yaml，而非/etc/docker/daemon.json；

- YAML配置必须用空格缩进，禁用Tab，否则会导致Colima启动失败；

- 配置完成后，重启Colima即可生效，用`docker info | grep -A 5 "Registry Mirrors"`验证；

- 3个加速地址覆盖了Docker Hub和GHCR，解决国内拉取镜像慢、超时的问题。

按照本文步骤操作，新手也能轻松搭建Mac M2的Docker开发环境，后续使用Docker命令和之前完全一致，无需额外适应。如果在操作过程中遇到其他问题，可在评论区留言，我会及时回复解答。
> （注：文档部分内容可能由 AI 生成）

Mac M2 系统：用Homebrew安装Colima并配置Docker镜像加速（超详细避坑版）

# OpenClaw 完整安装教程

> **版本说明**: 本教程基于 OpenClaw 最新版本（2025年2月）
> 
> **官方资源**:
> - 官网: https://openclaw.ai
> - 文档: https://docs.openclaw.ai
> - GitHub: https://github.com/openclaw/openclaw
> - Discord: https://discord.gg/clawd

---

## 📋 目录



1. [系统要求](#一系统要求)
2. [安装方式](#二安装方式)
   - npm 安装（推荐）
   - pnpm 安装
   - bun 安装
   - 源码安装
   - Docker 安装
   - 命令行安装
3. [首次配置](#三首次配置)
   - 运行引导向导
   - 配置文件详解
   - AI 模型配置
   - 通讯频道配置
4. [启动与使用](#四启动与使用)
5. [卸载方法](#五卸载方法)
6. [常见问题与解决方案](#六常见问题与解决方案)
7. [高级配置](#七高级配置)

---

## 一、系统要求

### 1.1 基础要求

| 项目 | 要求 |
|------|------|
| **Node.js** | ≥ 22 （必须） |
| **操作系统** | macOS / Linux / Windows (WSL2) |
| **包管理器** | npm / pnpm / bun |
| **内存** | 建议 4GB+ |
| **磁盘空间** | 至少 2GB 可用空间 |

### 1.2 检查 Node.js 版本

```bash
node --version
# 输出应该 >= v22.0.0
```

如果版本过低，请先升级 Node.js：

```bash
# 使用 nvm 升级（推荐）
nvm install 22
nvm use 22

# 或使用官方安装包
# https://nodejs.org/
```

---

## 二、安装方式

### 2.1 npm 安装（推荐）⭐

这是最简单、最推荐的安装方式：

```bash
# 全局安装 OpenClaw
npm install -g openclaw@latest

# 验证安装
openclaw --version
```

### 2.2 pnpm 安装

```bash
# 使用 pnpm 安装
pnpm add -g openclaw@latest

# 验证安装
openclaw --version
```

### 2.3 bun 安装

```bash
# 使用 bun 安装
bun add -g openclaw@latest

# 验证安装
openclaw --version
```

### 2.4 从源码安装（开发版）

适合想参与开发或使用最新功能的用户：

```bash
# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖（推荐使用 pnpm）
pnpm install

# 构建 UI
pnpm ui:build

# 构建项目
pnpm build

# 运行引导向导
pnpm openclaw onboard --install-daemon

# 开发模式（自动重载）
pnpm gateway:watch
```

### 2.5 Docker 安装

```bash
# 拉取镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest
```
### 2.6 命令行安装
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
详细 Docker 配置请参考：https://docs.openclaw.ai/install/docker

---

## 三、首次配置

### 3.1 运行引导向导（强烈推荐）

OpenClaw 提供了一个交互式向导，会一步步引导你完成配置：

```bash
# 运行向导并安装守护进程
openclaw onboard --install-daemon
```

向导会帮助你配置：
- ✅ Gateway 服务
- ✅ 工作目录
- ✅ 通讯频道（WhatsApp、Telegram、Slack 等）
- ✅ AI 模型
- ✅ Skills 技能

### 3.2 配置文件详解

配置文件位于：`~/.openclaw/openclaw.json`

#### 最小配置示例

```json5
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}
```

#### 完整配置示例

```json5
{
  // === AI 模型配置 ===
  "agent": {
    // 默认使用的 AI 模型
    "model": "anthropic/claude-opus-4-6",
    
    // 思考级别: off | minimal | low | medium | high | xhigh
    "thinking": "medium",
    
    // 工作空间路径
    "workspace": "~/.openclaw/workspace",
    
    // 默认行为
    "defaults": {
      // 沙盒模式: off | non-main | all
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  
  // === Gateway 配置 ===
  "gateway": {
    // 监听地址
    "bind": "loopback",
    
    // 端口号
    "port": 18789,
    
    // 详细日志
    "verbose": false,
    
    // 身份验证
    "auth": {
      "mode": "tailscale",  // none | password | tailscale
      "password": "your-secure-password"
    },
    
    // Tailscale 配置（可选）
    "tailscale": {
      "mode": "off",  // off | serve | funnel
      "resetOnExit": false
    }
  },
  
  // === 通讯频道配置 ===
  "channels": {
    // Telegram 配置
    "telegram": {
      "botToken": "123456:ABCDEF",
      "allowFrom": ["your_telegram_id"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    },
    
    // WhatsApp 配置
    "whatsapp": {
      "allowFrom": ["+86138xxxxxxxx"],
      "groups": ["*"]
    },
    
    // Slack 配置
    "slack": {
      "botToken": "xoxb-xxx",
      "appToken": "xapp-xxx",
      "allowFrom": ["U123456"]
    },
    
    // Discord 配置
    "discord": {
      "token": "MTIx...",
      "allowFrom": ["123456789"],
      "dmPolicy": "pairing"  // pairing | open
    },
    
    // Signal 配置
    "signal": {
      "account": "+86138xxxxxxxx",
      "allowFrom": ["+86138xxxxxxxx"]
    }
  },
  
  // === 模型提供商配置 ===
  "models": {
    "anthropic": {
      "apiKey": "sk-ant-api...",
      "maxTokens": 8192
    },
    "openai": {
      "apiKey": "sk-...",
      "maxTokens": 4096
    }
  },
  
  // === 工具配置 ===
  "tools": {
    // 浏览器配置
    "browser": {
      "enabled": true,
      "color": "#FF4500"
    },
    
    // Web 搜索配置
    "web": {
      "braveApiKey": "your-brave-api-key"
    }
  }
}
```

### 3.3 AI 模型配置

OpenClaw 支持多种 AI 模型，推荐配置如下：

#### Anthropic Claude（强烈推荐）

```json5
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  },
  "models": {
    "anthropic": {
      "apiKey": "sk-ant-api03-..."
    }
  }
}
```

获取 API Key: https://console.anthropic.com/

#### OpenAI GPT

```json5
{
  "agent": {
    "model": "openai/gpt-4o"
  },
  "models": {
    "openai": {
      "apiKey": "sk-..."
    }
  }
}
```

#### 其他模型

```json5
// Moonshot / 月之暗面
"agent": { "model": "moonshot/kimi-k2.5" }

// Google Gemini
"agent": { "model": "google/gemini-2.0-flash" }

// DeepSeek
"agent": { "model": "deepseek/deepseek-chat" }
```

### 3.4 通讯频道配置

#### Telegram 配置

1. 创建 Bot：
   - 与 [@BotFather](https://t.me/botfather) 对话
   - 发送 `/newbot`
   - 获取 Bot Token

2. 获取你的 Chat ID：
   - 与 [@userinfobot](https://t.me/userinfobot) 对话

3. 配置：

```json5
{
  "channels": {
    "telegram": {
      "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
      "allowFrom": ["123456789"]
    }
  }
}
```

#### WhatsApp 配置

```bash
# 登录 WhatsApp
openclaw channels login
```

按提示扫描二维码即可。

#### Slack 配置

1. 创建 Slack App: https://api.slack.com/apps
2. 获取 Bot Token 和 App Token
3. 配置：

```json5
{
  "channels": {
    "slack": {
      "botToken": "xoxb-xxx",
      "appToken": "xapp-xxx",
      "allowFrom": ["U12345678"]
    }
  }
}
```

#### Discord 配置

1. 创建 Bot: https://discord.com/developers/applications
2. 获取 Bot Token
3. 配置：

```json5
{
  "channels": {
    "discord": {
      "token": "MTIx...",
      "allowFrom": ["123456789"],
      "dmPolicy": "pairing"
    }
  }
}
```

---

## 四、启动与使用

### 4.1 启动 Gateway

```bash
# 前台启动（查看日志）
openclaw gateway --verbose

# 指定端口启动
openclaw gateway --port 18789 --verbose

# 后台启动（通过守护进程）
openclaw gateway start
```

### 4.2 检查状态

```bash
# 查看 Gateway 状态
openclaw gateway status

# 运行诊断
openclaw doctor
```

### 4.3 基本命令

```bash
# 发送消息
openclaw message send --to +1234567890 --message "Hello from OpenClaw"

# 与 AI 对话
openclaw agent --message "你好，介绍一下自己"

# 查看帮助
openclaw --help
openclaw gateway --help
```

### 4.4 聊天命令

在与 AI 对话时可以使用以下命令：

| 命令 | 说明 |
|------|------|
| `/status` | 查看当前会话状态 |
| `/new` 或 `/reset` | 重置会话 |
| `/compact` | 压缩会话上下文 |
| `/think <级别>` | 设置思考级别 |
| `/verbose on/off` | 开启/关闭详细模式 |
| `/usage` | 查看使用量 |
| `/restart` | 重启 Gateway（仅限拥有者）|

---

## 五、卸载方法

### 5.1 npm 卸载

```bash
# 卸载全局包
npm uninstall -g openclaw

# 清理配置文件（可选）
rm -rf ~/.openclaw
```

### 5.2 停止并移除守护进程

```bash
# macOS (launchd)
launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist
rm ~/Library/LaunchAgents/com.openclaw.gateway.plist

# Linux (systemd)
systemctl --user stop openclaw-gateway
systemctl --user disable openclaw-gateway
rm ~/.config/systemd/user/openclaw-gateway.service
```

### 5.3 Docker 卸载

```bash
# 停止并删除容器
docker stop openclaw
docker rm openclaw

# 删除镜像
docker rmi openclaw/openclaw:latest

# 清理数据卷（谨慎操作）
rm -rf ~/.openclaw
```

### 5.4 完全清理

```bash
# 删除所有 OpenClaw 相关数据
rm -rf ~/.openclaw
rm -rf ~/Library/Logs/openclaw        # macOS 日志
rm -rf ~/.cache/openclaw              # 缓存
```

---

## 六、常见问题与解决方案

### 6.1 安装问题

#### Q1: 安装时出现权限错误

**错误信息**:
```
npm ERR! code EACCES
npm ERR! syscall access
```

**解决方案**:
```bash
# 方法1：修改 npm 默认目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw@latest

# 方法2：使用 npx（无需全局安装）
npx openclaw@latest ...

# 方法3：使用 sudo（不推荐）
sudo npm install -g openclaw@latest
```

#### Q2: Node.js 版本不兼容

**错误信息**:
```
error openclaw@x.x.x: The engine "node" is incompatible with this module
```

**解决方案**:
```bash
# 使用 nvm 安装 Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

# 验证版本
node --version  # 应显示 v22.x.x
```

#### Q3: 安装后命令找不到

**解决方案**:
```bash
# 检查全局安装路径
npm config get prefix

# 添加到 PATH
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证
which openclaw
```

### 6.2 启动问题

#### Q4: Gateway 启动失败 - 端口被占用

**错误信息**:
```
Error: listen EADDRINUSE: address already in use :::18789
```

**解决方案**:
```bash
# 查找占用端口的进程
lsof -i :18789
# 或
netstat -tuln | grep 18789

# 杀死进程
kill -9 <PID>

# 或使用其他端口
openclaw gateway --port 18790
```

#### Q5: 配置文件格式错误

**错误信息**:
```
SyntaxError: Unexpected token } in JSON at position ...
```

**解决方案**:
```bash
# 验证 JSON 格式
openclaw doctor

# 或使用在线工具验证 ~/.openclaw/openclaw.json
# 注意：JSON5 允许注释，但必须是有效的 JSON5 格式
```

#### Q6: 守护进程无法启动

**解决方案**:
```bash
# macOS
launchctl list | grep openclaw
launchctl start com.openclaw.gateway

# Linux
systemctl --user status openclaw-gateway
systemctl --user restart openclaw-gateway
journalctl --user -u openclaw-gateway -f
```

### 6.3 AI 模型问题

#### Q7: API Key 无效

**错误信息**:
```
401 Unauthorized - Invalid API key
```

**解决方案**:
1. 检查 API Key 是否正确
2. 确认 API Key 有可用额度
3. 检查配置文件中的 Key 是否被正确转义

```bash
# 测试 API Key
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"
```

#### Q8: 模型响应缓慢或超时

**解决方案**:
```json5
// 在配置中添加超时设置
{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "timeout": 120000  // 120秒
  }
}
```

#### Q9: 模型切换不生效

**解决方案**:
```bash
# 重启 Gateway
openclaw gateway restart

# 或使用命令行指定模型
openclaw agent --model openai/gpt-4o --message "Hello"
```

### 6.4 通讯频道问题

#### Q10: Telegram Bot 不响应

**排查步骤**:
1. 检查 Bot Token 是否正确
2. 确认已向 Bot 发送 `/start`
3. 检查 allowFrom 是否包含你的 Chat ID
4. 查看 Gateway 日志

```bash
openclaw gateway --verbose
```

#### Q11: WhatsApp 断开连接

**解决方案**:
```bash
# 重新登录
openclaw channels login

# 检查 creds 文件
ls ~/.openclaw/credentials/whatsapp/
```

#### Q12: Discord DM 无法接收

**解决方案**:
```json5
{
  "channels": {
    "discord": {
      "dmPolicy": "pairing",  // 改为 "open" 允许所有人
      "allowFrom": ["*"]      // 允许所有用户
    }
  }
}
```

### 6.5 工具使用问题

#### Q13: 浏览器控制无法使用

**解决方案**:
```bash
# 确保已安装 Chrome/Chromium
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

# Linux
google-chrome --version

# 在配置中启用浏览器
{
  "browser": {
    "enabled": true
  }
}
```

#### Q14: Web 搜索返回错误

**错误信息**:
```
missing_brave_api_key
```

**解决方案**:
1. 获取 Brave API Key: https://brave.com/search/api/
2. 配置 Key：

```bash
openclaw configure --section web
# 或手动编辑配置文件
{
  "tools": {
    "web": {
      "braveApiKey": "your-api-key"
    }
  }
}
```

### 6.6 性能问题

#### Q15: 内存占用过高

**解决方案**:
```json5
{
  "agent": {
    // 启用会话修剪
    "pruneSessions": true,
    "maxSessionAge": 3600000  // 1小时
  }
}
```

#### Q16: 响应速度慢

**优化建议**:
1. 使用更快的模型（如 Claude Haiku 或 GPT-3.5）
2. 启用流式响应
3. 减少上下文长度

```json5
{
  "agent": {
    "model": "anthropic/claude-haiku",
    "streaming": true,
    "contextWindow": 4000
  }
}
```

---

## 七、高级配置

### 7.1 多模型故障转移

```json5
{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "fallbackModels": [
      "openai/gpt-4o",
      "moonshot/kimi-k2.5"
    ]
  }
}
```

### 7.2 Tailscale 远程访问

```json5
{
  "gateway": {
    "bind": "loopback",
    "auth": {
      "mode": "tailscale"
    },
    "tailscale": {
      "mode": "serve",  // serve 或 funnel
      "resetOnExit": false
    }
  }
}
```

### 7.3 沙盒安全配置

```json5
{
  "agent": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",  // 非主会话使用 Docker 沙盒
        "allowlist": ["bash", "read", "write", "edit"],
        "denylist": ["browser", "cron", "gateway"]
      }
    }
  }
}
```

### 7.4 自定义 Skills

```bash
# 安装技能
openclaw skills install weather
openclaw skills install 1password

# 查看已安装技能
openclaw skills list

# 更新技能
openclaw skills update
```

### 7.5 Cron 定时任务

```bash
# 添加定时任务
openclaw cron add --name "daily-summary" \
  --schedule "0 9 * * *" \
  --message "总结今天的日程"

# 列出定时任务
openclaw cron list

# 删除定时任务
openclaw cron remove --name "daily-summary"
```

---

## 八、更新 OpenClaw

```bash
# 检查更新
openclaw --version

# 更新到最新版本
npm update -g openclaw@latest

# 或重新安装
npm install -g openclaw@latest

# 运行迁移
openclaw doctor
```

---

## 九、获取帮助

### 9.1 官方资源

- 📚 文档: https://docs.openclaw.ai
- 💬 Discord: https://discord.gg/clawd
- 🐛 GitHub Issues: https://github.com/openclaw/openclaw/issues
- 🌐 官网: https://openclaw.ai

### 9.2 诊断工具

```bash
# 运行完整诊断
openclaw doctor

# 查看日志
openclaw logs

# 检查配置
openclaw config get
```

### 9.3 调试模式

```bash
# 开启详细日志
openclaw gateway --verbose

# 调试特定频道
DEBUG=telegram:* openclaw gateway
```

---

## 十、安全建议

1. **保护 API Keys**: 不要将 API Keys 提交到 Git
2. **使用 allowlist**: 配置 `allowFrom` 限制谁可以与 Bot 交互
3. **启用 DM 配对**: 默认使用 `dmPolicy: "pairing"`
4. **定期更新**: 保持 OpenClaw 和依赖项更新
5. **审查权限**: 定期运行 `openclaw doctor` 检查配置

---

> **恭喜！** 你已经完成了 OpenClaw 的完整安装配置。现在可以开始与你的个人 AI 助手对话了！
> 
> 如果遇到问题，记得查看第六部分的常见问题，或加入 Discord 社区寻求帮助。

OpenClaw 完整安装教程

# 优雅实现Java手机号脱敏：基于Jackson自定义注解方案
在日常的后端开发中，用户手机号等敏感信息的脱敏处理是数据安全合规的基本要求。直接在业务代码中硬编码脱敏逻辑会导致代码冗余、维护成本高，本文将分享一种基于Jackson自定义注解的优雅实现方案，只需一个注解即可完成手机号字段的自动脱敏。

## 一、需求背景
在接口返回用户数据时，手机号这类敏感信息不能明文展示，通常需要按照`138****5678`的格式进行脱敏。我们希望：
1. 脱敏逻辑与业务代码解耦，不侵入业务层
2. 使用简单，只需在字段上添加注解即可生效
3. 具备容错性，非手机号格式的字符串原样返回
4. 空值不做处理，避免空指针异常



## 二、技术选型
- **Jackson**：Java生态中主流的JSON序列化/反序列化框架，支持自定义序列化逻辑
- **Hutool**：国产优秀的Java工具类库，提供了完善的手机号校验和脱敏工具，避免重复造轮子
- **自定义注解**：通过注解标记需要脱敏的字段，实现配置化使用

## 三、实现步骤

### 3.1 引入依赖
首先确保项目中引入了必要的依赖（以Maven为例）：
```xml

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.15.2</version>
</dependency>


<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.20</version>
</dependency>
```

### 3.2 自定义手机号脱敏注解
创建自定义注解`PhoneDesensitization`，用于标记需要脱敏的手机号字段：
```java
package com.nsw.server.common.annotation;

import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.nsw.server.common.config.PhoneDesensitizationSerializer;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 手机号脱敏注解
 * 标注在需要脱敏的phone字段上
 *
 * @author weizhenwang
 */
// 注解作用目标：字段
@Target({ElementType.FIELD})
// 注解保留策略：运行时生效（反射可获取）
@Retention(RetentionPolicy.RUNTIME)
// 生成文档时包含该注解
@Documented
// 嵌套Jackson注解的标记，避免注解冲突
@JacksonAnnotationsInside
// 指定序列化器：使用自定义的PhoneDesensitizationSerializer处理字段
@JsonSerialize(using = PhoneDesensitizationSerializer.class)
public @interface PhoneDesensitization {
}
```

**注解关键属性说明**：
- `@Target(ElementType.FIELD)`：限定注解只能用在类的字段上
- `@Retention(RetentionPolicy.RUNTIME)`：注解在运行时保留，Jackson序列化时能通过反射识别
- `@JacksonAnnotationsInside`：Jackson的注解，用于嵌套自定义注解，防止注解失效
- `@JsonSerialize`：指定该字段序列化时使用的自定义序列化器

### 3.3 实现手机号脱敏序列化器
创建`PhoneDesensitizationSerializer`类，继承Jackson的`JsonSerializer`，实现具体的脱敏逻辑：
```java
package com.nsw.server.common.config;

import cn.hutool.core.lang.Validator;
import cn.hutool.core.util.DesensitizedUtil;
import cn.hutool.core.util.StrUtil;
import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.databind.JsonSerializer;
import com.fasterxml.jackson.databind.SerializerProvider;

import java.io.IOException;

/**
 * 手机号脱敏序列化器
 */
public class PhoneDesensitizationSerializer extends JsonSerializer<String> {

    @Override
    public void serialize(String phone, JsonGenerator gen, SerializerProvider serializers) throws IOException {
        // 1. 空值处理：空字符串/Null直接返回，避免空指针
        if (StrUtil.isBlank(phone)) {
            gen.writeString(phone);
            return;
        }

        // 2. 手机号格式校验：使用Hutool的Validator工具类
        if (Validator.isMobile(phone)) {
            // 3. 格式正确则脱敏：Hutool的DesensitizedUtil实现138****5678格式
            String desensitizedPhone = DesensitizedUtil.mobilePhone(phone);
            gen.writeString(desensitizedPhone);
        } else {
            // 4. 格式错误则原样返回，保证数据兼容性
            gen.writeString(phone);
        }
    }
}
```

**核心逻辑说明**：
1. **空值防护**：通过`StrUtil.isBlank()`判断空值，避免后续逻辑出现NPE
2. **格式校验**：`Validator.isMobile()`支持中国大陆11位手机号格式校验
3. **脱敏处理**：`DesensitizedUtil.mobilePhone()`内置了成熟的手机号脱敏逻辑（保留前3位和后4位，中间4位替换为*）
4. **容错处理**：非手机号格式的字符串原样返回，避免数据异常

## 四、使用示例

### 4.1 实体类中使用注解
在需要脱敏的手机号字段上添加`@PhoneDesensitization`注解：
```java
package com.nsw.server.entity;

import com.nsw.server.common.annotation.PhoneDesensitization;
import lombok.Data;

@Data
public class User {
    /**
     * 用户ID
     */
    private Long id;
    
    /**
     * 用户名
     */
    private String username;
    
    /**
     * 手机号（脱敏展示）
     */
    @PhoneDesensitization
    private String phone;
    
    /**
     * 邮箱
     */
    private String email;
}
```

### 4.2 接口返回效果
编写测试接口：
```java
package com.nsw.server.controller;

import com.nsw.server.entity.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("/info")
    public User getUserInfo() {
        User user = new User();
        user.setId(1L);
        user.setUsername("张三");
        user.setPhone("13812345678"); // 真实手机号
        user.setEmail("zhangsan@example.com");
        return user;
    }
}
```

访问接口后，返回的JSON数据如下：
```json
{
  "id": 1,
  "username": "张三",
  "phone": "138****5678", // 已脱敏
  "email": "zhangsan@example.com"
}
```

### 4.3 边界场景测试
| 输入手机号 | 输出结果 | 说明 |
|------------|----------|------|
| null       | null     | 空值原样返回 |
| ""         | ""       | 空字符串原样返回 |
| "13812345678" | "138****5678" | 合法手机号脱敏 |
| "123456"   | "123456" | 非手机号格式原样返回 |
| "138123456789" | "138123456789" | 长度不符原样返回 |

## 五、扩展与优化

### 5.1 支持更多脱敏规则
如果需要自定义脱敏规则（比如保留前2位、后3位），可以修改序列化器：
```java
// 自定义脱敏逻辑示例：保留前2位，后3位，中间用*填充
String prefix = phone.substring(0, 2);
String suffix = phone.substring(phone.length() - 3);
String desensitizedPhone = prefix + "*****" + suffix;
```

### 5.2 批量脱敏场景
如果需要对整个项目的手机号字段统一脱敏，可结合Spring Boot的配置，实现全局序列化规则，无需逐个字段加注解。

### 5.3 脱敏注解复用
可基于该思路扩展更多脱敏注解，如`@IdCardDesensitization`（身份证脱敏）、`@BankCardDesensitization`（银行卡脱敏）等，只需替换对应的序列化器即可。

## 六、核心优势
1. **侵入性低**：只需添加注解，无需修改业务代码，符合开闭原则
2. **通用性强**：基于Jackson实现，适配所有使用Jackson序列化的场景（Spring Boot默认JSON处理器）
3. **容错性好**：空值、非法格式均做了兼容处理，避免线上异常
4. **易于维护**：脱敏逻辑集中管理，修改时只需调整序列化器，无需逐个修改业务代码

## 总结
本文通过自定义Jackson注解+序列化器的方式，结合Hutool工具类，实现了优雅、通用的手机号脱敏方案。核心要点如下：
1. 利用`@JsonSerialize`注解指定自定义序列化器，实现字段级别的序列化控制
2. 通过Hutool工具类简化手机号校验和脱敏逻辑，提升开发效率
3. 做好空值和异常格式的容错处理，保证代码健壮性
4. 注解化使用方式降低代码侵入性，便于维护和扩展

该方案不仅适用于手机号脱敏，也可扩展到身份证、银行卡等其他敏感信息的脱敏场景，是后端开发中处理敏感数据的最佳实践之一。