Skip to content
Back to search

claude-to-im

SkillWorks with Claude CodeGitHub

Bridge THIS Claude Code or Codex session to Telegram, Discord, Feishu/Lark, QQ, or WeChat so the user can chat with Claude from their phone. Use for: setting up, starting, stopping, or diagnosing the claude-to-im bridge daemon; forwarding Claude replies to a messaging app; any phrase like "claude-to-im", "bridge", "消息推送", "消息转发", "桥接", "连上飞书", "手机上看claude", "启动后台服务", "诊断", "查看日志", "配置". Subcommands: setup, start, stop, status, logs, reconfigure, doctor. Do NOT use for: building standalone bots, webhook integrations, or coding with IM platform SDKs — those are regular programming tasks.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/op7418-claude-to-im-skill/badge.svg)](/listings/op7418-claude-to-im-skill)

HTML

<a href="/listings/op7418-claude-to-im-skill"><img src="/api/listings/op7418-claude-to-im-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Choose the section that matches the AI agent product you actually use.

Claude Code

Recommended: `npx skills`

npx skills add op7418/Claude-to-IM-skill

After installation, tell Claude Code:

/claude-to-im setup

If you want WeChat specifically, you can also say:

帮我接微信

Alternative: clone directly into Claude Code skills

git clone https://github.com/op7418/Claude-to-IM-skill.git ~/.claude/skills/claude-to-im

Claude Code discovers it automatically.

Alternative: symlink for development

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

Recommended: use the Codex install script

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

For local development with a live checkout:

bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh --link

The install script places the skill under `~/.codex/skills/claude-to-im`, installs dependencies, and builds the daemon.

After installation, tell Codex:

claude-to-im setup

If you want WeChat specifically, you can also say:

帮我接微信桥接

Alternative: clone directly into 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

Verify installation

**Claude Code:** Start a new session and type `/` — you should see `claude-to-im` in the skill list. Or ask Claude: "What skills are available?"

