企业微信ClawBot全链路部署详细过程

企业微信 ClawBot 全链路部署详细过程

目标：把自研的 AI 聊天机器人（ClawBot）接入企业微信，让员工可以在企业微信里跟 AI 对话。

核心问题：企业微信要求回调地址必须是「已备案的企业域名 + HTTPS」，不能直接用 IP 或内网地址。

⚠️ 本文所有 IP、域名、API Key 均为示例，请替换为你自己的实际信息。

---

一、整体架构

你发消息 → 企业微信服务器 → 你的备案域名(your-domain.com)↓Nginx (反向代理)↓ClawBot (FastAPI + DeepSeek AI)↓回复 → 企业微信 → 你

为什么需要这些组件？

组件	为什么需要
备案域名 (your-domain.com)	企业微信强制要求，不能用 IP
Nginx	负责 HTTPS 加密 + 把请求转发给后端程序
ClawBot	你写的 Python 程序，处理消息并调用 AI
DeepSeek API	AI 大脑，真正理解并回复消息

---

二、云服务器准备

2.1 购买腾讯云轻量服务器

为什么需要服务器？ 你的 ClawBot 程序需要 24 小时在线运行，不能用你家里的电脑（断电断网就没了）。

在腾讯云买一台轻量应用服务器（最低配 2核2G 就行），系统选 Ubuntu 24.04。

2.2 配置安全组（防火墙）

腾讯云有层额外的防火墙叫「安全组」，默认只开了 22 端口（SSH 登录用）。

需要手动开放：

端口	用途
80	HTTP（用于 Let's Encrypt 验证域名）
443	HTTPS（企业微信要求加密通信）

操作路径：腾讯云控制台 → 你的服务器 → 防火墙 → 添加规则

2.3 SSH 密钥登录

# 在本地电脑生成密钥对
ssh-keygen -t ed25519 -f ~/.ssh/clawbot_deploy# 把公钥内容加到服务器的 ~/.ssh/authorized_keys 里
# 这样后面可以用 ssh -i 密钥 登录

---

三、域名配置

3.1 为什么需要域名？

企业微信回调地址不能是 IP（如 http://YOUR_SERVER_IP/xxx），必须是域名。而且这个域名必须：

• 做了 ICP 备案（中国大陆法规要求）
• 能解析到你的服务器 IP

3.2 购买 + 备案

在腾讯云买域名（your-domain.com，1元/年），然后提交 ICP 备案申请（1-20天）。

3.3 DNS 解析

备案通过后，去腾讯云 DNSPod 添加一条 A 记录：

记录类型: A
主机记录: @
记录值: YOUR_SERVER_IP  (你的服务器公网IP)
TTL: 600

这样别人访问 your-domain.com 就会找到你的服务器。

---

四、部署 ClawBot

4.1 项目结构

clawbot/
├── app/
│   ├── main.py          # FastAPI 入口
│   ├── config.py        # 配置管理
│   ├── channel/
│   │   └── wecom.py     # 企业微信回调处理
│   ├── agent/
│   │   ├── engine.py    # AI 对话引擎
│   │   ├── prompts.py   # AI 人设 Prompt
│   │   └── tools.py     # AI 可用工具定义
│   ├── storage/         # 数据库
│   ├── scheduler/       # 定时任务
│   └── webui/           # 管理后台
├── run.py               # 启动文件
├── .env                 # 配置文件（API Key等敏感信息）
└── requirements.txt     # Python 依赖

4.2 上传代码到服务器

