OpenClaw实战：基于企业微信API打通个人微信的自动化机器人部署指南

1. 项目概述：当企业微信遇上个人微信

最近在折腾一个挺有意思的项目，叫OpenClaw。简单来说，它就像一个“桥梁”或者“翻译官”，能把企业微信和个人微信这两个看似独立的生态给打通。你可能要问了，这俩不都是腾讯家的吗，为啥还需要“打通”？这恰恰是问题的关键所在。企业微信主打的是办公协同，功能设计上更偏向组织管理、流程审批和内部通讯；而个人微信，就是我们每天用来聊天、刷朋友圈、支付的那个App，它的核心是社交和生活。两者在API开放程度、消息处理逻辑、甚至用户身份体系上，都存在巨大的差异。

OpenClaw的出现，就是为了解决一个核心痛点：如何让企业内部的自动化流程、智能机器人，能够触达并服务于使用个人微信的客户、合作伙伴，甚至是员工自己？想象一下，你公司用企业微信做内部管理，但你的客户、供应商、粉丝群全在个人微信里。你想给客户发个订单状态通知，或者用AI机器人自动回答粉丝群的常见问题，传统方式要么靠人工在两个App间切换复制粘贴，效率极低还容易出错；要么就得依赖一些风险极高的第三方“外挂”工具，不仅封号风险大，功能也极不稳定。

OpenClaw的思路很清晰：它通过官方或高度模拟官方的协议，在企业微信端建立一个“机器人”或“应用”。这个机器人可以接收企业微信内的指令或事件（比如有人@它、收到特定关键词、定时任务触发），然后，OpenClaw作为中间件，负责将处理后的结果，通过技术手段发送到指定的个人微信账号上。反过来，它也能监控个人微信的特定消息（如某个群的关键词、私聊信息），将其转化为结构化事件，再触发企业微信端的自动化流程。这样一来，就实现了双向的、可控的、相对安全的信息流转。

这个项目对于需要做私域运营、社群管理、自动化客服、跨平台通知的开发者和运营人员来说，价值非常大。它不再是简单的“消息转发”，而是结合了规则引擎、自然语言处理（对接大模型如Ollama）、任务调度等能力，成为一个功能强大的“微信生态自动化中枢”。接下来，我就结合自己的部署和调试经验，把从环境准备、核心配置到深度定制的全流程拆解清楚。

2. 核心架构与方案选型解析

在动手部署之前，我们必须先理解OpenClaw实现这一功能的几种典型架构，以及为什么我最终选择了某一种方案。这决定了后续部署的复杂度和系统的稳定性。

2.1 主流技术路径对比

目前，实现企业微信与个人微信互联，主要有三种技术路径，各有优劣：

1. 企业微信机器人Webhook + 个人微信协议库模拟

   • 原理：在企业微信群里创建一个“群机器人”，获取它的Webhook地址。OpenClaw部署一个服务，监听这个Webhook的POST请求（即企业微信端的消息）。同时，OpenClaw集成一个像itchat、wxpy（已停止维护）或其替代品的Python库，来登录和控制一个网页版或PC版个人微信客户端，实现消息的收发。
   • 优点：企业微信端实现简单，官方支持，稳定。概念清晰，易于理解。
   • 缺点：个人微信端风险极高。模拟协议的方式非常容易被腾讯检测并封号，尤其是新注册的号或高频操作时。功能受限，无法稳定获取二维码登录，且随着微信客户端更新，协议库需要频繁维护，可靠性差。这是最不推荐的方式，除非用于临时、低频、非核心业务的测试。

2. 企业微信应用API + 微信公众/小程序模板消息（间接）

   • 原理：不直接操作个人微信，而是为个人用户提供一个微信公众号或小程序。用户关注公众号或使用小程序后，可以收到模板消息或客服消息。企业微信应用通过API将消息发送到公众号/小程序后台，再由其推送给用户。
   • 优点：完全合规，零风险。功能强大且稳定，属于微信官方开放生态。
   • 缺点：流程复杂。需要用户主动关注或授权，有额外的开发成本（公众号/小程序开发）。无法实现像普通微信聊天那样的即时、自由的交互体验，消息形式和频率受平台规则限制。更适合做通知，而非双向即时通讯。

