WeClaw：无缝集成AI智能体到微信，打造高效技术沟通流

1. 项目概述与核心价值

如果你和我一样，经常在微信上和朋友、同事讨论技术问题，或者需要快速处理一些代码片段、文档草稿，那么来回切换微信和AI工具（比如Claude、Codex、Kimi）的过程就非常割裂。要么得把聊天记录里的代码复制到AI工具的网页或客户端，要么得把AI生成的结果再手动粘贴回微信，效率很低。WeClaw这个项目就是为了解决这个痛点而生的。它本质上是一个“桥梁”，一个运行在你电脑上的后台服务，能够将你的微信账号与本地安装的各类AI智能体（Agent）无缝连接起来。

简单来说，WeClaw让你可以在微信聊天窗口里，直接与Claude、Codex、Gemini等AI对话。你发一段代码过去，AI的回复会直接出现在微信里；AI生成的图片，也能直接以微信图片的形式发回来。它支持多种连接模式，从最高效的长连接进程到通用的HTTP API，几乎兼容了市面上主流的AI工具链。我自己用了快一个月，最大的感受就是“无感”——AI能力被自然地嵌入了日常沟通流，不再是一个需要特意去“打开”的应用。

2. 架构设计与工作模式解析

WeClaw的架构非常清晰，核心目标就是高效、稳定地在微信客户端和AI智能体之间传递消息。它自己并不实现AI能力，而是作为一个智能的路由和协议转换器。

2.1 核心组件与数据流

整个系统可以看作三个主要部分：

1. 微信客户端连接层：负责模拟微信Web端登录，保持在线状态，监听消息事件（接收、发送）。这是最底层也是最关键的一环，需要稳定处理微信的通信协议。
2. WeClaw核心引擎：这是项目的主体。它解析来自微信的消息，根据消息内容（比如是否包含/claude这样的命令）决定将消息路由到哪个AI智能体。同时，它也将AI返回的Markdown、图片URL等格式，转换成微信能够接收和显示的文本、图片、文件格式。
3. AI智能体适配层：这是最灵活的一层。WeClaw设计了三种模式来对接不同的AI工具，以适应它们各异的启动和通信方式。

2.2 三种智能体模式深度对比

这是WeClaw设计上的精髓，理解它们能帮你更好地配置和排错。

实操心得：模式选择优先级WeClaw会自动检测已安装的智能体，并且优先选择ACP模式，其次是CLI，最后是HTTP。这个策略很合理，因为ACP在体验上是最接近“原生集成”的。在实际部署时，你应该优先寻找或构建支持ACP的智能体版本。如果找不到，再考虑CLI。对于完全无法本地化的模型（如GPT-4），HTTP模式是保底选择。

3. 从零开始：完整安装与初始化配置

虽然项目提供了一键安装脚本，但为了更深入地理解和控制，我建议分步骤进行，尤其是第一次安装。

3.1 环境准备与依赖检查

WeClaw本身是用Go编写的，所以跨平台性很好。但在安装前，需要确保你的系统满足一些基本条件。

1. 基础环境：一个能正常登录的微信账号（不推荐使用主力号，可以新注册一个或使用小号），以及稳定的网络环境。
2. 终端工具：你需要一个可用的终端（Terminal）。在macOS上是Terminal或iTerm2，在Windows上建议使用Windows Terminal或WSL2下的终端，在Linux上就是系统自带的终端。
3. 权限问题：在macOS和Linux上，安装过程可能需要向/usr/local/bin等目录写入文件，确保你有相应的sudo权限或该目录的写权限。

3.2 多种安装方式详解

方式一：一键安装脚本（推荐新手）这是最快捷的方式，脚本会自动下载适合你操作系统和CPU架构的最新预编译二进制文件。

curl -sSL https://raw.githubusercontent.com/fastclaw-ai/weclaw/main/install.sh | sh

执行后，脚本会完成下载、解压、移动到系统路径（如/usr/local/bin）的全过程。安装完成后，直接在终端输入weclaw，如果看到帮助信息，说明安装成功。

方式二：通过Go工具链安装（适合Go开发者）如果你的系统已经配置了Go开发环境（Go 1.19+），可以用这种方式，它能确保你安装的是最新的代码版本。

go install github.com/fastclaw-ai/weclaw@latest

