op7418/Claude-to-IM-skill

# Claude-to-IM Skill 将 Claude Code / Codex 桥接至 IM 平台 —— 通过 Telegram、Discord、Feishu/Lark、QQ 或 WeChat 与 AI 编程 agent 聊天。 [中文文档](README_CN.md) ## 工作原理 此 Skill 会运行一个后台 daemon，将您的 IM bot 连接到 Claude Code 或 Codex 会话。来自 IM 的消息将被转发至 AI 编程 agent，而回复（包括 tool 调用、权限请求、流式预览）将被发送回您的聊天中。 ``` You (Telegram/Discord/Feishu/QQ/WeChat) ↕ Bot API Background Daemon (Node.js) ↕ Claude Agent SDK or Codex SDK (configurable via CTI_RUNTIME) Claude Code / Codex → reads/writes your codebase ``` ## 功能 - **五大 IM 平台** — Telegram、Discord、Feishu/Lark、QQ、WeChat — 支持任意组合启用 - **交互式设置** — 引导式向导提供分步说明以收集 token - **权限控制** — tool 调用需要通过内联按钮（Telegram/Discord）或文本 `/perm` 命令 / 快捷回复 `1/2/3`（Feishu/QQ/WeChat）获得明确批准 - **流式预览** — 在 Claude 输入时实时查看其回复（Telegram 与 Discord） - **会话持久化** — 对话不会因 daemon 重启而丢失 - **密钥保护** — token 以 `chmod 600` 权限存储，并在所有日志中自动脱敏 - **零代码要求** — 安装 Skill 后运行 `/claude-to-im setup`，或告知 Codex `claude-to-im setup` ## 前置条件 - **Node.js >= 20** - **Claude Code CLI**（用于 `CTI_RUNTIME=claude` 或 `auto`）— 已安装并完成身份验证（`claude` 命令可用） - **Codex CLI**（用于 `CTI_RUNTIME=codex` 或 `auto`）— `npm install -g @openai/codex`。身份验证：运行 `codex auth login`，或设置 `OPENAI_API_KEY`（可选，用于 API 模式） ## 安装说明 请选择与您实际使用的 AI agent 产品相匹配的部分。 ### Claude Code #### 推荐：`npx skills` ``` npx skills add op7418/Claude-to-IM-skill ``` 安装完成后，告诉 Claude Code： ``` /claude-to-im setup ``` 如果您明确需要 WeChat，也可以说： ``` 帮我接微信 ``` #### 替代方案：直接克隆到 Claude Code skills 目录 ``` git clone https://github.com/op7418/Claude-to-IM-skill.git ~/.claude/skills/claude-to-im ``` Claude Code 会自动发现它。 #### 替代方案：为开发创建符号链接 ``` git clone https://github.com/op7418/Claude-to-IM-skill.git ~/code/Claude-to-IM-skill mkdir -p ~/.claude/skills ln -s ~/code/Claude-to-IM-skill ~/.claude/skills/claude-to-im ``` ### Codex #### 推荐：使用 Codex 安装脚本 ``` git clone https://github.com/op7418/Claude-to-IM-skill.git ~/code/Claude-to-IM-skill bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh ``` 如需基于本地实时检出进行开发： ``` bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh --link ``` 安装脚本会将 Skill 放置于 `~/.codex/skills/claude-to-im`，安装依赖项并构建 daemon。 安装完成后，告诉 Codex： ``` claude-to-im setup ``` 如果您明确需要 WeChat，也可以说： ``` 帮我接微信桥接 ``` #### 替代方案：直接克隆到 Codex skills 目录 ``` git clone https://github.com/op7418/Claude-to-IM-skill.git ~/.codex/skills/claude-to-im cd ~/.codex/skills/claude-to-im npm install npm run build ``` ### 验证安装 **Claude Code:** 启动一个新会话并输入 `/` — 您应该能在 Skill 列表中看到 `claude-to-im`。或者询问 Claude：“有哪些可用的 Skill？” **Codex:** 启动一个新会话并说 `claude-to-im setup`、`start bridge`，或 `帮我接微信桥接`。 ## 更新 Skill 请选择与您的 AI agent 产品及安装方式均匹配的更新流程。 ### Claude Code 如果您使用 `npx skills` 安装，请重新运行： ``` npx skills add op7418/Claude-to-IM-skill ``` 如果您通过 `git clone` 或符号链接安装： ``` cd ~/.claude/skills/claude-to-im git pull npm install npm run build ``` 然后告诉 Claude Code： ``` /claude-to-im doctor /claude-to-im start ``` ### Codex 如果您使用 Codex 安装脚本以拷贝模式安装： ``` rm -rf ~/.codex/skills/claude-to-im bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh ``` 如果您使用 `--link` 安装或直接克隆到了 Codex skills 目录： ``` cd ~/.codex/skills/claude-to-im git pull npm install npm run build ``` 然后告诉 Codex： ``` claude-to-im doctor start bridge ``` ## 快速开始 ### 1. 设置 **Claude Code** ``` /claude-to-im setup ``` **Codex** ``` claude-to-im setup ``` 向导将引导您完成： 1. **选择渠道** — 选择 Telegram、Discord、Feishu、QQ、WeChat 或其任意组合 2. **输入凭据** — 向导会详细说明从何处获取每个 token、需要开启哪些设置以及需要授予哪些权限 3. **设置默认项** — 工作目录、模型与模式 4. **验证** — 立即根据平台 API 验证 token ### 2. 启动 **Claude Code** ``` /claude-to-im start ``` **Codex** ``` start bridge ``` daemon 将在后台启动。您可以关闭终端 — 它会持续运行。 ### 3. 聊天 打开您的 IM 应用并向您的 bot 发送消息。Claude Code / Codex 将通过桥接进行回复。 当 Claude 需要使用 tool（编辑文件、运行命令）时，您会在聊天中直接看到一个带有 **Allow** / **Deny** 按钮的权限提示（Telegram/Discord），或一个文本 `/perm` 命令提示 / 快捷回复 `1/2/3`（Feishu/QQ/WeChat）。 ## 命令 所有命令均在 Claude Code 或 Codex 中运行： | Claude Code | Codex（自然语言） | 描述 | |---|---|---| | `/claude-to-im setup` | "claude-to-im setup" / "配置" | 交互式设置向导 | | `/claude-to-im start` | "start bridge" / "启动桥接" | 启动桥接 daemon | | `/claude-to-im stop` | "stop bridge" / "停止桥接" | 停止桥接 daemon | | `/claude-to-im status` | "bridge status" / "状态" | 显示 daemon 状态 | | `/claude-to-im logs` | "查看日志" | 显示最后 50 行日志 | | `/claude-to-im logs 200` | "logs 200" | 显示最后 200 行日志 | | `/claude-to-im reconfigure` | "reconfigure" / "修改配置" | 交互式更新配置 | | `/claude-to-im doctor` | "doctor" / "诊断" | 诊断问题 | ## 平台设置指南 `setup` 向导为每一步提供了内联指导。以下是总结： ### Telegram 1. 在 Telegram 上向 `@BotFather` 发送消息 → `/newbot` → 按照提示操作 2. 复制 bot token（格式：`123456789:AABbCc...`） 3. 推荐：`/setprivacy` → Disable（供群组使用） 4. 查找您的 User ID：向 `@userinfobot` 发送消息 ### Discord 1. 前往 [Discord Developer Portal](https://discord.com/developers/applications) → New Application 2. Bot 标签页 → Reset Token → 复制它 3. 在 Privileged Gateway Intents 下启用 **Message Content Intent** 4. OAuth2 → URL Generator → scope 选择 `bot` → permissions 勾选：Send Messages、Read Message History、View Channels → 复制邀请 URL ### Feishu / Lark 1. 前往 [Feishu Open Platform](https://open.feishu.cn/app)（或 [Lark](https://open.larksuite.com/app)） 2. 创建 Custom App → 获取 App ID 和 App Secret 3. **批量添加权限**：前往“Permissions & Scopes” → 使用批量配置添加所有必需的 scope（`setup` 向导会提供确切的 JSON） 4. 在“Add Features”下启用 Bot 功能 5. **Events & Callbacks**：选择 **“Long Connection”** 作为事件分发方式 → 添加 `im.message.receive_v1` 事件 6. **发布**：前往“Version Management & Release” → 创建版本 → 提交审核 → 在 Admin Console 中批准 7. **重要**：在版本获得批准并发布之前，bot 将无法工作 ### QQ 1. 前往 [QQ Bot OpenClaw](https://q.qq.com/qqbot/openclaw) 2. 创建一个 QQ Bot 或选择现有的 bot → 获取 **App ID** 和 **App Secret**（仅需这两项必填字段） 3. 配置沙箱访问并使用 QQ 扫描二维码以添加 bot 4. `CTI_QQ_ALLOWED_USERS` 接受 `user_openid` 值（而非 QQ 号码）— 初始可为空 5. 如果底层 provider 不支持图片输入，请设置 `CTI_QQ_IMAGE_ENABLED=false` ### WeChat / Weixin 1. 从已安装的 Skill 目录运行本地二维码辅助程序： - Claude Code 默认安装：`cd ~/.claude/skills/claude-to-im && npm run weixin:login` - Codex 默认安装：`cd ~/.codex/skills/claude-to-im && npm run weixin:login` 2. 辅助程序会写入 `~/.claude-to-im/runtime/weixin-login.html` 并尝试自动在您的浏览器中打开它 3. 使用 WeChat 扫描二维码并在手机上确认 4. 成功后，关联的账号将存储于 `~/.claude-to-im/data/weixin-accounts.json` 5. 再次运行辅助程序将替换之前关联的 WeChat 账号 补充说明： - `CTI_WEIXIN_MEDIA_ENABLED` 仅控制入站的图片/文件/视频下载 - 语音消息仅使用 WeChat 内置的语音转文本功能 - 如果 WeChat 未提供 `voice_item.text`，桥接将回复错误，而不是下载/转录原始语音音频 - 权限批准使用文本 `/perm ...` 命令或快捷回复 `1/2/3` ## 架构 ``` ~/.claude-to-im/ ├── config.env ← Credentials & settings (chmod 600) ├── data/ ← Persistent JSON storage │ ├── sessions.json │ ├── bindings.json │ ├── permissions.json │ └── messages/ ← Per-session message history ├── logs/ │ └── bridge.log ← Auto-rotated, secrets redacted └── runtime/ ├── bridge.pid ← Daemon PID file └── status.json ← Current status ``` ### 关键组件 | 组件 | 作用 | |---|---| | `src/main.ts` | daemon 入口 — 组装 DI，启动桥接 | | `src/config.ts` | 加载/保存 `config.env`，映射至桥接设置 | | `src/store.ts` | JSON 文件 BridgeStore（30 个方法，直写缓存） | | `src/llm-provider.ts` | Claude Agent SDK `query()` → SSE 流 | | `src/codex-provider.ts` | Codex SDK `runStreamed()` → SSE 流 | | `src/sse-utils.ts` | 共享 SSE 格式化助手 | | `src/permission-gateway.ts` | 异步桥接：SDK `canUseTool` ↔ IM 按钮 | | `src/logger.ts` | 密钥脱敏的文件日志（带轮换功能） | | `scripts/daemon.sh` | 进程管理（启动/停止/状态/日志） | | `scripts/doctor.sh` | 健康检查 | | `SKILL.md` | Claude Code Skill 定义 | ### 权限流程 ``` 1. Claude wants to use a tool (e.g., Edit file) 2. SDK calls canUseTool() → LLMProvider emits permission_request SSE 3. Bridge sends inline buttons to IM chat: [Allow] [Deny] 4. canUseTool() blocks, waiting for user response (5 min timeout) 5. User taps Allow → bridge resolves the pending permission 6. SDK continues tool execution → result streamed back to IM ``` ## 故障排除 运行诊断： ``` /claude-to-im doctor ``` 此操作会检查：Node.js 版本、配置文件存在性与权限、token 有效性（实时 API 调用）、日志目录、PID 文件一致性以及最近的错误。 | 问题 | 解决方案 | |---|---| | `Bridge won't start` | 运行 `doctor`。检查 Node 是否 >= 20。检查日志。 | | `Messages not received` | 使用 `doctor` 验证 token。检查允许的用户配置。 | | `Permission timeout` | 用户未在 5 分钟内响应。tool 调用自动被拒绝。 | | `Stale PID file` | 依次运行 `stop` 和 `start`。daemon.sh 会自动清理过期 PID。 | 查看 [references/troubleshooting.md](references/troubleshooting.md) 了解更多详情。 ## 安全性 - 所有凭据均以 `chmod 600` 权限存储在 `~/.claude-to-im/config.env` 中 - token 在所有日志输出中都会被自动脱敏（基于模式的掩码处理） - 允许的用户/频道/guild 列表限制了可以与 bot 交互的对象 - daemon 是一个本地进程，没有入站网络监听器 - 请参阅 [SECURITY.md](SECURITY.md) 了解威胁模型与事件响应 ## 开发 ``` npm install # Install dependencies npm run dev # Run in dev mode npm run typecheck # Type check npm test # Run tests npm run build # Build bundle ``` ## 许可证 [MIT](LICENSE)

标签：Discord, GNU通用公共许可证, MITM代理, Node.js, SOC Prime, Telegram, 人工智能, 开发工具, 消息桥接, 用户模式Hook绕过, 自动化攻击, 飞书