3. 企业微信“联系我”/“微信客服”功能 + 自建消息路由（推荐）

   • 原理：这是目前最稳健、最接近需求的方式。利用企业微信的“微信客服”或“联系我”功能，生成一个二维码。个人微信用户扫描后，无需添加好友，即可在企业微信侧以一个“客户”的身份与一个指定的“接待人员”或“机器人应用”发起会话。OpenClaw部署为企业微信的一个“自建应用”，这个应用就充当了那个“接待人员”。所有通过二维码进来的个人微信消息，都会通过企业微信官方API推送到你的OpenClaw应用服务器上。OpenClaw处理完消息后，再通过企业微信API回复给这个“客户”，消息就会自动出现在用户的个人微信聊天窗口中。
   • 优点：官方合规通道，彻底杜绝封号风险。用户体验好，用户感觉就是在和一个普通的微信用户/客服聊天。功能完整，支持文字、图片、文件、菜单等。企业微信API丰富且稳定。
   • 缺点：需要企业微信认证（部分高级功能需要）。消息需要通过企业微信服务器中转，有轻微的延迟（通常毫秒级）。配置步骤稍多。

核心决策：基于稳定性、安全性和长期可维护性的考虑，方案3（企业微信应用API + 微信客服通道）是生产环境的首选。下文的所有实操也将围绕此方案展开。OpenClaw在这个方案中，主要扮演了“企业微信自建应用的消息处理中枢”角色，它可以对接AI大模型、数据库、业务系统，实现智能回复。

2.2 OpenClaw在此架构中的角色

明确了方案，我们再看看OpenClaw具体做什么。它不再需要去“ hack”个人微信，而是专注于：

• 接收：通过配置好的企业微信应用API接收器（Receiver），获取从个人微信用户经由企业微信客服通道发来的消息。
• 处理：消息进入OpenClaw的规则引擎。你可以配置技能（Skill），例如：关键词匹配、调用Ollama本地大模型进行对话、查询天气、执行命令等。
• 响应：处理完成后，通过企业微信应用的发送器（Sender），将回复内容传回企业微信服务器，最终显示在用户的个人微信里。

这样一来，技术风险全部转移到了企业微信API的合规使用上，而这是腾讯鼓励的方式。我们的工作就从“如何稳定控制一个微信客户端”变成了“如何开发一个高效的企业微信应用”，后者有完善的文档和社区支持。

3. 环境准备与基础部署

理论清晰后，我们进入实战。我选择在Ubuntu 22.04 LTS服务器上使用Docker部署OpenClaw，这是最干净、最便于管理和迁移的方式。

3.1 系统与依赖准备

首先，确保你的服务器满足基本要求：

# 更新系统包 sudo apt update && sudo apt upgrade -y # 安装Docker和Docker Compose插件 sudo apt install -y docker.io sudo systemctl start docker sudo systemctl enable docker # 安装Docker Compose插件（推荐方式，而非独立二进制文件） sudo apt install -y docker-compose-plugin # 验证安装 docker compose version

如果你的服务器在国内，为了提高拉取镜像的速度，可以配置Docker镜像加速器。这里以阿里云加速器为例（需替换为你自己的加速器地址）：

sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json <<-'EOF' { "registry-mirrors": ["https://your-mirror.mirror.aliyuncs.com"] } EOF sudo systemctl daemon-reload sudo systemctl restart docker

3.2 获取与配置OpenClaw

OpenClaw的Docker镜像通常来自Docker Hub或GitHub Container Registry。这里我们使用一个社区维护的镜像。

1. 创建项目目录并下载配置文件：

   mkdir -p ~/openclaw && cd ~/openclaw # 假设从官方GitHub仓库获取docker-compose示例文件 # 如果没有，我们可以手动创建