**Codex:** Start a new session and say `claude-to-im setup`, `start bridge`, or `帮我接微信桥接`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 192 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: claude-to-im
  3. description: |
  4. Bridge THIS Claude Code or Codex session to Telegram, Discord, Feishu/Lark, QQ, or WeChat so the
  5. user can chat with Claude from their phone. Use for: setting up, starting, stopping,
  6. or diagnosing the claude-to-im bridge daemon; forwarding Claude replies to a messaging
  7. app; any phrase like "claude-to-im", "bridge", "消息推送", "消息转发", "桥接",
  8. "连上飞书", "手机上看claude", "启动后台服务", "诊断", "查看日志", "配置".
  9. Subcommands: setup, start, stop, status, logs, reconfigure, doctor.
  10. Do NOT use for: building standalone bots, webhook integrations, or coding with IM
  11. platform SDKs — those are regular programming tasks.
  12. argument-hint: "setup | start | stop | status | logs [N] | reconfigure | doctor"
  13. allowed-tools:
  14. - Bash
  15. - Read
  16. - Write
  17. - Edit
  18. - AskUserQuestion
  19. - Grep
  20. - Glob
  21. ---
  22. # Claude-to-IM Bridge Skill
  23. You are managing the Claude-to-IM bridge.
  24. User data is stored at `~/.claude-to-im/`.
  25. The skill directory (SKILL_DIR) is at `~/.claude/skills/claude-to-im`.
  26. In Codex installs it may instead be `~/.codex/skills/Claude-to-IM-skill`.
  27. If neither path exists, fall back to Glob with pattern `**/skills/**/claude-to-im/SKILL.md` or `**/skills/**/Claude-to-IM-skill/SKILL.md` and derive the root from the result.
  28. ## Command parsing
  29. Parse the user's intent from `$ARGUMENTS` into one of these subcommands:
  30. | User says (examples) | Subcommand |
  31. |---|---|
  32. | `setup`, `configure`, `配置`, `我想在飞书上用 Claude`, `帮我连接 Telegram`, `帮我接微信` | setup |
  33. | `start`, `start bridge`, `启动`, `启动桥接` | start |
  34. | `stop`, `stop bridge`, `停止`, `停止桥接` | stop |
  35. | `status`, `bridge status`, `状态`, `运行状态`, `怎么看桥接的运行状态` | status |
  36. | `logs`, `logs 200`, `查看日志`, `查看日志 200` | logs |
  37. | `reconfigure`, `修改配置`, `帮我改一下 token`, `换个 bot` | reconfigure |
  38. | `doctor`, `diagnose`, `诊断`, `挂了`, `没反应了`, `bot 没反应`, `出问题了` | doctor |
  39. **Disambiguation: `status` vs `doctor`** — Use `status` when the user just wants to check if the bridge is running (informational). Use `doctor` when the user reports a problem or suspects something is broken (diagnostic). When in doubt and the user describes a symptom (e.g., "没反应了", "挂了"), prefer `doctor`.
  40. Extract optional numeric argument for `logs` (default 50).
  41. Before asking users for any platform credentials, read `SKILL_DIR/references/setup-guides.md` internally so you know where to find each credential. Do NOT dump the full guide to the user upfront — only mention the specific next step they need to do (e.g., "Go to https://open.feishu.cn → your app → Credentials to find the App ID"). If the user says they don't know how, then show the relevant section of the guide.
  42. ## Runtime detection
  43. Before executing any subcommand, detect which environment you are running in:
  44. 1. **Claude Code** — `AskUserQuestion` tool is available. Use it for interactive setup wizards.
  45. 2. **Codex / other** — `AskUserQuestion` is NOT available. Fall back to non-interactive guidance: explain the steps, show `SKILL_DIR/config.env.example`, and ask the user to create `~/.claude-to-im/config.env` manually.
  46. You can test this by checking if AskUserQuestion is in your available tools list.
  47. ## Config check (applies to `start`, `stop`, `status`, `logs`, `reconfigure`, `doctor`)
  48. Before running any subcommand other than `setup`, check if `~/.claude-to-im/config.env` exists:
  49. - **If it does NOT exist:**
  50. - In Claude Code: tell the user "No configuration found" and automatically start the `setup` wizard using AskUserQuestion.
  51. - In Codex: tell the user "No configuration found. Please create `~/.claude-to-im/config.env` based on the example:" then show the contents of `SKILL_DIR/config.env.example` and stop. Don't attempt to start the daemon — without config.env the process will crash on startup and leave behind a stale PID file that blocks future starts.
  52. - **If it exists:** proceed with the requested subcommand.
  53. ## Subcommands
  54. ### `setup`
  55. Run an interactive setup wizard. This subcommand requires `AskUserQuestion`. If it is not available (Codex environment), instead show the contents of `SKILL_DIR/config.env.example` with field-by-field explanations and instruct the user to create the config file manually.
  56. When AskUserQuestion IS available, collect input **one field at a time**. After each answer, confirm the value back to the user (masking secrets to last 4 chars only) before moving to the next question.
  57. **Step 1 — Choose channels**
  58. Ask which channels to enable (telegram, discord, feishu, qq, weixin). Accept comma-separated input. Briefly describe each:
  59. - **telegram** — Best for personal use. Streaming preview, inline permission buttons.
  60. - **discord** — Good for team use. Server/channel/user-level access control.
  61. - **feishu** (Lark) — For Feishu/Lark teams. Streaming cards, tool progress, inline permission buttons.
  62. - **qq** — QQ C2C private chat only. No inline permission buttons, no streaming preview. Permissions use text `/perm ...` commands.
  63. - **weixin** — WeChat QR login. Single linked account only; a new login replaces the previous one. No inline permission buttons, no streaming preview. Permissions use text `/perm ...` commands or quick `1/2/3` replies. Voice messages only use WeChat's own speech-to-text text; raw voice audio is not transcribed by the bridge.
  64. **Step 2 — Collect tokens per channel**
  65. For each enabled channel, collect one credential at a time. Tell the user where to find each value in one sentence. Only show the full guide section (from `SKILL_DIR/references/setup-guides.md`) if the user asks for help or says they don't know how:
  66. - **Telegram**: Bot Token → confirm (masked) → Chat ID (see guide for how to get it) → confirm → Allowed User IDs (optional). **Important:** At least one of Chat ID or Allowed User IDs must be set, otherwise the bot will reject all messages.
  67. - **Discord**: Bot Token → confirm (masked) → Allowed User IDs → Allowed Channel IDs (optional) → Allowed Guild IDs (optional). **Important:** At least one of Allowed User IDs or Allowed Channel IDs must be set, otherwise the bot will reject all messages (default-deny).
  68. - **Feishu**: App ID → confirm → App Secret → confirm (masked) → Domain (optional) → Allowed User IDs (optional). After collecting credentials, explain the two-phase setup the user must complete:
  69. - **Phase 1** (before starting bridge): (A) batch-add permissions, (B) enable bot capability, (C) publish first version + admin approve. This makes permissions and bot effective.
  70. - **Phase 2** (requires running bridge): (D) run `/claude-to-im start`, (E) configure events (`im.message.receive_v1`) and callback (`card.action.trigger`) with long connection mode, (F) publish second version + admin approve.
  71. - **Why two phases:** Feishu validates WebSocket connection when saving event subscription — if the bridge isn't running, saving will fail. The bridge needs published permissions to connect.
  72. - Keep this to a short checklist — show the full guide only if asked.
  73. - **QQ**: Collect two required fields, then optional ones:
  74. 1. QQ App ID (required) → confirm
  75. 2. QQ App Secret (required) → confirm (masked)
  76. - Tell the user: these two values can be found at https://q.qq.com/qqbot/openclaw
  77. 3. Allowed User OpenIDs (optional, press Enter to skip) — note: this is `user_openid`, NOT QQ number. If the user doesn't have openid yet, they can leave it empty.
  78. 4. Image Enabled (optional, default true, press Enter to skip) — if the underlying provider doesn't support image input, set to false
  79. 5. Max Image Size MB (optional, default 20, press Enter to skip)
  80. - Remind user: QQ first version only supports C2C private chat sandbox access. No group/channel support, no inline buttons, no streaming preview.
  81. - **Weixin**: Do not ask for a static token. Instead:
  82. 1. Tell the user this channel uses QR login, not manual credential entry.
  83. 2. Run `cd SKILL_DIR && npm run weixin:login`
  84. 3. The helper writes `~/.claude-to-im/runtime/weixin-login.html` and tries to open it automatically in the local browser.
  85. 4. If auto-open fails, tell the user to open that HTML file manually and scan the QR code with WeChat.
  86. 5. Wait for the helper to report success, then confirm that the linked account was saved locally.
  87. - Explain briefly: the linked Weixin account is stored in `~/.claude-to-im/data/weixin-accounts.json`. Running the helper again replaces the previously linked account.
  88. - Explain briefly: `CTI_WEIXIN_MEDIA_ENABLED` only controls inbound image/file/video downloads. For voice messages, the bridge only accepts the text returned by WeChat's built-in speech-to-text. If WeChat does not provide a transcript, the bridge replies with an error instead of downloading/transcribing raw audio.
  89. **Step 3 — General settings**
  90. Ask for runtime, default working directory, model, and mode:
  91. - **Runtime**: `claude` (default), `codex`, `auto`
  92. - `claude` — uses Claude Code CLI + Claude Agent SDK (requires `claude` CLI installed)
  93. - `codex` — uses OpenAI Codex SDK (requires `codex` CLI; auth via `codex auth login` or `OPENAI_API_KEY`)
  94. - `auto` — tries Claude first, falls back to Codex if Claude CLI not found
  95. - **Working Directory**: default `$CWD`
  96. - **Model** (optional): Leave blank to inherit the runtime's own default model. If the user wants to override, ask them to enter a model name. Do NOT hardcode or suggest specific model names — the available models change over time.
  97. - **Mode**: `code` (default), `plan`, `ask`
  98. **Step 4 — Write config and validate**
  99. 1. Show a final summary table with all settings (secrets masked to last 4 chars)
  100. 2. Ask user to confirm before writing
  101. 3. Use Bash to create directory structure: `mkdir -p ~/.claude-to-im/{data,logs,runtime,data/messages}`
  102. 4. Use Write to create `~/.claude-to-im/config.env` with all settings in KEY=VALUE format
  103. 5. Use Bash to set permissions: `chmod 600 ~/.claude-to-im/config.env`
  104. 6. Validate tokens — read `SKILL_DIR/references/token-validation.md` for the exact commands and expected responses for each platform. This catches typos and wrong credentials before the user tries to start the daemon. For Weixin, a successful QR login already counts as validation.
  105. 7. Report results with a summary table. If any validation fails, explain what might be wrong and how to fix it.
  106. 8. On success, tell the user: "Setup complete! Run `/claude-to-im start` to start the bridge."
  107. ### `start`
  108. **Pre-check:** Verify `~/.claude-to-im/config.env` exists (see "Config check" above). Without it, the daemon will crash immediately and leave a stale PID file.
  109. Run: `bash "SKILL_DIR/scripts/daemon.sh" start`
  110. Show the output to the user. If it fails, tell the user:
  111. - Run `doctor` to diagnose: `/claude-to-im doctor`
  112. - Check recent logs: `/claude-to-im logs`
  113. ### `stop`
  114. Run: `bash "SKILL_DIR/scripts/daemon.sh" stop`
  115. ### `status`
  116. Run: `bash "SKILL_DIR/scripts/daemon.sh" status`
  117. ### `logs`
  118. Extract optional line count N from arguments (default 50).
  119. Run: `bash "SKILL_DIR/scripts/daemon.sh" logs N`
  120. ### `reconfigure`
  121. 1. Read current config from `~/.claude-to-im/config.env`
  122. 2. Show current settings in a clear table format, with all secrets masked (only last 4 chars visible)
  123. 3. Use AskUserQuestion to ask what the user wants to change
  124. 4. When collecting new values, tell the user where to find the value; only show the full guide from `SKILL_DIR/references/setup-guides.md` if they ask for help
  125. 5. Update the config file atomically (write to tmp, rename)
  126. 6. Re-validate any changed tokens
  127. 7. Remind user: "Run `/claude-to-im stop` then `/claude-to-im start` to apply the changes."
  128. If the user wants to switch Weixin accounts during `reconfigure`, run `cd SKILL_DIR && npm run weixin:login` again. Each successful scan replaces the previously linked local account.
  129. ### `doctor`
  130. Run: `bash "SKILL_DIR/scripts/doctor.sh"`
  131. Show results and suggest fixes for any failures. Common fixes:
  132. - SDK cli.js missing → `cd SKILL_DIR && npm install`
  133. - dist/daemon.mjs stale → `cd SKILL_DIR && npm run build`
  134. - Config missing → run `setup`
  135. - Weixin account missing / expired → `cd SKILL_DIR && npm run weixin:login`
  136. - Weixin voice message reports missing speech-to-text → enable WeChat's own voice transcription and resend; the bridge does not transcribe raw voice audio itself
  137. For more complex issues (messages not received, permission timeouts, high memory, stale PID files), read `SKILL_DIR/references/troubleshooting.md` for detailed diagnosis steps.
  138. **Feishu upgrade note:** If the user upgraded from an older version of this skill and Feishu is returning permission errors (e.g. streaming cards not working, typing indicators failing, permission buttons unresponsive), the root cause is almost certainly missing permissions or callbacks in the Feishu backend. Refer the user to the "Upgrading from a previous version" section in `SKILL_DIR/references/setup-guides.md` — they need to add new scopes (`cardkit:card:write`, `cardkit:card:read`, `im:message:update`, `im:message.reactions:read`, `im:message.reactions:write_only`), add the `card.action.trigger` callback, and re-publish the app. The upgrade requires two publish cycles because adding the callback needs an active WebSocket connection (bridge must be running).
  139. ## Notes
  140. - Always mask secrets in output (show only last 4 characters) — users often share terminal output in bug reports, so exposed tokens would be a security incident.
  141. - Always check for config.env before starting the daemon — without it the process crashes on startup and leaves a stale PID file that blocks future starts (requiring manual cleanup).
  142. - The daemon runs as a background Node.js process managed by platform supervisor (launchd on macOS, setsid on Linux, WinSW/NSSM on Windows).
  143. - Config persists at `~/.claude-to-im/config.env` — survives across sessions.
