适用场景：让 Claude Code 通过企业微信收发微信消息，支持文字对话、图片识图和任务进度查询

难度：中等，需一台 Linux VPS + 一个企微账号 + Docker 基本操作

耗时：约 2 小时

一、架构总览

微信扫码发消息
    ↓
企微回调 → your.domain.com (:80)
    ↓ nginx 反向代理
VPS 回调服务 (:18909) → 解密/存储消息 → 调用 deepseek-vision 代理 (:8000)
    ↓                                    ↓
企微 API 回复 ← 生成回复              ├── 文字 → DeepSeek / 其他 LLM
                                       └── 图片 → Qwen 识图 → LLM 生成描述

涉及的主机

二、前置准备

三、本地配置

3.1 目录结构

~/.claude/
├── .mcp.json              # MCP 服务器配置
├── settings.json          # 钩子配置
├── cache/
│   └── task-session.json  # 任务状态缓存
└── test/wework-bot/
    ├── server.js           # 本地 MCP 服务器（可选，提供 wework_* 工具）
    ├── wework-client.js    # 企微 API 客户端
    ├── config.json         # 配置
    ├── config.legacy.json  # 企微凭证 ⚠️ 需 gitignore
    ├── server-vps.mjs      # VPS 回调服务（核心）
    ├── wework-poll.sh      # 轮询脚本
    ├── task-status.sh      # 手工任务状态同步
    ├── sync-task-status.py # Stop 钩子自动同步
    └── .gitignore

3.2 MCP 配置 (~/.claude/.mcp.json)

{
  "mcpServers": {
    "wework": {
      "type": "stdio",
      "command": "node",
      "args": ["<你的路径>/test/wework-bot/server.js"],
      "env": {
        "WEWORK_CONFIG": "<你的路径>/test/wework-bot/config.json",
        "WEWORK_LOG_DIR": "<你的路径>/test/wework-bot/logs"
      }
    }
  }
}

⚠️ .mcp.json 必须放在 Claude Code 实际读取的配置目录下。部分环境（如 Windows 软链接目录）可能导致路径不被识别，确认 settings.json 所在目录即为正确位置。

3.3 钩子配置

在 settings.json 中添加：

SessionStart：启动微信轮询

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "bash <你的路径>/test/wework-bot/wework-poll.sh",
        "async": true
      }]
    }]
  }
}

Stop：自动同步任务状态到 VPS

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "python <你的路径>/test/wework-bot/sync-task-status.py"
      }]
    }]
  }
}

四、VPS 部署

4.1 VPS 目录规划

/opt/
├── wecom-callback/         # 回调服务
│   ├── server.mjs          # 主服务（Node.js）
│   ├── config.json         # 凭证 + autoReply 配置 ⚠️ 600 权限
│   ├── merge-tasks.py      # 任务合并脚本
│   ├── task-status.json    # 任务状态数据
│   ├── events.log          # 运行日志
│   └── inbox.jsonl         # 消息收件箱
│
└── deepseek-vision/        # LLM 代理
    ├── .env                # 环境变量 ⚠️ 600 权限
    └── ...

4.2 回调服务 (server.mjs)

核心功能：

服务绑定 127.0.0.1:18909，不直接对外暴露。

完整代码见附录 A。

4.3 deepseek-vision 代理

基于开源项目 ErlichLiu/deepseek-vision 部署，为纯文本 LLM API 补齐视觉理解能力。

部署步骤：

cd /opt
git clone https://github.com/ErlichLiu/deepseek-vision.git
cd deepseek-vision

# ⚠️ 修复 Dockerfile 缺少 README.md 的问题
sed -i 's/^COPY pyproject.toml .\/$/COPY pyproject.toml README.md .\//' Dockerfile

创建 .env（权限 600）：

# 必填
ADMIN_PASSWORD=<你自己设的密码>
MASTER_API_KEY=<客户端访问本代理的 Key>
DEEPSEEK_API_KEY=<你的 DeepSeek Key>

# 视觉识别（去 dashscope.aliyun.com 申请免费 Key）
VISION_API_KEY=<你的 DashScope Key>

# 高级
DEEPSEEK_BASE_URL=https://api.deepseek.com/anthropic
PORT=8000

构建并启动：