2. 编写docker-compose.yml文件： 这是部署的核心。下面是一个基础版本的配置，集成了OpenClaw和Ollama（用于本地大模型对话）。

   version: '3.8' services: openclaw: image: somecommunity/openclaw:latest # 请替换为实际可用的镜像名 container_name: openclaw restart: unless-stopped ports: - "8080:8080" # OpenClaw管理后台端口 environment: - TZ=Asia/Shanghai - OPENCLAW_API_KEY=your_super_secret_key_here # 用于API调用的密钥 - OPENCLAW_LOG_LEVEL=INFO volumes: - ./openclaw_data:/app/data # 持久化配置和数据 - ./config.yaml:/app/config.yaml:ro # 挂载外部配置文件 depends_on: - ollama networks: - openclaw-net ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped ports: - "11434:11434" # Ollama API端口 volumes: - ./ollama_data:/root/.ollama # 持久化模型数据 networks: - openclaw-net networks: openclaw-net: driver: bridge

   注意：镜像名somecommunity/openclaw:latest是一个占位符。由于OpenClaw的官方镜像可能变化，你需要根据最新的项目文档或社区推荐，替换为真实的镜像地址。例如可能是ghcr.io/openclaw/openclaw:latest。务必在部署前确认。

3. 编写基础的OpenClaw配置文件config.yaml： 这个文件定义了OpenClaw的核心行为，包括接收器、技能、发送器。我们先创建一个最小化版本，后续再添加企业微信的详细配置。

   # ~/openclaw/config.yaml log: level: INFO file: /app/data/openclaw.log server: host: 0.0.0.0 port: 8080 # 技能定义 - 后续会详细扩展 skills: [] # 接收器定义 - 后续添加企业微信接收器 receivers: [] # 发送器定义 - 后续添加企业微信发送器 senders: []

4. 启动服务：

   cd ~/openclaw docker compose up -d

   使用docker compose logs -f openclaw查看启动日志，确认没有报错。访问http://你的服务器IP:8080应该能看到OpenClaw的管理界面（如果镜像提供了的话）或健康检查页面。

3.3 配置Ollama本地大模型

OpenClaw的智能回复能力很大程度上依赖于对接的大模型。Ollama让我们能在本地运行如Llama 3、Qwen等开源模型。

1. 进入Ollama容器并拉取模型：

   docker exec -it ollama ollama pull qwen2.5:7b-instruct # 以通义千问2.5 7B模型为例

   这个过程会下载模型文件，耗时取决于你的网络和模型大小（7B模型约4-5GB）。你也可以选择更小的模型如llama3.2:3b或qwen2.5:0.5b进行快速测试。

2. 测试Ollama API：

   curl http://localhost:11434/api/generate -d '{ "model": "qwen2.5:7b-instruct", "prompt": "你好，请介绍一下你自己。", "stream": false }'

   如果返回一段JSON格式的文本回答，说明Ollama运行正常。

至此，我们的基础环境和一个“大脑”（Ollama）已经就绪。接下来就是最关键的一步：让OpenClaw接入企业微信。

4. 企业微信侧配置详解

这是整个流程中最需要细心的一环，任何一步配置错误都会导致消息无法收发。请严格按照以下步骤操作。

4.1 创建企业微信自建应用

1. 登录企业微信管理后台：使用你的企业微信管理员账号登录。
2. 进入“应用管理” -> “自建应用” -> “创建应用”。
   • 应用名称：填写一个易于识别的名字，例如“智能客服助手”。
   • 应用Logo：上传一个图标。
   • 可见范围：选择能管理此应用的企业成员（至少包括你自己）。点击“创建”。
3. 获取关键凭证：
   • 创建成功后，进入应用详情页。
   • 记录AgentId（应用ID）和Secret（应用密钥）。Secret非常重要，点击“查看”后需立即保存，它只显示一次。
   • 记录企业ID（CorpID）：在管理后台的“我的企业” -> “企业信息”页面最下方可以找到。

这三个参数（CorpID,AgentId,Secret）是OpenClaw与企业微信通信的“身份证”，下面配置会用到。

4.2 配置企业微信“微信客服”功能（核心）

为了让个人微信用户能联系到这个应用，我们需要启用“微信客服”。

1. 在管理后台找到“微信客服”：通常在“客户联系”或单独的一级菜单里。
2. 配置“客服账号”：
   • 点击“添加客服账号”。
   • 填写账号名称（用户将在个人微信中看到的名字）、头像等。
   • 在“接待人员”或“关联应用”处，选择我们刚刚创建的“智能客服助手”应用。这意味着所有发给这个客服账号的消息，都会推送到我们的自建应用。
3. 获取客服链接或二维码：
   • 配置完成后，你会获得一个专属的客服链接和一个二维码。
   • 这个二维码就是入口。任何个人微信用户扫描这个二维码，就会在微信中打开一个临时会话窗口，窗口标题就是你设置的客服账号名称。用户在此发送的消息，都会流向你的OpenClaw应用。