README.md · README · 376 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Claude-to-IM Skill
  2. Bridge Claude Code / Codex to IM platforms — chat with AI coding agents from Telegram, Discord, Feishu/Lark, QQ, or WeChat.
  3. [中文文档](README_CN.md)
  4. > **Want a desktop GUI instead?** Check out [CodePilot](https://github.com/op7418/CodePilot) — a full-featured desktop app with visual chat interface, session management, file tree preview, permission controls, and more. This skill was extracted from CodePilot's IM bridge module for users who prefer a lightweight, CLI-only setup.
  5. ---
  6. ## How It Works
  7. This skill runs a background daemon that connects your IM bots to Claude Code or Codex sessions. Messages from IM are forwarded to the AI coding agent, and responses (including tool use, permission requests, streaming previews) are sent back to your chat.
  8. ```
  9. You (Telegram/Discord/Feishu/QQ/WeChat)
  10. ↕ Bot API
  11. Background Daemon (Node.js)
  12. ↕ Claude Agent SDK or Codex SDK (configurable via CTI_RUNTIME)
  13. Claude Code / Codex → reads/writes your codebase
  14. ```
  15. ## Features
  16. - **Five IM platforms** — Telegram, Discord, Feishu/Lark, QQ, WeChat — enable any combination
  17. - **Interactive setup** — guided wizard collects tokens with step-by-step instructions
  18. - **Permission control** — tool calls require explicit approval via inline buttons (Telegram/Discord) or text `/perm` commands / quick `1/2/3` replies (Feishu/QQ/WeChat)
  19. - **Streaming preview** — see Claude's response as it types (Telegram & Discord)
  20. - **Session persistence** — conversations survive daemon restarts
  21. - **Secret protection** — tokens stored with `chmod 600`, auto-redacted in all logs
  22. - **Zero code required** — install the skill and run `/claude-to-im setup`, or tell Codex `claude-to-im setup`
  23. ## Prerequisites
  24. - **Node.js >= 20**
  25. - **Claude Code CLI** (for `CTI_RUNTIME=claude` or `auto`) — installed and authenticated (`claude` command available)
  26. - **Codex CLI** (for `CTI_RUNTIME=codex` or `auto`) — `npm install -g @openai/codex`. Auth: run `codex auth login`, or set `OPENAI_API_KEY` (optional, for API mode)
  27. ## Installation
  28. Choose the section that matches the AI agent product you actually use.
  29. ### Claude Code
  30. #### Recommended: `npx skills`
  31. ```bash
  32. npx skills add op7418/Claude-to-IM-skill
  33. ```
  34. After installation, tell Claude Code:
  35. ```text
  36. /claude-to-im setup
  37. ```
  38. If you want WeChat specifically, you can also say:
  39. ```text
  40. 帮我接微信
  41. ```
  42. #### Alternative: clone directly into Claude Code skills
  43. ```bash
  44. git clone https://github.com/op7418/Claude-to-IM-skill.git ~/.claude/skills/claude-to-im
  45. ```
  46. Claude Code discovers it automatically.
  47. #### Alternative: symlink for development
  48. ```bash
  49. git clone https://github.com/op7418/Claude-to-IM-skill.git ~/code/Claude-to-IM-skill
  50. mkdir -p ~/.claude/skills
  51. ln -s ~/code/Claude-to-IM-skill ~/.claude/skills/claude-to-im
  52. ```
  53. ### Codex
  54. #### Recommended: use the Codex install script
  55. ```bash
  56. git clone https://github.com/op7418/Claude-to-IM-skill.git ~/code/Claude-to-IM-skill
  57. bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh
  58. ```
  59. For local development with a live checkout:
  60. ```bash
  61. bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh --link
  62. ```
  63. The install script places the skill under `~/.codex/skills/claude-to-im`, installs dependencies, and builds the daemon.
  64. After installation, tell Codex:
  65. ```text
  66. claude-to-im setup
  67. ```
  68. If you want WeChat specifically, you can also say:
  69. ```text
  70. 帮我接微信桥接
  71. ```
  72. #### Alternative: clone directly into Codex skills
  73. ```bash
  74. git clone https://github.com/op7418/Claude-to-IM-skill.git ~/.codex/skills/claude-to-im
  75. cd ~/.codex/skills/claude-to-im
  76. npm install
  77. npm run build
  78. ```
  79. ### Verify installation
  80. **Claude Code:** Start a new session and type `/` — you should see `claude-to-im` in the skill list. Or ask Claude: "What skills are available?"
  81. **Codex:** Start a new session and say `claude-to-im setup`, `start bridge`, or `帮我接微信桥接`.
  82. ## Updating the Skill
  83. Choose the update flow that matches both your AI agent product and your installation method.
  84. ### Claude Code
  85. If you installed with `npx skills`, re-run:
  86. ```bash
  87. npx skills add op7418/Claude-to-IM-skill
  88. ```
  89. If you installed via `git clone` or symlink:
  90. ```bash
  91. cd ~/.claude/skills/claude-to-im
  92. git pull
  93. npm install
  94. npm run build
  95. ```
  96. Then tell Claude Code:
  97. ```text
  98. /claude-to-im doctor
  99. /claude-to-im start
  100. ```
  101. ### Codex
  102. If you installed with the Codex install script in copy mode:
  103. ```bash
  104. rm -rf ~/.codex/skills/claude-to-im
  105. bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh
  106. ```
  107. If you installed with `--link` or cloned directly into the Codex skills directory:
  108. ```bash
  109. cd ~/.codex/skills/claude-to-im
  110. git pull
  111. npm install
  112. npm run build
  113. ```
  114. Then tell Codex:
  115. ```text
  116. claude-to-im doctor
  117. start bridge
  118. ```
  119. ## Quick Start
  120. ### 1. Setup
  121. **Claude Code**
  122. ```text
  123. /claude-to-im setup
  124. ```
  125. **Codex**
  126. ```text
  127. claude-to-im setup
  128. ```
  129. The wizard will guide you through:
  130. 1. **Choose channels** — pick Telegram, Discord, Feishu, QQ, WeChat, or any combination
  131. 2. **Enter credentials** — the wizard explains exactly where to get each token, which settings to enable, and what permissions to grant
  132. 3. **Set defaults** — working directory, model, and mode
  133. 4. **Validate** — tokens are verified against platform APIs immediately
  134. ### 2. Start
  135. **Claude Code**
  136. ```text
  137. /claude-to-im start
  138. ```
  139. **Codex**
  140. ```text
  141. start bridge
  142. ```
  143. The daemon starts in the background. You can close the terminal — it keeps running.
  144. ### 3. Chat
  145. Open your IM app and send a message to your bot. Claude Code / Codex will respond through the bridge.
  146. When Claude needs to use a tool (edit a file, run a command), you'll see a permission prompt with **Allow** / **Deny** buttons right in the chat (Telegram/Discord), or a text `/perm` command prompt / quick `1/2/3` replies (Feishu/QQ/WeChat).
  147. ## Commands
  148. All commands are run inside Claude Code or Codex:
  149. | Claude Code | Codex (natural language) | Description |
  150. |---|---|---|
  151. | `/claude-to-im setup` | "claude-to-im setup" / "配置" | Interactive setup wizard |
  152. | `/claude-to-im start` | "start bridge" / "启动桥接" | Start the bridge daemon |
  153. | `/claude-to-im stop` | "stop bridge" / "停止桥接" | Stop the bridge daemon |
  154. | `/claude-to-im status` | "bridge status" / "状态" | Show daemon status |
  155. | `/claude-to-im logs` | "查看日志" | Show last 50 log lines |
  156. | `/claude-to-im logs 200` | "logs 200" | Show last 200 log lines |
  157. | `/claude-to-im reconfigure` | "reconfigure" / "修改配置" | Update config interactively |
  158. | `/claude-to-im doctor` | "doctor" / "诊断" | Diagnose issues |
  159. ## Platform Setup Guides
  160. The `setup` wizard provides inline guidance for every step. Here's a summary:
  161. ### Telegram
  162. 1. Message `@BotFather` on Telegram → `/newbot` → follow prompts
  163. 2. Copy the bot token (format: `123456789:AABbCc...`)
  164. 3. Recommended: `/setprivacy` → Disable (for group use)
  165. 4. Find your User ID: message `@userinfobot`
  166. ### Discord
  167. 1. Go to [Discord Developer Portal](https://discord.com/developers/applications) → New Application
  168. 2. Bot tab → Reset Token → copy it
  169. 3. Enable **Message Content Intent** under Privileged Gateway Intents
  170. 4. OAuth2 → URL Generator → scope `bot` → permissions: Send Messages, Read Message History, View Channels → copy invite URL
  171. ### Feishu / Lark
  172. 1. Go to [Feishu Open Platform](https://open.feishu.cn/app) (or [Lark](https://open.larksuite.com/app))
  173. 2. Create Custom App → get App ID and App Secret
  174. 3. **Batch-add permissions**: go to "Permissions & Scopes" → use batch configuration to add all required scopes (the `setup` wizard provides the exact JSON)
  175. 4. Enable Bot feature under "Add Features"
  176. 5. **Events & Callbacks**: select **"Long Connection"** as event dispatch method → add `im.message.receive_v1` event
  177. 6. **Publish**: go to "Version Management & Release" → create version → submit for review → approve in Admin Console
  178. 7. **Important**: The bot will NOT work until the version is approved and published
  179. ### QQ
  180. > QQ currently supports **C2C private chat only**. No group/channel support, no inline permission buttons, no streaming preview. Permissions use text `/perm ...` commands. Image inbound only (no image replies).
  181. 1. Go to [QQ Bot OpenClaw](https://q.qq.com/qqbot/openclaw)
  182. 2. Create a QQ Bot or select an existing one → get **App ID** and **App Secret** (only two required fields)
  183. 3. Configure sandbox access and scan QR code with QQ to add the bot
  184. 4. `CTI_QQ_ALLOWED_USERS` takes `user_openid` values (not QQ numbers) — can be left empty initially
  185. 5. Set `CTI_QQ_IMAGE_ENABLED=false` if the underlying provider doesn't support image input
  186. ### WeChat / Weixin
  187. > WeChat currently uses QR login, single-account mode, text-based permissions, and no streaming preview.
  188. 1. Run the local QR helper from your installed skill directory:
  189. - Claude Code default install: `cd ~/.claude/skills/claude-to-im && npm run weixin:login`
  190. - Codex default install: `cd ~/.codex/skills/claude-to-im && npm run weixin:login`
  191. 2. The helper writes `~/.claude-to-im/runtime/weixin-login.html` and tries to open it in your browser automatically
  192. 3. Scan the QR code with WeChat and confirm on your phone
  193. 4. On success, the linked account is stored in `~/.claude-to-im/data/weixin-accounts.json`
  194. 5. Running the helper again replaces the previously linked WeChat account
  195. Additional notes:
  196. - `CTI_WEIXIN_MEDIA_ENABLED` controls inbound image/file/video downloads only
  197. - Voice messages only use WeChat's own built-in speech-to-text text
  198. - If WeChat does not provide `voice_item.text`, the bridge replies with an error instead of downloading/transcribing raw voice audio
  199. - Permission approvals use text `/perm ...` commands or quick `1/2/3` replies
  200. ## Architecture
  201. ```
  202. ~/.claude-to-im/
  203. ├── config.env ← Credentials & settings (chmod 600)
  204. ├── data/ ← Persistent JSON storage
  205. │ ├── sessions.json
  206. │ ├── bindings.json
  207. │ ├── permissions.json
  208. │ └── messages/ ← Per-session message history
  209. ├── logs/
  210. │ └── bridge.log ← Auto-rotated, secrets redacted
  211. └── runtime/
  212. ├── bridge.pid ← Daemon PID file
  213. └── status.json ← Current status
  214. ```
  215. ### Key components
  216. | Component | Role |
  217. |---|---|
  218. | `src/main.ts` | Daemon entry — assembles DI, starts bridge |
  219. | `src/config.ts` | Load/save `config.env`, map to bridge settings |
  220. | `src/store.ts` | JSON file BridgeStore (30 methods, write-through cache) |
  221. | `src/llm-provider.ts` | Claude Agent SDK `query()` → SSE stream |
  222. | `src/codex-provider.ts` | Codex SDK `runStreamed()` → SSE stream |
  223. | `src/sse-utils.ts` | Shared SSE formatting helper |
  224. | `src/permission-gateway.ts` | Async bridge: SDK `canUseTool` ↔ IM buttons |
  225. | `src/logger.ts` | Secret-redacted file logging with rotation |
  226. | `scripts/daemon.sh` | Process management (start/stop/status/logs) |
  227. | `scripts/doctor.sh` | Health checks |
  228. | `SKILL.md` | Claude Code skill definition |
  229. ### Permission flow
  230. ```
  231. 1. Claude wants to use a tool (e.g., Edit file)
  232. 2. SDK calls canUseTool() → LLMProvider emits permission_request SSE
  233. 3. Bridge sends inline buttons to IM chat: [Allow] [Deny]
  234. 4. canUseTool() blocks, waiting for user response (5 min timeout)
  235. 5. User taps Allow → bridge resolves the pending permission
  236. 6. SDK continues tool execution → result streamed back to IM
  237. ```
  238. ## Troubleshooting
  239. Run diagnostics:
  240. ```
  241. /claude-to-im doctor
  242. ```
  243. This checks: Node.js version, config file existence and permissions, token validity (live API calls), log directory, PID file consistency, and recent errors.
  244. | Issue | Solution |
  245. |---|---|
  246. | `Bridge won't start` | Run `doctor`. Check if Node >= 20. Check logs. |
  247. | `Messages not received` | Verify token with `doctor`. Check allowed users config. |
  248. | `Permission timeout` | User didn't respond within 5 min. Tool call auto-denied. |
  249. | `Stale PID file` | Run `stop` then `start`. daemon.sh auto-cleans stale PIDs. |
  250. See [references/troubleshooting.md](references/troubleshooting.md) for more details.
  251. ## Security
  252. - All credentials stored in `~/.claude-to-im/config.env` with `chmod 600`
  253. - Tokens are automatically redacted in all log output (pattern-based masking)
  254. - Allowed user/channel/guild lists restrict who can interact with the bot
  255. - The daemon is a local process with no inbound network listeners
  256. - See [SECURITY.md](SECURITY.md) for threat model and incident response
  257. ## Development
  258. ```bash
  259. npm install # Install dependencies
  260. npm run dev # Run in dev mode
  261. npm run typecheck # Type check
  262. npm test # Run tests
  263. npm run build # Build bundle
  264. ```
  265. ## License
  266. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.