企业微信 (WeChat Work) 接入指南

本文档介绍如何将 cc-connect 接入企业微信，让你可以通过企业微信（甚至个人微信）远程调用 Claude Code。

💡 特色功能：配置完成后，个人微信用户也可以直接对话 —— 只需在企业微信管理后台关联微信插件即可。

企业微信支持两种接入模式：

模式	优势	要求
WebSocket 长连接（推荐）	无需公网 URL、无需消息加解密、无需 IP 白名单，支持图片接收与图片回传	创建「智能机器人」
Webhook 回调	兼容企业微信自建应用回调模式	公网 URL + 可信 IP

模式一：WebSocket 长连接（推荐）

企业微信「智能机器人」支持 WebSocket 长连接模式，cc-connect 主动连接企业微信服务器，无需公网 URL、无需消息加解密、无需 IP 白名单，配置最简单。

前置要求

企业微信管理员权限
一台可运行 cc-connect 的服务器（无需公网 IP）
Claude Code 已安装并配置完成

第一步：创建智能机器人

登录企业微信管理后台
进入 应用管理 → 智能机器人 → 创建智能机器人
填写机器人信息（名称、头像等）
创建完成后，记录以下凭证：

BotID:  xxxxxxxxxxxxxxxx
Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Secret 只会显示一次，请立即保存！

第二步：配置 cc-connect

将凭证配置到 config.toml 中：

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/path/to/your/project"
mode = "default"

[[projects.platforms]]
type = "wecom"

[projects.platforms.options]
mode = "websocket"
bot_id = "your-bot-id"
bot_secret = "your-bot-secret"
allow_from = "*"

配置项说明

配置项	必填	说明
`mode`	✅	必须为 `"websocket"`
`bot_id`	✅	智能机器人 BotID
`bot_secret`	✅	智能机器人 Secret
`allow_from`	❌	允许的用户 ID（默认 `"*"` 允许所有）

第三步：启动并验证

cc-connect

你应该看到类似日志：

level=INFO msg="wecom-ws: connecting" endpoint=wss://openws.work.weixin.qq.com
level=INFO msg="wecom-ws: subscribed successfully" bot_id=your-bot-id

在企业微信中找到你的机器人，发送一条消息测试即可。

技术细节

连接地址：wss://openws.work.weixin.qq.com
认证方式：连接后发送 aibot_subscribe（bot_id + secret）
心跳：每 30 秒发送 ping
自动重连：连接断开后指数退避重连（1s → 2s → 4s → ... → 30s max）
图片回传：通过 aibot_upload_media_* 上传临时素材，再用 aibot_send_msg 发送图片
限制：同一机器人仅支持 1 个长连接；30 条/分钟、1000 条/小时

模式二：Webhook 回调

💡 推荐优先使用上方的 WebSocket 长连接模式。只有在你已有企业微信自建应用回调部署、或需要兼容旧配置时，再使用 Webhook 回调模式。

前置要求

企业微信管理员权限
一台可运行 cc-connect 的服务器
公网可访问的 URL（用于接收企业微信回调）
Claude Code 已安装并配置完成

第一步：创建企业微信自建应用

1.1 进入管理后台

登录企业微信管理后台。

1.2 创建应用

进入 应用管理 → 自建 → 创建应用
填写应用信息：

字段	填写建议
应用名称	`cc-connect`
应用Logo	上传一个喜欢的图标
可见范围	选择需要使用的部门/成员

1.3 记录凭证

创建完成后，记录以下信息：

AgentId:  1000002
Secret:   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Secret 只会显示一次，请立即保存！

第二步：获取企业 ID

在管理后台首页，点击 我的企业
在页面底部找到 企业ID (CorpId)
复制保存

CorpId: wwxxxxxxxxxxxxxx

第三步：配置接收消息

3.1 进入消息配置

进入你创建的应用 → 接收消息 → 设置API接收

3.2 填写配置