4.3 配置API接收权限与服务器

企业微信需要知道把消息推送到哪里。

1. 进入自建应用详情页，找到“接收消息”或“开发者接口”设置。
2. 配置API接收：
   • 点击“设置API接收”。
   • URL：填写你的OpenClaw服务暴露给公网的地址，并加上企业微信回调的路径。例如：https://your-domain.com/openclaw/callback/wecom。注意：必须是HTTPS，且端口为443（或你做了反向代理）。本地测试可以用内网穿透工具（如ngrok、frp）生成一个临时HTTPS地址。
   • Token：自定义一个字符串，用于生成签名，例如YourWeComToken。
   • EncodingAESKey：点击“随机生成”即可，用于消息加解密。
   • 填写后先不要点击保存。
3. 在OpenClaw中验证URL：
   • 企业微信要求你在保存配置前，提供一个能响应GET请求并完成签名验证的接口。这意味着我们需要先在OpenClaw的配置中，把企业微信接收器（Receiver）配置好并启动，让这个URL端点生效。
   • 这引出了“先有鸡还是先有蛋”的问题。我们的策略是：先完成OpenClaw侧的配置并确保服务运行，再用临时HTTPS地址让企业微信完成验证，最后将验证通过的URL更新为正式地址。

5. OpenClaw核心配置实战

现在，我们来深入配置OpenClaw的config.yaml，让它具备接收、处理和回复企业微信消息的能力。

5.1 配置企业微信接收器（Receiver）

接收器负责监听企业微信服务器推送过来的消息。在config.yaml的receivers:部分添加：

receivers: - name: wecom_receiver # 接收器名称，自定义 type: wecom # 类型指定为企业微信 config: corp_id: "wwyourcorpid123" # 替换为你的企业ID agent_id: 1000002 # 替换为你的应用AgentId secret: "your_app_secret_here" # 替换为你的应用Secret token: "YourWeComToken" # 必须与企业管理后台设置的Token一致 aes_key: "YourEncodingAESKey" # 必须与企业管理后台设置的EncodingAESKey一致 endpoint: "/openclaw/callback/wecom" # 接收消息的URL路径，与后台配置的URL后缀一致 # 注意：后台配置的完整URL是 `https://your-domain.com` + `endpoint`

关键点解析：

• corp_id,agent_id,secret：用于OpenClaw主动调用企业微信API（如发送消息、获取用户信息）时的身份认证。
• token,aes_key：用于验证企业微信服务器发来的请求是否合法，并对消息进行解密。必须与管理后台设置完全一致。
• endpoint：这是OpenClaw内部路由。当企业微信向你的服务器https://your-server.com/openclaw/callback/wecom发送POST请求时，OpenClaw会根据这个endpoint将其路由到这个接收器处理。

5.2 配置企业微信发送器（Sender）

发送器负责将处理好的消息内容，通过企业微信API发送回去。在senders:部分添加：

senders: - name: wecom_sender # 发送器名称，自定义 type: wecom # 类型指定为企业微信 config: corp_id: "wwyourcorpid123" # 同上 agent_id: 1000002 # 同上 secret: "your_app_secret_here" # 同上 # 通常，发送器和接收器使用同一套凭证，因为它们操作的是同一个应用

5.3 配置核心技能（Skill）—— 对接Ollama

技能是OpenClaw的“大脑”，定义了收到消息后做什么。我们配置一个最基本的技能：将所有用户消息转发给Ollama大模型，并将回复返回。

skills: - name: ollama_chat_skill type: llm # 技能类型为大型语言模型 config: model: "qwen2.5:7b-instruct" # 与Ollama中拉取的模型名一致 base_url: "http://ollama:11434" # 注意：这里用的是Docker服务名`ollama`，因为在同一网络内 api_key: "none" # Ollama默认无需API Key prompt_template: | 你是一个专业的助理，负责通过企业微信与用户对话。 用户信息：{{sender_name}} (ID: {{sender_id}}) 当前时间：{{current_time}} 历史对话： {{chat_history}} 用户最新消息：{{query}} 请用友好、专业的语气回复用户： max_history: 6 # 保留最近6轮对话作为上下文 temperature: 0.7 triggers: - type: message # 触发类型为消息 receiver: wecom_receiver # 指定由哪个接收器来的消息触发此技能 # 可以在这里添加更精细的触发条件，例如匹配关键词 # condition: "{{message}} contains '帮助'" actions: - type: reply # 执行回复动作 sender: wecom_sender # 使用哪个发送器回复 config: # 可以在这里定义回复消息的格式，默认使用技能返回的文本