安装后，二进制文件会出现在$GOPATH/bin或$GOBIN目录下，请确保该目录在你的系统PATH环境变量中。

方式三：Docker方式（适合环境隔离）对于不想污染主机环境，或者希望在服务器上运行的用户，Docker是最佳选择。

# 拉取最新的WeClaw镜像 docker pull ghcr.io/fastclaw-ai/weclaw:latest # 运行一个临时容器进行登录（扫码） docker run -it --rm -v ~/.weclaw:/root/.weclaw ghcr.io/fastclaw-ai/weclaw login # 以后台服务方式运行 docker run -d --name weclaw \ -v ~/.weclaw:/root/.weclaw \ -p 18011:18011 \ ghcr.io/fastclaw-ai/weclaw:latest

重要提示：Docker与本地AI智能体Docker镜像只包含WeClaw本身。如果你要使用ACP或CLI模式连接本地安装的AI工具（比如你Mac上装的Claude Desktop），这些工具在Docker容器内是不可见的。因此，Docker方案更适用于纯HTTP模式（连接远程API），或者你需要将AI工具也打包进自定义Docker镜像的场景。

3.3 首次启动与微信登录

安装完成后，就可以进行第一次启动了。

weclaw start

首次运行weclaw start会触发以下关键步骤：

1. 生成登录二维码：终端会显示一个二维码图片（如果终端不支持图形，会输出一个URL，你可以复制到浏览器打开显示二维码）。
2. 微信扫码登录：用你的微信（建议使用备用账号）扫描这个二维码，并在手机上确认登录。这个过程和登录微信网页版类似。
3. 配置生成与智能体探测：登录成功后，WeClaw会在你的用户目录下创建~/.weclaw/文件夹，并生成默认的config.json配置文件。同时，它会自动扫描你的系统路径，寻找已知的AI智能体（如claude,codex等命令），并将它们添加到配置中。
4. 服务后台运行：完成上述步骤后，WeClaw会转入后台运行。此时，你的微信账号就已经处于“在线”状态，可以开始接收和处理消息了。

登录信息（cookie、token等）会安全地存储在~/.weclaw/目录下。后续重启WeClaw，通常无需再次扫码，除非登录凭证过期。

4. 核心功能实战：聊天命令与智能体管理

登录成功，服务跑起来之后，真正的乐趣就开始了。你可以在微信里，像和朋友聊天一样指挥不同的AI为你工作。

4.1 基础消息交互

默认情况下，你发给这个微信账号的任何消息，都会被转发给配置中的default_agent（默认是claude，如果检测到的话）。

• 场景：你在微信里收到同事发来的一段问题代码。
• 操作：你直接长按这段代码，转发给你的WeClaw微信账号（它在你微信里显示为一个普通的联系人）。
• 结果：几秒后，你会收到来自WeClaw账号的回复，内容是Claude对这段代码的分析、解释或修改建议。

4.2 智能体指定与切换

如果同时配置了多个AI（比如Claude擅长理解，Codex擅长写代码），你可以通过命令指定由谁来处理当前消息。

• 指定单次处理对象：在消息前加上/智能体名称或/别名。
  • 例如：发送/codex 写一个Python函数，计算斐波那契数列。这条消息会专门交给Codex处理，而不会打扰Claude。
  • 例如：发送/cc 解释一下什么是RESTful API。这里/cc是claude的预设别名（见后文表格）。
• 切换默认智能体：发送/智能体名称命令（后面不跟具体消息），可以永久切换默认的AI，直到你再次切换。
  • 例如：发送/codex。之后你所有没有指定前缀的普通消息，都会默认发送给Codex处理。这个设置会被保存到config.json中，重启后依然有效。

4.3 预设别名与自定义别名

为了方便输入，WeClaw为常用智能体设置了简短的命令别名：

你完全可以自定义别名，让操作更符合你的习惯。编辑~/.weclaw/config.json文件，在对应智能体的配置中添加aliases字段：