docker build -t deepseek-vision .
docker run -d --name deepseek-vision --restart unless-stopped \
  --env-file /opt/deepseek-vision/.env \
  -p 127.0.0.1:8000:8000 deepseek-vision

⚠️ 修改 .env 后必须 docker rm -f deepseek-vision 再 docker run，单纯的 docker restart 不会重读 .env。

4.4 nginx 配置

server {
    listen 80;
    server_name your.domain.com;

    # 企微回调 — 必须公网可达
    location / {
        proxy_pass http://127.0.0.1:18909;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 收件箱/回复/聊天管理 API — 仅本地访问
    location /inbox {
        allow 127.0.0.1;
        deny all;
        proxy_pass http://127.0.0.1:18909;
    }
    location /reply {
        allow 127.0.0.1;
        deny all;
        proxy_pass http://127.0.0.1:18909;
    }
    location /chat {
        allow 127.0.0.1;
        deny all;
        proxy_pass http://127.0.0.1:18909;
    }
}

五、企微后台配置

5.1 创建应用

1. 登录 企业微信管理后台

2. 应用管理 → 创建应用 → 记录 AgentID 和 Secret

3. 记下 企业 ID (corpId)：在「我的企业」→「企业信息」页底部

5.2 API 接收消息

应用详情 → 接收消息 → 设置 API 接收：

三项填写后与 VPS 回调服务 config.json 保持一致即可。保存时企微会发起 URL 验证，服务正常返回即通过。

5.3 微信插件（关键步骤）

路径：管理后台 → 我的企业 → 微信插件（⚠️ 不在应用管理里）

关键设置：

六、VPS 回调服务配置 (config.json)

{
  "token": "<你的 Token>",
  "encodingAESKey": "<你的 EncodingAESKey>",
  "corpId": "<你的企业 ID>",
  "secret": "<你的应用 Secret>",
  "agentId": "<你的 AgentID>",
  "autoReply": {
    "enabled": true,
    "proxyUrl": "http://127.0.0.1:8000/v1/messages",
    "proxyKey": "<MASTER_API_KEY>",
    "model": "deepseek-v4-flash",
    "apiKey": "<你的 DeepSeek Key>",
    "systemPrompt": "你的 System Prompt，定义 AI 的人设和回复风格"
  }
}

七、任务状态同步机制

原理

Claude Code 会话结束
    → Stop 钩子触发
    → sync-task-status.py 读取本地 cache/task-session.json
    → SSH stdin 管道 → VPS merge-tasks.py（按任务名 upsert）
    → task-status.json 原子写入
    → 微信问"进度"时自动注入 AI 上下文

手工同步

bash task-status.sh --add "任务名" "详情"
bash task-status.sh --done "任务名"
bash task-status.sh --list
bash task-status.sh --clear

八、安全措施清单

注意

九、常见问题 & 踩坑记录

9.1 启动/部署相关

9.2 功能相关

9.3 设计决策

十、恢复检查清单

服务挂了按顺序排查：

# 1. VPS 回调服务
ssh root@<你的VPS> "pgrep -f 'node server.mjs'" || echo "需要重启"
# 重启：
ssh root@<你的VPS> "cd /opt/wecom-callback && nohup node server.mjs > /tmp/wecom.log 2>&1 &"

# 2. deepseek-vision 代理
ssh root@<你的VPS> "docker ps | grep deepseek-vision" || echo "需要重启"

# 3. nginx
ssh root@<你的VPS> "systemctl status nginx"

# 4. 公网可达性
curl -s http://your.domain.com/ && echo "OK" || echo "不可达"

# 5. 代理健康检查
ssh root@<你的VPS> "curl -s http://127.0.0.1:8000/health"

附录 A：回调服务核心代码

完整 server.mjs 约 300 行，关键逻辑：

POST / （企微回调）
  → 解密 Encrypt → 解析 XML → 提取消息字段
  → 文本消息 → callAI(历史 + 新消息) → sendReply
  → 图片消息 → downloadImage → callAI(历史 + base64) → sendReply
  → 任务查询检测 → 注入 task-status.json → callAI

GET /inbox/unread → 返回未回复消息
POST /inbox/mark → 标记已回复
POST /reply → 手动回复
POST /chat/clear → 清除某用户对话历史

服务绑定 127.0.0.1:18909，通过 nginx 反向代理暴露企微回调路径（/），其余 API 仅本地可访问。