配置逻辑链：

1. 触发：当wecom_receiver收到一条个人微信用户发来的消息。
2. 处理：消息被传递给ollama_chat_skill。该技能将消息内容、用户信息、对话历史等填充到prompt_template中，形成完整的提示词，发送给http://ollama:11434的API。
3. 响应：Ollama返回生成的回复文本。技能执行reply动作，调用wecom_sender，将回复文本通过企业微信API发送给对应的用户。

5.4 完成配置并重启服务

将更新后的config.yaml覆盖到容器内，然后重启OpenClaw服务。

# 确保配置文件在正确位置 cp ~/openclaw/config.yaml ~/openclaw/config.yaml.bak # 备份 # 用你编辑好的内容替换 ~/openclaw/config.yaml # 重启OpenClaw容器使配置生效 docker compose restart openclaw # 查看日志，确认配置加载无误，无报错 docker compose logs -f openclaw

在日志中，你应该能看到类似Loaded receiver 'wecom_receiver'，Loaded skill 'ollama_chat_skill'，Loaded sender 'wecom_sender'的信息。

6. 验证与调试全流程

配置完成后，必须进行端到端的验证。这是排查问题最关键的一步。

6.1 第一步：验证OpenClaw回调URL可达性

由于企业微信要求HTTPS，我们假设你已经有了一个域名your-domain.com并配置了SSL证书，且通过Nginx等反向代理将https://your-domain.com/openclaw/callback/wecom代理到了内网OpenClaw容器的8080端口。

你可以先用curl命令模拟企业微信的验证请求（GET方法）：

# 这只是一个本地测试，验证OpenClaw内部路由是否工作。真正的验证需要企业微信服务器发起。 curl -X GET "http://localhost:8080/openclaw/callback/wecom"

如果返回Invalid request或类似提示，说明路由是通的，只是在等正确的签名参数。这算初步成功。

6.2 第二步：完成企业微信服务器验证

1. 确保你的OpenClaw服务正在运行，且公网URL可访问。
2. 回到企业微信管理后台自建应用的“接收消息”设置页面。
3. 将URL、Token、EncodingAESKey填写进去，然后点击“保存”。
4. 此时，企业微信服务器会立即向你的URL发送一个携带特定参数的GET请求进行验证。
5. 观察OpenClaw日志：如果配置正确，OpenClaw会成功处理这个验证请求，并在日志中打印WeCom verification successful之类的信息。同时，管理后台的“保存”按钮会变成灰色，并显示“验证成功”。
6. 如果验证失败，后台会提示“Token验证失败”等错误。请仔细核对：
   • config.yaml中的token、aes_key是否与后台完全一致（包括大小写、无多余空格）。
   • 网络是否通畅，防火墙/安全组是否开放了443端口。
   • Nginx反向代理配置是否正确，请求是否被正确转发到了OpenClaw的8080端口。

6.3 第三步：端到端消息测试

验证通过后，就可以进行真正的消息测试了。

1. 打开个人微信，扫描之前“微信客服”生成的二维码。
2. 扫描后，微信里会打开一个与“客服账号”的聊天窗口。
3. 发送一条消息，比如“你好”。
4. 观察OpenClaw日志：你应该能看到详细的日志，例如：

   [INFO] Received message from WeCom: sender_id=xxx, content=你好 [INFO] Skill 'ollama_chat_skill' triggered. [INFO] Calling LLM API at http://ollama:11434... [INFO] LLM response: 你好！我是你的智能助理，很高兴为你服务。 [INFO] Sending reply via wecom_sender to user xxx.

5. 检查个人微信：稍等片刻（时间取决于模型推理速度），你应该能收到AI助理的回复。

如果收不到回复，按以下顺序排查：