字段	填写内容
URL	`https://你的公网域名/wecom/callback`（见第四步）
Token	自定义一个随机字符串
EncodingAESKey	点击「随机获取」生成（43 个字符）

⚠️ 暂时不要点保存！ 需要先启动 cc-connect 再回来保存（因为保存时企业微信会立即验证回调 URL）。

3.3 记录配置

把 Token 和 EncodingAESKey 记下来，后面配置 config.toml 要用。

第四步：配置公网访问

企业微信需要能够访问你的回调 URL。推荐方案：

方案 A：cloudflared tunnel（推荐，免费）

# 安装
# macOS: brew install cloudflared
# Linux: 参考 https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/

# 快速启动（会生成一个临时公网 URL）
cloudflared tunnel --url http://localhost:8081

启动后会输出类似 https://xxx-xxx.trycloudflare.com，将其作为回调 URL 的域名。

方案 B：ngrok（开发测试用）

ngrok http 8081

方案 C：有公网 IP 的服务器 + Nginx

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /wecom/callback {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

第五步：配置企业可信 IP

企业微信要求调用 API 的服务器 IP 在白名单中。

5.1 查询服务器出口 IP

curl -s https://ifconfig.me

如果你的出口 IP 是动态的（如家用宽带），可以使用 VPS 正向代理方案，见后文「动态 IP 场景」。

5.2 添加到白名单

进入 应用管理 → 选择你的应用
滚动到底部，找到 企业可信IP
点击配置，添加你的出口 IP

第六步：配置 cc-connect

将凭证配置到 config.toml 中：

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/path/to/your/project"
mode = "default"

[[projects.platforms]]
type = "wecom"

[projects.platforms.options]
corp_id = "wwxxxxxxxxxxxxxx"
corp_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
agent_id = "1000002"
callback_token = "你在第三步设置的Token"
callback_aes_key = "你在第三步获取的EncodingAESKey"
port = "8081"
callback_path = "/wecom/callback"
api_base_url = "https://qyapi.weixin.qq.com"
enable_markdown = false

配置项说明

配置项	必填	说明
`corp_id`	✅	企业 ID
`corp_secret`	✅	应用 Secret
`agent_id`	✅	应用 AgentId
`callback_token`	✅	回调 Token
`callback_aes_key`	✅	回调 EncodingAESKey（43字符）
`port`	❌	Webhook 监听端口（默认 `8081`）
`callback_path`	❌	Webhook 路径（默认 `/wecom/callback`）
`api_base_url`	❌	企业微信 API 基础地址（默认 `https://qyapi.weixin.qq.com`）
`enable_markdown`	❌	是否发送 Markdown 消息（默认 `false`）
`proxy`	❌	HTTP 正向代理地址（动态 IP 场景使用）

关于 enable_markdown

false（默认）：发送纯文本消息，企业微信应用和个人微信都能正常显示
true：发送 Markdown 格式消息，仅企业微信应用内可渲染，个人微信会显示「暂不支持的消息类型」

💡 如果你的用户主要通过个人微信使用，建议保持 false。

第七步：启动并验证

7.1 启动 cc-connect

cc-connect
# 或指定配置文件
cc-connect -config /path/to/config.toml

你应该看到类似日志：

level=INFO msg="platform started" project=my-project platform=wecom
level=INFO msg="cc-connect is running" projects=1
level=INFO msg="wecom: webhook server listening" port=8081 path=/wecom/callback

7.2 确保公网隧道在运行

# 确认 cloudflared / ngrok 正在运行并转发到 8081 端口
cloudflared tunnel --url http://localhost:8081

7.3 回到企业微信保存回调配置

回到企业微信管理后台 → 你的应用 → 接收消息
确认 URL 填写正确（cloudflared 生成的公网 URL + /wecom/callback）
点击保存
如果验证通过，配置完成！

第八步：关联个人微信（可选）

如果希望个人微信也能直接与 AI 对话：

登录企业微信管理后台
进入 我的企业 → 微信插件
用个人微信扫描页面上的二维码
关联后，个人微信中会出现企业微信的应用入口

💡 关联后，个人微信用户可以直接发送消息给应用，无需安装企业微信。

动态 IP 场景

如果你的服务器没有固定公网 IP（如家用宽带），企业微信可信 IP 白名单无法使用动态 IP。解决方案：

使用 VPS 正向代理

在一台有固定公网 IP 的 VPS 上安装 tinyproxy：

# Ubuntu/Debian
apt install tinyproxy

# 编辑配置：允许你的机器访问
vim /etc/tinyproxy/tinyproxy.conf
# 添加: Allow your-home-ip

systemctl restart tinyproxy

在 cc-connect 配置中添加 proxy：

[projects.platforms.options]
# ... 其他配置 ...
proxy = "http://vps-ip:8888"

将 VPS 的公网 IP 添加到企业可信 IP 白名单

这样 cc-connect 调用企业微信 API 时会通过 VPS 代理，出口 IP 固定为 VPS 的 IP。

架构图

┌─────────────────────────────────────────────────────────────┐
│                 企业微信 / 个人微信                            │
│                       服务器                                  │
│                        │                                     │
│                  加密 XML 回调                                │
└────────────────────────┼─────────────────────────────────────┘
                         │
                         │ HTTPS (需要公网 URL)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    你的服务器                                  │
│                                                              │
│   cloudflared ──→ cc-connect ──→ Claude Code CLI             │
│   / ngrok            │                                       │
│                      │ (可选) proxy                          │
│                      ▼                                       │
│                企业微信 API ──→ VPS 正向代理                   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

常见问题

Q: 回调验证失败？

确认 cc-connect 已启动且 webhook server 在监听
确认公网隧道（cloudflared/ngrok）正在运行
检查 URL 是否能公网访问：curl https://你的域名/wecom/callback
检查 Token 和 EncodingAESKey 是否与管理后台一致

Q: 消息发不出去？

检查日志是否有 get access_token failed 错误
确认出口 IP 在企业可信 IP 白名单中
如果使用代理，确认代理服务正常运行

Q: 报错 `60020` (not allow to access from your ip)？

日志中会提示实际的出口 IP，将该 IP 添加到企业可信 IP 白名单。

Q: 个人微信显示「暂不支持的消息类型」？

将 enable_markdown 设为 false（默认值），改为发送纯文本消息。

Q: 动态 IP 导致发送失败？

参考上文「动态 IP 场景」，使用 VPS 正向代理。

Uh oh!

FilesExpand file tree

wecom.md

Latest commit

History

wecom.md

File metadata and controls

企业微信 (WeChat Work) 接入指南

模式一：WebSocket 长连接（推荐）

前置要求

第一步：创建智能机器人

第二步：配置 cc-connect

配置项说明

第三步：启动并验证

技术细节

模式二：Webhook 回调

前置要求

第一步：创建企业微信自建应用

1.1 进入管理后台

1.2 创建应用

1.3 记录凭证

第二步：获取企业 ID

第三步：配置接收消息

3.1 进入消息配置

3.2 填写配置

3.3 记录配置

第四步：配置公网访问

方案 A：cloudflared tunnel（推荐，免费）

方案 B：ngrok（开发测试用）

方案 C：有公网 IP 的服务器 + Nginx

第五步：配置企业可信 IP

5.1 查询服务器出口 IP

5.2 添加到白名单

第六步：配置 cc-connect

配置项说明

关于 enable_markdown

第七步：启动并验证

7.1 启动 cc-connect

7.2 确保公网隧道在运行

7.3 回到企业微信保存回调配置

第八步：关联个人微信（可选）

动态 IP 场景

使用 VPS 正向代理

架构图

常见问题

Q: 回调验证失败？

Q: 消息发不出去？

Q: 报错 60020 (not allow to access from your ip)？

Q: 个人微信显示「暂不支持的消息类型」？

Q: 动态 IP 导致发送失败？

参考链接

下一步

Q: 报错 `60020` (not allow to access from your ip)？