CodeWhale 企业微信 Bridge 部署实战基于智能机器人 WebSocket 长连接的无公网 IP 远程终端方案【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale导读本指南以 CodeWhale 仓库中 integrations/wecom-bridge/DEPLOYMENT.md 为核心骨架讲解如何将 CodeWhale 与企业微信WeCom智能机器人 WebSocket 长连接模式打通实现无需公网 IP即可在手机端远程操控本地codewhale serve --httpRuntime。读完本文你将掌握智能机器人的创建与凭据获取、Runtime 与 Bridge 的双端启动与全部环境变量配置、首次配对First Pairing白名单机制、常用斜杠命令与工具审批流程、以及基于 systemd 的生产级长期部署方法并结合 RUNTIME_API.md 与 bridge-core 源码理解其底层调用链。一、方案概述企业微信智能机器人为什么能免公网 IPWeCom Bridge 与个人微信方向的 integrations/weixin-bridge 不同它面向企业微信组织内部使用企业微信官方智能机器人 API长连接/WebSocket 模式。关键点在于消息投递不再依赖外部主动回调到你的机器那需要公网端口而是由 Bridge 主动向企业微信服务端建立一条出站 WebSocket 长连接事件经此连接下发回复也沿此连接上行。因此部署机只需要能访问外网即可无需开放任何入站端口、无需公网 IP、无需反向代理或内网穿透工具。整体链路如下来自 DEPLOYMENT.md 的 Architecture 小节WeCom Client → Smart Bot WebSocket → WeCom Bridge ──HTTP──→ codewhale serve --http ◀── aibot_respond_msg ◀── (127.0.0.1:7878)Bridge 运行期间的工作流程src/index.mjs 中的WSClient回调可印证用BotID Secret换取access_token建立到智能机器人 API 的 WebSocket 长连接接收aibot_msg_callback事件经文本解析后转成对 CodeWhale Runtime 的/v1/*HTTP 调用通过aibot_respond_msg命令把 Runtime 的回复SSE 事件流送回企业微信。Bridge 本身是纯 Node.js 模块package.json仅依赖wecom/aibot-node-sdk要求 Node.js 18入口为src/index.mjs。二、前置条件与智能机器人创建2.1 前置要求企业微信管理员权限需要进入管理后台创建智能机器人CodeWhale Runtime API运行于http://127.0.0.1:7878本地回环地址Node.js 18承载 Bridge 运行时的运行环境。2.2 创建智能机器人API 模式在企业微信管理后台完成以下步骤打开管理后台 →应用管理 → 智能机器人 → 创建机器人务必选择API 模式不是 Webhook 模式——API 模式才提供aibot_msg_callback长连接事件与aibot_respond_msg回复命令创建成功后复制BotID与Secret后续填入 Bridge 环境变量可选按需配置机器人接收消息的格式。若把 Secret 当作占位符字符串如your-bot-secret、replace-with-long-random-token直接运行Bridge 的配置校验会报placeholder_value/placeholder_runtime_token错误并拒绝启动详见后文“配置校验”。三、快速开始两个终端打通全链路按照官方指南用两个终端分别启动 Runtime 与 Bridge。3.1 终端一启动本地 Runtime APIexport CODEWHALE_RUNTIME_TOKEN$(openssl rand -hex 32) codewhale serve --http --host 127.0.0.1 --port 7878 --auth-token $CODEWHALE_RUNTIME_TOKEN要点说明--auth-token与CODEWHALE_RUNTIME_TOKEN是 Runtime 的 Bearer 令牌Bridge 侧必须配置同一个值所有/v1/*调用都通过Authorization: Bearer token鉴权bridge-core 的 createRuntimeClient绑定地址固定为127.0.0.1只监听回环这是整个方案安全边界的第一层令牌用openssl rand -hex 32生成 64 位十六进制随机串即可避免弱口令。兼容性说明codewhale serve --http是codewhale app-server --http的兼容别名二者启动的是同一个 HTTP/SSE Runtime API 服务器见 docs/RUNTIME_API.md。新集成推荐直接使用codewhale app-server --http。3.2 终端二启动 Bridgecd integrations/wecom-bridge cp .env.example .env # 编辑 .env填入 WeCom 凭据并确保 CODEWHALE_RUNTIME_TOKEN 与终端一完全一致 npm install npm run startnpm run start等价于node src/index.mjs启动日志会打印Starting CodeWhale WeCom bridge、Runtime: url、Workspace: path若未配置白名单还会提示 “No allowlist configured. Incoming chats will receive their IDs and be refused.”src/index.mjs。3.3 验证安装# 语法检查同时检查 src/index.mjs 与 src/lib.mjs npm run check # 运行 bridge 测试套件 npm test期望输出ℹ tests 16 ℹ pass 16 ℹ fail 0。测试覆盖ThreadStore私有状态文件权限目录0700、文件0600、配置校验、中英文自然语言审批关键词识别等见 test/lib.test.mjs。四、环境变量全表必填与可选4.1 必填变量变量示例说明WECOM_BOT_IDwb-xxxxxxxxxxxxxxxx企业微信管理后台智能机器人的 BotIDWECOM_BOT_SECRETyour-secret智能机器人 SecretCODEWHALE_RUNTIME_TOKENrand-xxxxxxxxRuntime API 的 Bearer 令牌生成随机串两侧保持一致4.2 可选变量变量默认值说明CODEWHALE_RUNTIME_URLhttp://127.0.0.1:7878Runtime API 地址源码中会去掉末尾斜杠CODEWHALE_WORKSPACE(cwd)工作区目录CODEWHALE_MODELauto默认模型名称CODEWHALE_MODEagent运行模式来自 READMECODEWHALE_ALLOW_SHELLtrue是否允许 shell 工具.env.exampleCODEWHALE_TRUST_MODEfalse信任模式开关CODEWHALE_AUTO_APPROVEfalse自动审批开关WECOM_CHAT_ALLOWLIST逗号分隔的允许 UserID / chat_id 白名单WECOM_ALLOW_UNLISTEDfalse首次配对模式开关开启时所有聊天都会被放行WECOM_STATE_DIR/var/lib/codewhale-wecom-bridge状态持久化目录WECOM_THREAD_MAP_PATH/var/lib/codewhale-wecom-bridge/thread-map.json聊天 → 线程映射文件路径WECOM_MAX_REPLY_CHARS3500单条回复最大字符数超长自动分块CODEWHALE_TURN_TIMEOUT_MS900000Turn 超时默认 15 分钟CODEWHALE_APPROVAL_TIMEOUT_MS300000审批超时默认 5 分钟WECOM_API_BASE_URLhttps://qyapi.weixin.qq.com企业微信 API 基础地址一般无需修改4.3 源码侧对这些变量的处理在 src/index.mjs 中配置对象逐项读取上述变量requiredEnv对三个必填项做非空校验缺失直接抛XXX is required并退出parseBool支持1/true/yes/on大小写不敏感解析bridge-coreparseList负责把逗号分隔的白名单拆成数组bridge-coremaxReplyChars、turnTimeoutMs、approvalTimeoutMs则用Number(...)从字符串转换。4.4 配置校验启动前自检src/lib.mjs的validateBridgeConfigintegrations/wecom-bridge/src/lib.mjs在缺省时仍会对配置做全面体检errors阻断WECOM_BOT_ID/WECOM_BOT_SECRET/CODEWHALE_RUNTIME_TOKEN缺失或仍为占位符replace-with*、xxxxxxxx、changemeCODEWHALE_RUNTIME_URL不是合法 http/https URLwarnings警告白名单为空且未开配对模式 →not_paired所有聊天都会被拒绝白名单为空但开了WECOM_ALLOW_UNLISTEDtrue→pairing_mode_open首次配对模式保持开放有风险。formatValidationReport会输出[fail]/[warn]/[ok]格式的报告。生产部署时可在服务启动前先跑一遍校验脚本避免把错误配置带入线上。五、首次配对First Pairing如何安全地拿到自己的 IDBridge 默认拒绝一切未在白名单中的聊天。第一次使用需要“配对”保持WECOM_ALLOW_UNLISTEDfalse启动 Bridge在企业微信中给机器人发任意一条消息Bridge 会回复拒绝提示并附上chat_id...单聊场景下还会给出user_id...把其中任意一个值加入WECOM_CHAT_ALLOWLIST逗号分隔多个值可同时配置重启 Bridge 生效。配对的判定逻辑在 integrations/wecom-bridge/src/lib.mjsisAllowed检查chatId与userId二者之一命中白名单即放行拒绝文案pairingRefusalText会回显chat_id与可用的user_id。单聊的chatId会被规范化为single:userid形式这与 ThreadStore 测试 中的single:user-a用例一致。官方 README 也提供另一种配对路径设WECOM_ALLOW_UNLISTEDtrue启动 → 发/status→ 拿到user_id填入白名单 → 改回false重启。两种方式殊途同归后一种更适合机器人较多、消息流量大的场景。无论哪种方式配对完成后都应尽快关闭WECOM_ALLOW_UNLISTED。六、消息命令速查所有非命令内容都会作为 CodeWhale 提示prompt发送给 Runtime群聊中需要在消息前加/cw前缀源码中群聊前缀实际使用stripGroupPrefix私聊直接放行bridge-core。命令说明/help显示帮助/statusruntime 和工作区状态/threads最近的 runtime 线程/new为此聊天创建新线程/resume thread_id绑定到此聊天的现有线程/model name\|default设置或重置聊天模型/interrupt中断活动 turn/compact压缩当前线程/allow approval_id [remember]批准待处理的工具调用remember记录该决策/deny approval_id拒绝待处理的工具调用命令解析链路handleIncomingMessage→stripGroupPrefix→isAllowed→parseCommand→commandActionbridge-core 中的switch分支→ 对应处理函数。例如/status会并行请求/health、/v1/runtime/info、/v1/workspace/status三个端点返回版本、监听地址、鉴权要求、工作区 git 状态src/index.mjs。6.1 工具审批移动端的把关机制当 Runtime 中的 Agent 需要调用工具时会通过 SSE 下发approval.required事件Bridge 收到后在聊天里弹出审批卡片tool、approval_id、描述并提示三种操作方式src/index.mjs显式命令/allow approval_id或/deny approval_id自然语言直接回复「允许」「可以」「好」「同意」「批准」等中文词或yes、ok、approve、allow等英文词拒绝同理支持「拒绝」「不行」「不要」与no、deny、reject、stop等审批 ID 过期默认 5 分钟后需重试或调大CODEWHALE_APPROVAL_TIMEOUT_MS。自然语言识别由 integrations/wecom-bridge/src/lib.mjs 的isApprovalResponse/isDenyResponse实现test/lib.test.mjs 用 16 个用例锁定了关键词表含大小写、去空白、中英文单/双字词、以及“同一关键词不能既是批准又是拒绝”的互斥校验。Bridge 内部还为每个聊天维护了一张pendingApprovals表每 2 分钟清理一次超过 5 分钟的过期审批src/index.mjs。6.2 事件流与 turn 生命周期普通提示的完整链路是POST /v1/threads/{id}/turns发起 turn →GET /v1/threads/{id}/events?since_seqseq建立 SSE 事件流src/index.mjs→ 流式把item.deltaagent 消息增量推回企业微信 → 收到turn.completed或turn.lifecyclefailed/canceled/interrupted结束。整个 turn 受CODEWHALE_TURN_TIMEOUT_MS约束超时会AbortController.abort()并提示 “Turn timed out after Ns”。事件流按since_seq增量读取、lastSeq持久化到 thread map因此 Bridge 重启后可续传不重不漏事件流端点见 docs/RUNTIME_API.md。七、安全边界Security Boundaries官方文档明确列出了四道防线配合源码可进一步确认零公网端口暴露codewhale serve --http仅绑定127.0.0.1Bridge 只主动发起出站 WebSocket 连接Token 鉴权所有/v1/*调用必须携带CODEWHALE_RUNTIME_TOKENAuthorization: Bearer在 bridge-core createRuntimeClient 中强制注入聊天白名单只有WECOM_CHAT_ALLOWLIST内的 chat/user 会被服务isAllowed判定审批闸门来自企业微信的工具调用必须显式审批/allow或自然语言关键词CODEWHALE_AUTO_APPROVE默认关闭。数据边界企业微信一侧只能看到 Bridge 发送的提示、状态摘要、线程列表与审批消息工作区文件内容、shell 输出、Runtime 内部实现细节全部留在本机。Bridge 在向用户回显错误时还会用publicBridgeError把CODEWHALE_RUNTIME_TOKEN替换为redacted并截断到 500 字符src/index.mjs避免令牌通过聊天记录泄露。另外Bridge 的线程状态文件采用0700目录 /0600文件权限写入ThreadStore的privateMode见 bridge-core并有测试专门断言该权限位test/lib.test.mjs 首个用例。八、故障排查速查表症状可能原因解决办法“not paired” 警告WECOM_CHAT_ALLOWLIST为空加入自己的 user_id或临时开启WECOM_ALLOW_UNLISTEDtrue完成配对/allow返回 404审批 ID 已过期默认 5 分钟更快响应或调大CODEWHALE_APPROVAL_TIMEOUT_MSBridge 立即退出缺少环境变量直接运行node src/index.mjs查看校验错误信息收不到消息Secret 或 BotID 错误到企业微信管理后台核对凭据WebSocket 断连网络不稳定Bridge 会自动重连查看 bridge stdout/stderr 日志定位补充两个诊断技巧启动日志中若出现 “No allowlist configured…”说明尚未配对属预期行为npm run check只能查语法配置类错误需通过node src/index.mjs直接运行触发requiredEnv或占位符校验。九、生产环境长期部署9.1 托管两个常驻进程Runtime 与 Bridge 都应交给进程管理器托管systemd、launchd、Windows 任务计划程序、pm2 或终端复用器均可。需要监管的两个命令codewhale serve --http --host 127.0.0.1 --port 7878 --auth-token $CODEWHALE_RUNTIME_TOKEN npm run start --prefix integrations/wecom-bridge仓库 deploy/tencent-lighthouse/systemd 提供了可直接借鉴的 systemd 单元文件codewhale-runtime.service通过EnvironmentFile/etc/codewhale/runtime.env注入令牌ExecStart动态读取CODEWHALE_RUNTIME_PORT/CODEWHALE_RUNTIME_WORKERS并配置Restarton-failure、RestartSec5、NoNewPrivilegestrue、PrivateTmptrue、ProtectSystemfull等加固项codewhale-telegram-bridge.service结构与 wecom bridge 完全同型——Wants/After依赖codewhale-runtime.service、EnvironmentFile注入 bridge 环境变量、ReadWritePaths限定状态目录。将其中的二进制路径与状态目录替换为 wecom 对应值即可套用。9.2 日志采集Bridge 的所有日志输出到 stdout/stderrsystemd 下由journalctl -u service统一采集launchd 可用StandardOutPath/StandardErrorPath重定向到文件自建脚本或 pm2 则直接重定向或由 pm2 自带日志功能接管。9.3 自动重启在同一个进程管理器中启用 restart/recovery瞬时 WebSocket 断连由 Bridge 内置逻辑自动重连wecom/aibot-node-sdk的WSClient无需人工干预进程崩溃或宿主机重启后必须由 supervisor 拉起进程——这是生产可用性的兜底保障。十、与 weixin-bridge 的差异对照特性weixin-bridgewecom-bridge账号类型个人微信企业微信登录方式扫码登录BotID Secret消息协议iLink Bot 长轮询智能机器人 WebSocket认证方式扫码获取 bot_tokenAPI 获取 access_token组织管理无支持企业通讯录权限管理公网需求不需要不需要选型建议个人开发者、面向个人微信号的场景选 weixin-bridge团队/组织内部、需要按企业通讯录做权限管控的场景选 wecom-bridge。二者共享 integrations/bridge-core/src/lib.mjs 中的ThreadStore、命令解析、SSE 读取、Runtime 客户端等公共逻辑维护成本集中。十一、相关文档导航WeCom Bridge README含中文环境变量全表与命令表环境变量模板 .env.exampleCodeWhale Runtime API 参考/v1/*端点与 SSE 事件格式CodeWhale 安全策略CodeWhale 贡献指南【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考