• 看OpenClaw日志：有没有收到消息？技能是否触发？LLM调用是否成功？发送器是否执行？
• 看Ollama日志：docker compose logs -f ollama，看是否有收到请求并生成回复。
• 检查企业微信应用权限：确保应用已“启用”，并且“微信客服”账号确实关联了该应用。
• 检查网络：确保OpenClaw容器能访问ollama:11434（内部网络），以及OpenClaw服务器能访问企业微信的API域名（qyapi.weixin.qq.com）。

7. 高级配置与玩法拓展

基础通路打通后，OpenClaw的真正威力在于其灵活的规则引擎和技能组合。下面分享几个进阶玩法。

7.1 多技能路由与优先级

你不可能让所有消息都走大模型，那样成本高、响应慢。需要根据消息内容路由到不同的技能。

skills: - name: help_skill type: command config: commands: - keyword: "帮助" response: "我是智能助手，你可以问我问题，或输入以下关键词：\n- 帮助：查看此信息\n- 时间：查看当前时间\n- 天气 [城市]：查询天气" triggers: - type: message receiver: wecom_receiver condition: "{{message}} contains '帮助'" actions: - type: reply sender: wecom_sender - name: time_skill type: script # 脚本类型技能 config: script: | import datetime current_time = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S") return f"当前时间是：{current_time}" triggers: - type: message receiver: wecom_receiver condition: "{{message}} contains '时间'" actions: - type: reply sender: wecom_sender - name: ollama_chat_skill type: llm config: model: "qwen2.5:7b-instruct" base_url: "http://ollama:11434" triggers: - type: message receiver: wecom_receiver # 默认技能，当以上技能都不匹配时触发 condition: "true" actions: - type: reply sender: wecom_sender

配置解析：这里定义了三个技能，并按顺序匹配。当用户消息包含“帮助”时，由help_skill直接回复固定文本；包含“时间”时，由time_skill执行Python脚本返回时间；其他所有消息（condition: "true"）才交给ollama_chat_skill处理。技能的顺序很重要，OpenClaw会按定义顺序匹配第一个触发条件为真的技能。

7.2 对接多个大模型与模型路由

如果你的Ollama部署了多个模型，可以根据不同场景调用。

skills: - name: general_chat_skill type: llm config: model: "qwen2.5:7b-instruct" # 通用对话模型 base_url: "http://ollama:11434" triggers: - type: message receiver: wecom_receiver condition: "not ({{message}} contains '代码')" actions: [...] - name: code_skill type: llm config: model: "codellama:7b" # 代码专用模型 base_url: "http://ollama:11434" prompt_template: "你是一个编程专家，请回答以下代码问题：{{query}}" triggers: - type: message receiver: wecom_receiver condition: "{{message}} contains '代码'" actions: [...]

7.3 状态保持与上下文管理

在llm类型技能中，max_history参数用于控制上下文长度。OpenClaw会自动维护一个与每个用户（sender_id）的对话历史记录。但需要注意，历史记录是保存在内存中的，服务重启会丢失。对于生产环境，你需要配置持久化存储，或者使用技能配置中的context字段结合外部数据库（如Redis）来管理更复杂的状态。

7.4 安全加固与限流

• API密钥保护：确保config.yaml中的secret等敏感信息不被泄露。可以考虑使用环境变量注入，而不是明文写在文件里。在docker-compose.yml中：

  environment: - WECOM_SECRET=${WECOM_SECRET} # 从外部环境变量读取

  然后在.env文件中定义WECOM_SECRET=your_secret，并确保.env文件不被提交到版本库。
• 网络隔离：将OpenClaw、Ollama等服务放在独立的Docker网络内，不暴露不必要的端口到公网。只将OpenClaw的8080端口通过Nginx反向代理（HTTPS）暴露。
• 请求限流：在企业微信应用管理后台，可以设置“API接收消息”的IP白名单，只允许你的服务器IP调用。此外，可以在Nginx层面配置请求频率限制，防止恶意调用。

8. 常见问题与故障排查实录

在实际部署和运行中，我踩过不少坑。这里把典型问题和解决方案整理出来，希望能帮你节省时间。

8.1 企业微信回调验证失败