scp -r clawbot/* ubuntu@YOUR_SERVER_IP:~/clawbot/

4.3 安装 Python 依赖

cd ~/clawbot
python3 -m venv venv               # 创建虚拟环境（隔离 Python 包）
source venv/bin/activate            # 激活虚拟环境
pip install -r requirements.txt     # 安装所有依赖

为什么用虚拟环境？ 不同项目可能需要不同版本的 Python 包，虚拟环境让它们互不干扰。

4.4 配置 .env 文件

.env 存放所有敏感配置，相当于程序的「钥匙串」：

# AI 模型 (ClawBot 的大脑)
LLM_API_KEY=YOUR_DEEPSEEK_API_KEY
LLM_BASE_URL=https://api.deepseek.com/anthropic  # DeepSeek 的 Anthropic 兼容接口
LLM_MODEL=deepseek-v4-pro# 企业微信应用配置
WECOM_CORP_ID=YOUR_CORP_ID      # 企业 ID（以 ww 开头）
WECOM_AGENT_SECRET=YOUR_AGENT_SECRET  # 应用 Secret
WECOM_AGENT_ID=YOUR_AGENT_ID     # 应用 AgentID
WECOM_TOKEN=YOUR_CALLBACK_TOKEN  # 回调 Token（自己定，3-32位字符）
WECOM_ENCODING_AES_KEY=YOUR_AES_KEY  # 回调加密 Key（43位）# 服务
HOST=0.0.0.0                  # 监听所有网卡（让 Nginx 能访问）
PORT=8000

4.5 配置 Nginx 反向代理

Nginx 是什么？ 一个高性能的 Web 服务器，这里用它做两件事：

1. HTTPS 加密 — 让通信安全
2. 反向代理 — 把外部请求转发给 ClawBot（跑在 8000 端口）

创建 /etc/nginx/sites-available/clawbot：

server {listen 80;server_name your-domain.com;location / {proxy_pass http://127.0.0.1:8000;  # 转发到 ClawBotproxy_set_header Host $host;}location /wecom/ {proxy_pass http://127.0.0.1:8000;proxy_set_header Host $host;proxy_buffering off;  # 企业微信回调需要实时响应}
}

然后启用：

sudo ln -s /etc/nginx/sites-available/clawbot /etc/nginx/sites-enabled/
sudo nginx -t         # 测试配置是否正确
sudo systemctl reload nginx  # 重载配置

4.6 配置 HTTPS（SSL 证书）

用 Certbot 免费申请 Let's Encrypt 证书（有效期3个月，自动续期）：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

执行后 Certbot 会自动：

1. 验证你对域名的控制权（访问 http://your-domain.com/.well-known/...）
2. 申请证书
3. 自动修改 Nginx 配置加上 SSL

Nginx 配置会变成：

server {listen 443 ssl;server_name your-domain.com;ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;# ... 原来配置不变
}server {listen 80;server_name your-domain.com;return 301 https://$host$request_uri;  # HTTP 自动跳转 HTTPS
}

4.7 配置 systemd 开机自启

为什么需要？ 服务器重启后，ClawBot 程序要自动跑起来，不能每次手动启动。

创建 /etc/systemd/system/clawbot.service：

[Unit]
Description=ClawBot - AI 研究助手
After=network.target[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/clawbot
ExecStart=/home/ubuntu/clawbot/venv/bin/python run.py
Restart=always        # 挂了自动重启
RestartSec=5[Install]
WantedBy=multi-user.target

启动并启用：

sudo systemctl enable clawbot   # 开机自启
sudo systemctl start clawbot    # 立即启动
sudo systemctl status clawbot   # 查看状态

---

五、企业微信配置

5.1 创建自建应用

登录 企业微信管理后台 → 应用管理 → 自建 → 创建应用

创建后会拿到：

• AgentID（应用编号）
• Secret（应用密码，调用企业微信 API 用）

5.2 配置回调地址

在企业微信管理后台 → 你的应用 → 接收消息 → 设置接收消息

填写：

字段	值
URL	https://your-domain.com/wecom/callback
Token	跟 .env 里的 WECOM_TOKEN 一致
EncodingAESKey	跟 .env 里的 WECOM_ENCODING_AES_KEY 一致

点击保存时，企业微信会发一个 GET 请求到你的 URL 做验证：

https://your-domain.com/wecom/callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx

ClawBot 的 wecom.py 里用 WeChatCrypto.check_signature() 验证签名 → 解密 echostr → 返回解密后的字符串 → 验证通过。

5.3 添加 IP 白名单

企业微信限制了哪些 IP 可以调用它的 API 发消息。你的服务器 IP 必须加进去：

应用管理 → 你的应用 → 企业可信IP → 添加 YOUR_SERVER_IP

如果不加，ClawBot 能收到消息但发不出去，会报错：

Error code: 60020 - not allow to access from your ip

---

六、完整数据流

你在企业微信发：你好│▼
企业微信服务器收到消息│ 根据回调 URL 配置，把消息加密后 POST 到▼
https://your-domain.com/wecom/callback?msg_signature=xxx&timestamp=xxx&nonce=xxx│▼
Nginx (443端口) → 转发到 127.0.0.1:8000│▼
ClawBot (wecom.py)│ 1. 用 WeChatCrypto.decrypt_message() 解密消息│ 2. 解析 XML，取出用户ID和消息内容│ 3. 把消息存入 SQLite 数据库│ 4. 调用 AI 引擎处理▼
AI 引擎 (engine.py)│ 1. 组装消息为 DeepSeek API 格式│ 2. 调用 https://api.deepseek.com/chat/completions│ 3. DeepSeek 返回回复文本▼
ClawBot 收到回复│ 1. 把回复存入数据库│ 2. 调用企业微信 API 发消息给用户▼
企业微信服务器 → 你手机 → 弹窗显示回复

---

七、遇到的问题 & 解决方案

问题	原因	解决
本地电脑没有公网 IP	家庭宽带没有固定公网 IP	部署到腾讯云服务器
企业微信回调验证失败	ngrok/cpolar 域名不是企业主体	购买备案域名 your-domain.com
HTTPS 证书	需要加密通信	Let's Encrypt 免费证书
DeepSeek API 403 拒绝	API Key 错误或过期	换新 Key
搜索失败	DuckDuckGo 从国内无法访问	改用 Bing 搜索
消息发送失败 60020	服务器 IP 不在白名单	企业微信后台添加可信 IP
回复格式显示 ## 等符号	企业微信不渲染 Markdown	改用纯文本 + emoji 格式

---

总结：整个部署的核心就是搞明白「消息怎么从用户手机出发，经过哪些环节，到达 AI，再返回」这条链路。每个环节都有特定的要求（域名要备案、通信要加密、IP 要白名单），一个一个满足就行了。