1. 项目概述将微信变身为AI编程助手的远程控制台如果你和我一样经常在电脑前使用Claude Code、Cursor这类AI编程工具但同时又希望能在离开电脑时比如通勤路上、会议室里也能随时调用它们处理一些紧急的代码问题那么WeClaw这个项目绝对值得你花时间研究。简单来说WeClaw是一个桥梁它把你的微信变成了一个可以远程操控本地或云端AI编程助手的“遥控器”。你不需要在手机上安装任何复杂的开发环境只需要像平时聊天一样在微信里发送指令WeClaw就会在你的电脑上调用对应的AI代理Agent执行任务并将结果返回到微信。这个项目的核心价值在于它解决了“场景切换”的痛点。程序员的工作流常常是碎片化的灵感可能在任何地方迸发而调试和编码又需要完整的开发环境。WeClaw通过微信这个几乎人人都在用的高频入口无缝衔接了移动场景与桌面端的强大AI能力。它支持多种主流的AI编程代理包括Claude Code、Codex、OpenCode、Cursor甚至可以通过HTTP模式接入任何兼容OpenAI API的云端大模型。这意味着无论你手头用的是哪款“AI程序员”现在都可以通过微信来指挥它了。2. 核心设计思路与架构解析2.1 为什么是微信—— 入口的普适性与便利性选择微信作为控制入口是一个极其务实的决定。首先微信拥有近乎100%的装机率用户无需额外安装和注册任何新应用学习成本几乎为零。其次微信的消息推送是即时且可靠的这为实时交互提供了基础。最后微信支持文本、图片、文件等多种消息格式这为AI代理处理复杂任务如图表分析、代码截图提供了可能。WeClaw巧妙地利用了微信的“服务号”或“企业微信机器人”背后的iLink Bot API作为通信通道实现了消息的双向转发。2.2 核心架构一个轻量、专注的消息路由器WeClaw的架构设计非常清晰它没有试图成为一个全能的AI工作流平台而是定位为一个“薄薄的消息路由层”。它的核心职责只有三个监听微信消息、路由到正确的AI代理、将结果返回微信。这种专注的设计使得它非常稳定也易于扩展。整个系统的数据流可以这样理解监听层 (Monitor)持续轮询iLink Bot API获取来自微信的新消息。路由层 (Router)这是大脑。它解析消息内容识别用户意图是普通对话还是/codex这样的命令并根据当前用户和“空间”Space的配置决定将消息发送给哪个AI代理。它还负责管理会话状态和日志。代理池 (Agent Pool)管理所有已配置AI代理的生命周期。对于ACP模式的代理如Claude Code它会维持一个长期运行的子进程以实现快速响应对于CLI模式则按需创建进程。发送层 (Sender)将AI代理返回的Markdown格式回复转换成微信支持的纯文本格式并处理其中可能存在的图片链接等媒体资源最后通过iLink API发回微信。这种分层、解耦的设计使得增加一个新的AI代理支持变得非常简单基本上只需要在配置文件中定义它的类型和启动命令即可。2.3 “空间”概念的引入多任务并发的优雅解决方案“空间”Space是WeClaw一个非常精妙的设计它彻底解决了多任务场景下的混乱问题。在没有“空间”之前所有微信消息都进入一个共享的聊天线程如果你想同时用Claude规划项目、用Codex写代码就必须在每条消息前加上/claude或/codex否则上下文就会串线。“空间”本质上是一个隔离的会话工作区。你可以创建多个空间例如work空间默认绑定codex代理专门处理当前项目的代码任务。planning空间默认绑定claude代理用来写技术方案和文档。ops空间绑定一个HTTP模式的GPT-4处理服务器运维问答。每个空间都独立维护自己的默认AI代理和完整的对话历史。通过微信命令/space work codex你就可以切换到work空间并将默认代理设为Codex。此后在这个空间内发送的所有普通消息如“修复登录bug”都会自动交给Codex处理无需重复输入命令。这模拟了我们在IDE中打开不同项目窗口的体验让远程AI协作变得井然有序。3. 详细安装与配置指南3.1 环境准备与一键安装WeClaw本身使用Go语言编写二进制文件跨平台。但它的运行依赖于后端AI代理如Claude Code和微信iLink API的访问权限。假设你已经在开发机上安装好了所需的AI代理那么安装WeClaw本身非常简单。推荐使用一键安装脚本它能处理大部分依赖curl -fsSL https://raw.githubusercontent.com/shp-ai/weclaw/main/install.sh | sh这条命令会从GitHub下载最新的weclaw二进制文件到你的系统路径通常是/usr/local/bin并且如果检测到系统有npm它会自动安装捆绑的Claude和Codex的ACP适配器claude-agent-acp和codex-acp。这两个适配器是实现持久化会话、低延迟响应的关键。注意如果你的网络环境访问GitHub raw内容较慢或者你希望跳过捆绑适配器的安装例如你打算全部使用CLI或HTTP模式可以使用以下命令curl -fsSL https://raw.githubusercontent.com/shp-ai/weclaw/main/install.sh | WECLAW_SKIP_ADAPTERS1 sh安装完成后直接在终端输入weclaw应该能看到帮助信息。3.2 微信端登录与授权安装好WeClaw后第一步是将其与你的微信账号绑定。这里需要的是微信的iLink Bot API权限通常需要通过一个官方或第三方平台申请“机器人”或“回调服务”并获得相应的API端点、Token等信息。由于涉及平台政策具体申请流程可能变化但大致的逻辑是在微信开放平台或企业微信后台创建一个“应用”或“机器人”。获取该应用的AppID、AppSecret、Token、EncodingAESKey等信息。在启动WeClaw前将这些信息通过环境变量或配置文件提供给WeClaw。一个典型的启动和登录流程可能是具体参数名需参考最新文档# 设置环境变量示例实际参数名可能不同 export WECLAW_WECHAT_APP_IDyour_app_id export WECLAW_WECHAT_APP_SECRETyour_app_secret export WECLAW_WECHAT_TOKENyour_token export WECLAW_WECHAT_AES_KEYyour_aes_key # 启动WeClaw服务 weclaw start服务启动后它会在后台监听微信服务器推送的消息。你需要在微信客户端将你的个人号或群聊与该机器人应用关联如扫码关注服务号、邀请机器人进群等。关联成功后你就可以在对应的聊天窗口里机器人或直接发送消息进行测试了。3.3 核心配置文件详解WeClaw的主要行为通过~/.weclaw/config.json配置文件控制。理解这个文件的每个字段是进行高级定制的基础。{ default_agent: claude, // 全局默认代理当消息未指定代理时使用 api_addr: 127.0.0.1:18012, // WeClaw自身HTTP API的监听地址用于接收外部主动消息 agents: { // 定义所有可用的AI代理 claude: { type: acp, // 代理类型acp, cli, http command: claude-agent-acp, // ACP/CLI模式下要执行的二进制命令 args: [--some-flag] // 可选传递给命令的额外参数 }, codex: { type: acp, command: codex-acp }, my_gpt4: { // 自定义一个HTTP代理 type: http, endpoint: https://api.openai.com/v1/chat/completions, api_key: sk-..., // 你的API Key model: gpt-4, // 指定模型 system_prompt: 你是一个专业的代码助手用中文回复。 // 可选系统提示词 }, openclaw_fallback: { // 将OpenClaw配置为CLI后备 type: cli, command: openclaw, args: [--dangerously-skip-permissions] // 跳过交互式权限确认 } } }配置要点解析代理类型选择acp首选。性能最佳会话持久响应快。需要代理本身支持ACP协议如捆绑的claude-agent-acp。cli通用性强。每次调用都启动新进程可能有冷启动延迟。适合任何有命令行接口的工具。http用于连接云端大模型API。功能统一但依赖网络且有上下文长度限制WeClaw默认维护20条消息历史。参数args的使用对于一些CLI工具可能需要附加参数才能非交互式运行。例如Claude CLI需要--dangerously-skip-permissions来跳过工具使用确认Codex CLI可能需要--skip-git-repo-check以便在非Git目录下工作。请谨慎使用这些参数它们绕过了安全确认环节。系统提示词system_prompt在HTTP模式下非常有用。你可以在这里为不同的代理设定不同的角色和任务边界比如让一个代理专精于Python另一个专精于系统设计。4. 核心功能实操与使用技巧4.1 基础消息交互从微信到AI代理假设你已经完成了安装、配置并且WeClaw服务正在运行。你的微信已经与机器人连接。现在打开与机器人的聊天窗口指定代理发送指令这是最直接的方式。输入/codex 写一个Python函数计算斐波那契数列。微信会将这条消息发送给WeClaw路由器识别到/codex命令就会将“写一个Python函数...”这部分内容发送给配置文件中名为codex的代理并将代理的回复返回给你的微信。使用默认代理如果你在某个“空间”里设置了默认代理例如在work空间默认是codex那么直接输入修复用户登录模块的NullPointer异常这条消息就会自动发给Codex处理无需前缀。切换默认代理发送/claude这会将你当前所在空间的默认代理切换为Claude。这是一个持久化操作直到你再次切换或改变空间。4.2 高级功能“空间”的实战管理“空间”的管理可以通过微信命令和WeClaw CLI两种方式进行。微信端快捷操作/spaces列出当前微信账号下的所有空间。/space显示你当前处于哪个空间以及该空间的默认代理是什么。/space backend切换到名为backend的空间。如果该空间不存在则创建它并使用全局默认代理。/space backend claude切换到backend空间并同时将其默认代理设置为claude。CLI端精细管理在服务器上执行# 列出所有空间按账号分组 weclaw space list # 为用户 userim.wechat 添加一个名为“research”的空间并设置默认代理为“my_gpt4” weclaw space add research --account userim.wechat --default-agent my_gpt4 # 删除特定账号下的某个空间 weclaw space remove research --account userim.wechatCLI管理更适合初始化设置或批量操作。所有空间信息都保存在~/.weclaw/state.json中。一个典型的多空间工作流在微信中操作 1. /space projectA codex - 进入/创建projectA空间用Codex。 2. 实现用户注册API。 - 消息自动发给Codex在projectA的上下文中。 3. /space projectB claude - 切换到projectB空间用Claude。 4. 设计这个项目的数据库Schema。 - 消息自动发给Claude在projectB的上下文中与projectA的对话完全隔离。 5. /space projectA - 切回projectA空间。 6. 为刚才的API添加单元测试。 - 消息继续发给Codex并且它还记得之前关于“用户注册API”的对话。这种体验就像在IDE里同时打开了多个项目文件每个文件都有自己的编辑器和历史互不干扰。4.3 主动消息推送将外部事件通知到微信这是WeClaw一个非常强大的特性它不仅仅是一个被动的消息转发器更是一个主动的消息发送网关。你可以从任何能调用HTTP API或命令行的地方向微信发送消息。场景举例CI/CD流水线构建失败或成功时自动推送通知。服务器监控系统发现异常自动告警。你写的脚本定期运行完毕推送结果摘要。使用方法HTTP API推荐WeClaw在运行时会启动一个HTTP服务默认127.0.0.1:18012。# 发送文本消息 curl -X POST http://127.0.0.1:18012/api/send \ -H Content-Type: application/json \ -d { to: 目标用户的微信唯一标识如OpenID, text: 【服务器告警】CPU使用率持续5分钟超过90% } # 发送图片/文件通过URL curl -X POST http://127.0.0.1:18012/api/send \ -H Content-Type: application/json \ -d { to: user_id, media_url: https://your-monitor.com/alert-chart.png }to参数需要是你在微信端绑定机器人时WeClaw日志中记录的那个用户ID。命令行工具在安装了WeClaw的机器上直接使用。weclaw send --to user_id --text 数据库备份任务已于$(date)完成。实操心得主动推送功能的关键在于获取正确的to用户ID。一个可靠的方法是在微信里给机器人发一条消息然后立刻查看WeClaw的日志文件~/.weclaw/weclaw.log或~/.weclaw/logs/下的JSONL文件里面会记录这条消息的发送者ID。把这个ID记下来作为后续推送的to参数。4.4 会话日志与成本追踪所有经过WeClaw的消息交互都会被详细地记录到按日期分割的JSONL日志文件中路径为~/.weclaw/logs/YYYY-MM-DD.jsonl。每一条记录都包含时间戳、方向入站/出站、微信用户、使用的代理、原始消息、AI回复以及耗时。例如{ts:2024-05-27T10:30:00Z,direction:inbound,wechat_user:wxid_abc123,agent:claude,message:解释一下Rust的所有权系统,response:Rust的所有权系统是其内存安全的核心...,latency_ms:1250} {ts:2024-05-27T10:30:02Z,direction:outbound,wechat_user:wxid_abc123,agent:claude,message:以下是解释...,response:,latency_ms:0}这个日志的实用价值极高调试与审计当AI回复不符合预期时可以回溯完整的对话历史看是否是上下文理解有误。成本分摊如果你使用了按Token计费的HTTP API如GPT-4可以通过分析日志统计每个用户、每个项目空间的调用量和成本。你可以编写简单的脚本从response字段估算Token消耗。体验优化分析latency_ms可以了解不同代理的响应性能帮助你决定在 latency-sensitive 的任务中应该首选哪个代理。对话导出你可以基于这个结构化的日志轻松构建一个简单的对话历史查询页面方便知识复盘。日志采用缓冲写入每5秒刷盘一次因此对消息响应的延迟几乎没有影响。5. 不同AI代理模式的深度配置与避坑指南5.1 ACP模式追求极致响应速度ACPAgent Communication Protocol模式是WeClaw的“一等公民”。它通过标准输入输出与AI代理进程进行JSON-RPC通信维持一个常驻子进程。这意味着没有冷启动开销对话上下文完全在代理进程内部维护响应速度最快。配置关键{ claude: { type: acp, command: claude-agent-acp, // 必须是由 claude 官方提供的或兼容的ACP包装器 args: [] } }常见问题与排查问题配置了ACP模式但WeClaw日志显示agent not available或启动失败。排查步骤在终端直接运行claude-agent-acp --version或claude-agent-acp --help确认命令存在且可执行。检查该二进制文件的路径是否在系统的PATH环境变量中。如果不在需要在command中使用绝对路径如/usr/local/bin/claude-agent-acp。检查是否有权限问题。尝试以运行WeClaw的同一用户身份在终端手动启动该代理看是否有错误输出。心得一键安装脚本尝试安装的claude-agent-acp和codex-acp是最省心的方式。如果手动安装务必确认你下载的是支持ACP协议的版本而非普通的CLI。5.2 CLI模式最广泛的兼容性后备CLI模式是通用后备方案。WeClaw会为每一条消息或一个会话启动一个新的代理进程通过命令行参数传递消息并捕获其标准输出作为回复。配置关键{ openclaw: { type: cli, command: openclaw, args: [--dangerously-skip-permissions] // 关键避免交互式阻塞 }, trae: { type: cli, command: trae, args: [] // 根据trae的实际CLI参数调整 } }注意事项与技巧冷启动延迟每次调用都需要启动新进程、加载模型如果是本地模型可能导致响应慢几秒。对于频繁的简短交互体验不佳。会话连续性一些CLI工具支持--resume或类似参数来恢复之前的会话。如果配置的代理支持此功能WeClaw会尝试利用它来维持有限的上下文。你需要查阅具体代理的文档。参数转义确保传递给代理的args是正确的。特别是包含空格或特殊字符的系统提示词可能需要仔细处理引号。权限绕过如配置示例所示很多AI工具的CLI在非交互式环境下会请求权限确认。必须使用像--dangerously-skip-permissions这样的参数来跳过否则进程会挂起等待输入导致WeClaw超时。请理解并接受此操作的安全风险。5.3 HTTP模式无缝接入云端大模型HTTP模式让你可以接入任何提供OpenAI兼容API的模型服务包括OpenAI GPT系列、Anthropic Claude如果其API兼容、国内外的众多大模型平台如智谱GLM、深度求索DeepSeek、月之暗面Kimi等。配置示例以DeepSeek为例{ deepseek_coder: { type: http, endpoint: https://api.deepseek.com/v1/chat/completions, api_key: 你的DeepSeek API Key, model: deepseek-coder, system_prompt: 你是一个专注于代码生成、代码解释和代码调试的AI助手。请用简洁专业的语言回复优先提供可运行的代码片段。, temperature: 0.2, // 可选参数控制创造性 max_tokens: 4096 // 可选参数控制回复长度 } }高级配置与优化流式响应WeClaw的HTTP模式默认尝试使用Server-Sent Events接收流式响应这可以让用户在微信端看到回复是逐字打出的体验更好。如果API端点不支持流式它会自动降级为普通请求。上下文管理WeClaw会为每个用户维护一个最近20条消息的对话历史包括用户消息和AI回复并在每次请求时将其作为messages数组发送。这保证了对话的连贯性。system_prompt会作为第一条系统消息插入历史。超时与重试你可以在配置中未来版本可能支持或通过环境变量设置HTTP请求的超时时间和重试策略这对于不稳定的网络环境很重要。多模型负载均衡你可以为同一个逻辑代理配置多个不同的HTTP后端需要修改WeClaw源码或等待相关插件实现简单的故障转移或负载均衡。6. 生产环境部署、运维与故障排查6.1 以系统服务方式运行对于长期使用你应该将WeClaw配置为系统服务如systemd或launchd以便它能在后台稳定运行开机自启。Linux (systemd) 示例创建服务文件/etc/systemd/system/weclaw.service[Unit] DescriptionWeClaw Bridge Service Afternetwork.target [Service] Typesimple Useryour_username # 改为运行AI代理的实际用户 WorkingDirectory/home/your_username EnvironmentPATH/usr/local/bin:/usr/bin:/bin EnvironmentWECLAW_DEFAULT_AGENTclaude # 可选环境变量 ExecStart/usr/local/bin/weclaw start -f # 前台运行让systemd管理进程 Restarton-failure RestartSec5 [Install] WantedBymulti-user.target启用并启动服务sudo systemctl daemon-reload sudo systemctl enable weclaw sudo systemctl start weclaw sudo systemctl status weclaw # 查看状态macOS (launchd) 示例创建~/Library/LaunchAgents/com.user.weclaw.plist文件内容类似并使用launchctl load加载。6.2 监控与日志查看服务状态weclaw status命令可以快速检查守护进程是否在运行。运行日志主要的运行日志错误、启动信息等在~/.weclaw/weclaw.log。会话日志所有消息往来记录在~/.weclaw/logs/目录下按日期和空间分类。这是最宝贵的调试信息。资源监控如果使用ACP模式AI代理是常驻进程。注意监控它们的内存和CPU使用情况避免资源泄露。6.3 常见问题排查速查表问题现象可能原因排查步骤微信发送消息后无回复1. WeClaw服务未运行。2. 微信iLink API配置错误。3. 路由失败代理未配置或启动失败。1. 运行weclaw status确认。2. 查看weclaw.log是否有连接错误。3. 查看日志中是否有route message to agent X及后续错误。提示agent “claude” not available1. 代理命令在PATH中找不到。2. ACP代理进程启动失败。1. 在终端测试which claude-agent-acp。2. 检查config.json中命令路径是否正确。3. 查看日志中代理进程的具体错误输出。HTTP代理响应慢或超时1. 网络问题。2. API端点限流或不可用。3. 请求的上下文过长。1. 用curl直接测试API端点。2. 查看API提供商的控制台。3. 尝试缩短消息或清理历史。切换空间或代理后上下文混乱1. 空间隔离未生效。2. ACP代理内部缓存了全局上下文。1. 确认使用/space name agent命令。2. 对于某些代理可能需要重启WeClaw服务来清空ACP进程的旧上下文。主动推送API返回错误1. HTTP服务未监听。2.to参数的用户ID不正确。3. 请求格式错误。1. 确认weclaw start已启动且api_addr配置正确。2. 从会话日志中确认正确的wechat_user。3. 检查JSON格式和请求头Content-Type: application/json。6.4 安全与权限考量API密钥保护config.json中存储了云模型API的密钥。务必确保该文件权限为600(chmod 600 ~/.weclaw/config.json)并且不在不安全的环境中备份或共享此文件。网络暴露默认api_addr为127.0.0.1:18012仅本地可访问。如果你需要从外部调用主动推送API可以考虑改为0.0.0.0:18012但务必在前面设置防火墙规则或反向代理如Nginx并添加认证否则任何人都可以向你的微信发送消息。代理权限谨慎使用--dangerously-skip-permissions等参数。确保你信任你所运行的AI代理因为它将在你的用户权限下执行操作如读写文件、执行命令。7. 扩展思路与进阶玩法WeClaw的基础架构已经足够稳固基于它你可以构建更自动化的工作流。1. 构建自动化运维机器人结合主动推送API你可以将服务器监控如Prometheus Alertmanager、CI/CD工具如Jenkins、GitLab CI的webhook配置为在事件发生时向你的微信推送通知。更进一步你可以在微信里直接回复这些通知触发预设的处置脚本例如回复“重启服务”给某个告警WeClaw收到后调用一个HTTP接口执行重启。2. 创建团队协作空间如果你使用企业微信可以将WeClaw机器人拉入项目群。为群聊创建一个独立的“空间”并将默认代理设置为团队常用的AI。这样团队成员在群里提出的技术问题可以直接由AI初步解答或自动生成代码片段提高协作效率。3. 实现代码审查助手在Git服务器如Gitea、Gitee的Webhook中配置当有新的Pull Request时将代码diff通过WeClaw的HTTP API发送给一个专门的“代码审查”AI代理例如配置为使用GPT-4或Claude Sonnet进行分析。AI生成的审查意见可以再通过WeClaw推送到指定的个人或群聊实现半自动化的代码审查流程。4. 个性化知识库问答你可以将HTTP代理的端点指向一个自建的、接入了你公司内部文档知识库的LLM应用例如使用LangChain、LlamaIndex搭建。这样在微信里就可以随时询问公司内部的技术规范、API文档等AI的回答会基于你的知识库更加精准。WeClaw的价值在于它提供了一个极其简单、通用的“人机交互”接口。它将复杂的AI能力封装成了最朴素的“发送消息-接收回复”模式。这种设计看似简单却为各种场景下的自动化与智能化提供了无限的可能性。从我个人的使用体验来看它的稳定性和“空间”设计大大提升了日常使用AI编程助手的效率真正做到了让AI能力触手可及且随场景切换自如。