• 问题：在企业微信后台保存回调配置时，始终提示“Token验证失败”或“URL请求超时”。
• 排查：
  1. 检查三要素：Token，EncodingAESKey，URL。必须保证OpenClaw配置config.yaml中的token和aes_key与后台填写的一字不差，包括首尾空格。
  2. 检查URL可访问性：用浏览器或curl访问你填写的URL（带上?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx之类的参数可能不行），至少应返回一个错误页面而不是“连接拒绝”。确保是HTTPS且端口正确。
  3. 检查网络路径：企业微信服务器需要能访问到你的URL。如果你用的是家庭宽带，大概率没有公网IP，必须使用内网穿透工具（如frp、ngrok）提供一个临时的HTTPS地址用于验证。验证通过后，再换成正式的服务器地址。
  4. 查看OpenClaw日志：这是最重要的信息源。验证请求到来时，OpenClaw会打印相关日志。如果没看到日志，说明请求根本没到OpenClaw，问题出在网络或反向代理。

8.2 能收到消息但无法回复

• 问题：个人微信发送消息后，OpenClaw日志显示收到了消息并触发了技能，但用户收不到回复。
• 排查：
  1. 检查发送器日志：OpenClaw日志中，在技能执行后，应该有一行关于调用wecom_sender的记录。如果没有，检查技能的actions配置是否正确关联了sender。
  2. 检查企业微信API调用权限：确保自建应用的“权限”中，“企业微信授权登录”和“微信客服”等相关权限已经开启。特别是“发送消息到微信客服”这个权限。
  3. 检查corp_id,agent_id,secret：发送消息需要这些凭证。确保它们在sender配置中正确，且secret未过期（企业微信Secret有可能重置）。
  4. 检查接收消息与发送消息的AgentId是否一致：接收消息用的是你配置的agent_id，发送也必须用同一个应用的agent_id，不能混用。
  5. 测试主动发送：你可以写一个简单的Python脚本，使用相同的corp_id,secret,agent_id，调用企业微信“发送消息”API，看是否能成功。这可以隔离OpenClaw的问题。

8.3 Ollama调用超时或无响应

• 问题：OpenClaw日志显示调用http://ollama:11434超时，或者返回错误。
• 排查：
  1. 检查容器网络：确保OpenClaw和Ollama在同一个Docker网络（openclaw-net）内。进入OpenClaw容器测试连通性：

     docker exec -it openclaw ping ollama

  2. 检查Ollama服务状态：docker compose logs ollama查看Ollama是否正常启动，模型是否加载。
  3. 手动测试Ollama API：在OpenClaw容器内或宿主机上，用curl命令模拟OpenClaw的请求，看Ollama是否正常响应。
  4. 模型名称：确保config.yaml中model的名字与Ollama中拉取的模型名完全一致（包括标签，如:7b-instruct）。

8.4 个人微信收不到客服二维码或扫码后无反应

• 问题：在企业微信后台生成了客服二维码，但个人微信扫描后没反应，或提示“已停止访问该网页”。
• 排查：
  1. 企业微信未认证：只有认证过的企业微信，其“微信客服”功能生成的二维码才能被所有个人微信用户扫描。未认证企业，只有企业通讯录内的成员才能扫描成功。这是最常见的原因。
  2. 客服账号未启用：检查客服账号是否处于“启用”状态。
  3. 关联应用未启用：检查客服账号关联的自建应用是否已“启用”。

8.5 消息延迟高

• 问题：从发送消息到收到回复，耗时超过10秒甚至更长。
• 优化：
  1. 模型大小：Ollama模型越大，推理越慢。在满足需求的前提下，选择更小的模型（如3B、1.5B甚至0.5B）。
  2. 硬件加速：确保服务器有足够的CPU和内存。如果有可能，使用带GPU的服务器，并在Ollama启动时指定GPU层数（如OLLAMA_NUM_GPU=2）。
  3. 技能路由：如7.1节所述，用简单的命令或脚本技能处理高频、固定问答，避免所有请求都走大模型。
  4. 提示词优化：精简prompt_template，移除不必要的上下文，可以缩短推理时间。

整个配置过程就像搭积木，每一步都要严丝合缝。从企业微信的创建、应用配置、API权限，到OpenClaw的Docker部署、YAML文件编写、技能定义，再到最后的联调测试，任何一个环节的疏漏都会导致失败。但一旦跑通，你会发现这套基于官方API的方案异常稳定，为你的自动化工作流打开了一扇新的大门。你可以在此基础上，集成更多的技能，比如连接数据库查询订单、调用外部API获取天气、甚至控制智能家居，让这个“桥梁”变得无比强大。