{ "agents": { "claude": { "type": "acp", "command": "/usr/local/bin/claude-agent-acp", "aliases": ["c", "ai", "助手"] // 添加自定义别名 } } }

修改配置后，需要重启WeClaw (weclaw stop && weclaw start) 或发送/reload命令（如果支持）来生效。之后，发送/ai 你好或/助手 写首诗，消息都会路由到Claude。

4.4 工作区与上下文管理

AI智能体，特别是CLI模式的，经常需要在特定的项目目录（工作区）下运行，以访问项目文件、理解上下文。

• 切换工作区：使用/cwd /你的/项目/路径命令。这会让后续的AI操作都基于该目录进行。例如，在讨论一个特定Git仓库的问题时，先切换到该仓库根目录，AI就能更好地引用项目内的文件。
• 新建会话：AI对话通常有上下文长度限制。当对话轮数太多，或者你想开始一个全新话题时，发送/new命令。这会清空当前与默认智能体的会话历史，开始一个全新的对话线程。
• 查看信息：发送/info，WeClaw会回复当前默认的智能体是哪个、工作目录是什么等信息，方便你确认当前状态。

5. 高级功能详解：多媒体支持与主动消息

除了文本对话，WeClaw在多媒体消息和主动触达方面也做了贴心设计，让集成体验更完整。

5.1 多媒体消息处理流程

接收端（微信 -> AI）：当你向WeClaw微信账号发送图片、文件或语音消息时，WeClaw会进行预处理。

• 图片/文件：这些媒体文件会被下载到本地临时目录，然后WeClaw可能会根据智能体的能力，将其转换为可处理的格式（如将图片描述给视觉模型，或上传文件内容）。
• 语音消息：这是一个非常实用的功能。WeClaw会调用微信自身的语音转文字服务，将你的语音消息先转换成文本，再将文本发送给AI智能体。这样就实现了“语音提问，文字回答”的流畅体验。系统还做了去重处理，防止网络波动导致同一语音消息被重复处理。

发送端（AI -> 微信）：当AI智能体的回复中包含Markdown格式的图片链接时，WeClaw的转换流程堪称“黑魔法”。

1. 链接提取：WeClaw解析Markdown，找出所有![](图片URL)格式的链接。
2. 图片下载：将网络图片下载到本地。
3. 微信CDN上传：将图片上传到微信的服务器（CDN）。这个过程涉及微信的加密协议（AES-128-ECB），WeClaw已经封装好了。
4. 发送图片消息：最后，将上传后获得的微信内部资源标识，作为图片消息发送回聊天窗口。

同时，为了适配微信较弱的富文本支持，AI回复中的Markdown格式（如代码块、粗体、斜体、链接）会被巧妙地转换为纯文本。例如，代码块会被去掉“```”标记，但保留缩进；链接[文字](URL)会只显示“文字”部分。这样保证了消息在微信端的可读性。

5.2 主动消息发送（Proactive Messaging）

WeClaw不仅能被动回复，还能主动向任何微信联系人（个人、群聊）发送消息。这为自动化流程打开了大门，比如：服务器监控报警、定时提醒、CI/CD结果通知等。

通过CLI命令发送：

# 发送纯文本 weclaw send --to "好友微信ID@im.wechat" --text "数据库备份已完成。" # 发送网络图片 weclaw send --to "群聊ID@im.wechat" --media "https://example.com/chart.png" # 发送本地文件（需绝对路径） weclaw send --to "好友微信ID@im.wechat" --media "/Users/me/report.pdf" # 图文混发 weclaw send --to "好友微信ID@im.wechat" --text "这是你要的图表：" --media "https://example.com/chart.png"

这里的--to参数需要填写微信内部ID，这个ID可以在WeClaw的日志文件~/.weclaw/weclaw.log中查看。当有消息事件发生时，日志会记录发送者的ID。

通过HTTP API发送：当weclaw start运行时，它会启动一个本地HTTP服务器（默认127.0.0.1:18011）。你可以通过任何能发送HTTP请求的工具（如curl、Postman、Python脚本）来调用发送接口。

# 使用curl发送文本 curl -X POST http://127.0.0.1:18011/api/send \ -H "Content-Type: application/json" \ -d '{ "to": "wxid_xxxxxxxxxxxx@im.wechat", "text": "服务器CPU使用率超过90%！" }' # 发送图片 curl -X POST http://127.0.0.1:18011/api/send \ -H "Content-Type: application/json" \ -d '{ "to": "wxid_xxxxxxxxxxxx@im.wechat", "media_url": "https://monitoring.example.com/alert.png" }'

安全提示：默认监听在127.0.0.1是安全的，只有本机可以访问。如果你需要从局域网其他机器调用，可以通过环境变量WECLAW_API_ADDR=0.0.0.0:18011来修改监听地址，但请注意这会暴露接口，应考虑设置防火墙规则。

6. 配置文件深度定制与权限处理

~/.weclaw/config.json是WeClaw的大脑，所有行为都由它控制。理解如何配置它，是解锁高级玩法的关键。

6.1 配置文件结构解析

一个典型的配置包含全局设置和智能体定义两部分。

{ "default_agent": "claude", // 全局默认AI "agents": { // 所有可用的AI智能体定义 "claude": { "type": "acp", // 连接模式：acp, cli, http "command": "/usr/local/bin/claude-agent-acp", // ACP/CLI模式的可执行文件路径 "env": { // 传递给该智能体的环境变量 "ANTHROPIC_API_KEY": "sk-ant-xxx" }, "model": "claude-3-5-sonnet-20241022", // 可选，指定模型 "aliases": ["c", "ai"], // 自定义命令别名 "cwd": "/path/to/your/project", // 工作目录 "args": [] // 启动参数 }, "my_gpt": { "type": "http", "endpoint": "https://api.openai.com/v1/chat/completions", // HTTP API地址 "api_key": "sk-xxx", "model": "gpt-4-turbo-preview", "timeout": 120 // 可选，请求超时时间（秒） } } }

6.2 关键配置项说明

• type：必须准确。acp和cli都需要本地的command可执行文件，而http只需要网络可达的endpoint。
• command：对于acp/cli类型，这里必须是绝对路径。你可以通过which claude这样的命令来查找二进制文件的确切位置。
• env：这是注入API密钥或其他配置的最佳位置。永远不要将密钥硬编码在脚本或命令行参数中，通过env配置既安全又灵活。
• cwd：对于需要访问文件系统的AI（如Codex分析项目），设置正确的工作目录至关重要。如果不设置，默认为~/.weclaw/workspace。
• args：用于传递一些特殊的命令行标志，最典型的用途就是绕过权限检查。

6.3 权限绕过配置详解

某些AI工具的CLI版本（如Claude Desktop的CLI）在非交互式环境（比如被WeClaw这样的后台进程调用）中运行时，会弹出需要图形界面点击确认的权限请求框，这会导致进程卡住。

为了解决这个问题，WeClaw允许你在args中添加特定的“危险”标志来跳过这些检查。

{ "agents": { "claude": { "type": "cli", "command": "/Applications/Claude.app/Contents/MacOS/claude", "args": ["--dangerously-skip-permissions"] // 跳过Claude的所有权限弹窗 }, "codex": { "type": "cli", "command": "/usr/local/bin/codex", "cwd": "/home/user/my-git-repo", "args": ["--skip-git-repo-check"] // 允许在非Git仓库目录运行Codex } } }

严重警告：--dangerously-skip-permissions这类参数正如其名，是危险的。它们会禁用AI工具内置的安全确认机制。例如，Claude在执行“读写文件”等敏感操作前本应征求你的同意，加上这个参数后就自动允许了。请仅在完全信任当前工作环境和对话上下文的情况下使用。ACP模式的智能体通常能更好地处理权限交互，因此不需要这些参数。

7. 生产环境部署：后台服务与系统集成

让WeClaw稳定可靠地在后台运行，是享受其便利的前提。这里介绍几种不同的运行方式。

7.1 后台运行与管理

WeClaw的CLI设计得很完善，管理起来很方便。

# 默认以后台服务方式启动（推荐） weclaw start # 查看运行状态 weclaw status # 输出示例：WeClaw is running (pid: 12345) # 停止服务 weclaw stop # 在前台运行，并输出详细日志（用于调试） weclaw start -f

所有运行日志都会写入~/.weclaw/weclaw.log文件。遇到问题时，查看这个日志是首要的排查手段。

7.2 配置为系统服务（开机自启）

对于需要7x24小时运行的场景，将其注册为系统服务是最佳实践。

macOS (使用 launchd):

1. 将项目service/目录下的com.fastclaw.weclaw.plist文件复制到用户级LaunchAgents目录。

   cp /path/to/weclaw/service/com.fastclaw.weclaw.plist ~/Library/LaunchAgents/

2. 加载并启动服务。

   launchctl load ~/Library/LaunchAgents/com.fastclaw.weclaw.plist launchctl start com.fastclaw.weclaw

3. 检查状态：launchctl list | grep weclaw

Linux (使用 systemd):

1. 将systemd服务文件复制到系统目录。需要sudo权限。

   sudo cp /path/to/weclaw/service/weclaw.service /etc/systemd/system/

2. 重新加载systemd配置，启用（开机自启）并立即启动服务。

   sudo systemctl daemon-reload sudo systemctl enable --now weclaw

3. 检查状态和日志。

   sudo systemctl status weclaw sudo journalctl -u weclaw -f # 跟踪日志

配置调整：你可能需要根据实际安装路径，修改上述.plist或.service文件中的ExecStart路径（例如/usr/local/bin/weclaw start）。

7.3 Docker Compose编排示例

对于使用Docker且配置了多个环境变量（如多个API密钥）的复杂场景，使用Docker Compose管理更清晰。

创建一个docker-compose.yml文件：

version: '3.8' services: weclaw: image: ghcr.io/fastclaw-ai/weclaw:latest container_name: weclaw restart: unless-stopped # 异常退出时自动重启 volumes: - ~/.weclaw:/root/.weclaw # 持久化配置和登录状态 ports: - "18011:18011" # 暴露HTTP API端口到主机 environment: - WECLAW_DEFAULT_AGENT=my_gpt - OPENAI_API_KEY=sk-xxx # 示例：为HTTP模式智能体提供密钥 # 如果需要额外的配置，可以挂载自定义config.json # volumes: # - ./custom-config.json:/root/.weclaw/config.json:ro

然后使用docker-compose up -d启动即可。

8. 常见问题排查与实战技巧

在实际使用中，你可能会遇到一些问题。下面是我踩过坑后总结出来的排查清单和技巧。

8.1 问题排查速查表

8.2 日志分析与调试技巧

日志是排查问题的第一手资料。WeClaw的日志级别比较详细。

# 实时查看最新日志 tail -f ~/.weclaw/weclaw.log # 查看包含“错误”或“失败”的日志行 grep -i "error\|fail\|panic" ~/.weclaw/weclaw.log # 查看特定时间段或智能体的交互日志 grep "claude" ~/.weclaw/weclaw.log | head -20

在日志中，你会看到消息的接收、路由决策、调用AI的过程、以及回复发送的完整链路。如果AI调用失败，日志通常会打印出具体的错误信息，比如API密钥无效、网络超时、命令执行失败等。

8.3 性能优化与稳定性建议

1. 首选ACP模式：如果AI工具提供ACP版本，务必使用它。长连接带来的性能提升是巨大的，尤其是在频繁交互的场景下。
2. 合理设置超时：对于HTTP模式，根据模型和网络情况，在配置中适当调整timeout值，避免因单次请求卡死而阻塞整个服务。
3. 管理会话长度：定期使用/new命令开启新会话，避免过长的上下文消耗大量token（对于按token计费的API）或导致模型性能下降。
4. 使用系统服务：务必配置为launchd或systemd服务，并设置restart策略。这样可以在进程意外退出时自动重启，保障服务可用性。
5. 隔离测试账号：强烈建议使用一个专门的微信小号来运行WeClaw，避免对主要社交账号造成任何潜在风险或干扰。

8.4 自定义扩展思路

WeClaw的架构是开放的，你可以基于它做很多有趣的事情：

• 接入更多AI：只要它能通过CLI或HTTP调用，就可以按照配置模板添加到config.json中。比如接入本地部署的Ollama、通义千问等。
• 构建自动化流程：结合其HTTP API，你可以用任何编程语言编写脚本，监听GitHub Webhook、服务器监控报警，然后自动通过WeClaw发送消息到指定微信群或个人。
• 消息过滤与路由：通过修改源码（Go语言），可以实现更复杂的消息路由逻辑，例如根据关键词将消息转发给不同的AI，或实现群聊中的@机器人功能。

这个项目把微信这个高频的沟通工具，变成了一个可编程的AI交互入口。一旦配置妥当，它就会安静地在后台工作，成为你数字工作流中一个强大而自然的延伸。