Channel Manager

Channel Setup Skill

Configure IM platform channels for openclacky.

Command Parsing

status

Call the server API:

curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels

Response shape (example):

{"channels":[
  {"platform":"feishu","enabled":true,"running":true,"has_config":true,"app_id":"cli_xxx","domain":"https://open.feishu.cn","allowed_users":[]},
  {"platform":"wecom","enabled":false,"running":false,"has_config":false,"bot_id":""},
  {"platform":"weixin","enabled":true,"running":true,"has_config":true,"has_token":true,"base_url":"https://ilinkai.weixin.qq.com","allowed_users":[]},
  {"platform":"discord","enabled":true,"running":true,"has_config":true,"has_token":true,"allowed_users":[]}
  {"platform":"telegram","enabled":true,"running":true,"has_config":true,"has_token":true,"base_url":"https://api.telegram.org","parse_mode":"Markdown","allowed_users":[]}
]}

Display the result:

Channel Status
─────────────────────────────────────────────────────
Platform   Enabled   Running   Details
feishu     ✅ yes    ✅ yes    app_id: cli_xxx...
wecom      ❌ no     ❌ no     (not configured)
weixin     ✅ yes    ✅ yes    has_token: true
discord    ✅ yes    ✅ yes    has_token: true
telegram   ✅ yes    ✅ yes    has_token: true
dingtalk   ✅ yes    ✅ yes    client_id: ding_xxx...
─────────────────────────────────────────────────────

• Feishu: show app_id (truncated to 12 chars)
• WeCom: show bot_id if present
• Weixin: show has_token: true/false (token value is never displayed)
• Discord: show has_token: true/false (token value is never displayed)
• Telegram: show has_token: true/false (bot token is never displayed)
• DingTalk: show client_id (truncated to 12 chars)

If the API is unreachable or returns an empty list: "No channels configured yet. Run /channel-manager setup to get started."

setup

Ask:

Which platform would you like to connect?

1. Feishu
2. WeCom (Enterprise WeChat)
3. Weixin (Personal WeChat via iLink QR login)
4. Discord
5. Telegram (Bot API)
6. DingTalk

Feishu setup

Use the setup script to create the Feishu app automatically via OAuth 2.0 Device Authorization Grant. The user only needs to scan a QR code once.

Step 1 — Run setup script as a background session

terminal(command: "ruby SKILL_DIR/feishu_setup.rb", background: true)

Keep polling the session. The script will print:

• SCAN_URL:<url> — the QR code URL
• EXPIRE_IN:<seconds> — how long the URL is valid

Once you see these lines, tell the user immediately:

• zh: "请在飞书中打开以下链接（或扫码）完成授权，链接 <expire_in> 秒内有效：\n<url>"
• en: "Open this link in Feishu (or scan the QR code) to authorize. Valid for <expire_in>s:\n<url>"

Continue polling until the response contains an exit_code. When the session ends successfully, stdout will contain:

• APP_ID:<app_id>
• APP_SECRET:<app_secret>

Parse both values.

Step 2 — Save credentials

curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/feishu \
  -H "Content-Type: application/json" \
  -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","domain":"https://open.feishu.cn"}'

CRITICAL: This curl call is the ONLY way to save credentials. NEVER write ~/.clacky/channels.yml or any file under ~/.clacky/channels/ directly. The server API handles persistence, hot-reload, and establishing the long connection.

On success: tell the user the following (zh), then continue to Step 3 (Feishu CLI):

zh: "✅ 飞书通道已配置成功！现在你可以通过飞书与智能助手进行私聊和群聊，也支持阅读飞书文档。" en: "✅ Feishu channel configured! You can now chat with the assistant via Feishu DMs or group chats, and read Feishu Docs."

Step 3 — Optional: install Feishu CLI

Reach here after the channel is configured (Step 2 succeeded). Read app_id and app_secret from ~/.clacky/channels.yml (under channels.feishu) for the install commands below.

Call ask_user:

zh:

{
  \"question\": \"是否安装飞书 CLI？安装后将解锁更多飞书能力，例如创建、编辑、删除云文档。\",
  "options": ["安装", "跳过"]
}

en:

{
  "question": "Install Feishu CLI? It unlocks more Feishu capabilities, such as creating, editing, and deleting Docs.",
  "options": ["Install", "Skip"]
}

If the user picks Skip, stop — setup is complete.

If the user picks Enable, run the following in order:

Step 3a — Install and configure (single terminal call):

lark-cli --version > /dev/null 2>&1 || npm install -g @larksuite/cli
echo -n "<APP_SECRET>" | lark-cli config init --app-id <APP_ID> --app-secret-stdin --brand feishu
ruby "SKILL_DIR/install_feishu_skills.rb"

Step 3b — Start authorization as a background session:

terminal(command: "lark-cli auth login --recommend", background: true)

This returns a session_id. Keep polling with terminal(session_id: <id>, input: "") every few seconds.

Once you see the authorization URL appear in the output, tell the user immediately (do not wait for their reply):

• zh: "请在浏览器中打开下方链接完成授权：\n<URL>"
• en: "Open this URL in your browser to authorize:\n<URL>"

Continue polling until the response contains an exit_code (meaning the session has ended). Do not kill the session — restarting invalidates the device code.

When the session ends with exit_code: 0, tell the user:

• zh: "✅ 飞书 CLI 已就绪。"
• en: "✅ Feishu CLI is ready."

Stop — setup is fully complete.

WeCom setup

1. Navigate: open https://work.weixin.qq.com/wework_admin/frame#/aiHelper/create. Pass isolated: true. If the browser is not configured (the open call fails), just give the user the URL and ask them to open it manually in any browser — the rest of the flow is fully manual and does not need browser automation.
2. If a login page or QR code is shown, tell the user to log in and wait for "done".
3. Guide the user: "Scroll to the bottom of the right panel and click 'API mode creation'. Reply done." Wait for "done".
4. Guide the user: "Click 'Add' next to 'Visible Range'. Select the top-level company node. Click Confirm. Reply done." Wait for "done".
5. Guide the user: "If Secret is not visible, click 'Get Secret'. Copy Bot ID and Secret before clicking Save. Paste here. Reply with: Bot ID: xxx, Secret: xxx" Wait for "done".
6. Guide the user: "Click Save. Enter name (e.g. Open Clacky) and description. Click Confirm. Click Save again. Reply done." Wait for "done".
7. Parse credentials. Trim whitespace. Ensure bot_id (starts with aib) and secret are not swapped. Run:

   curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/wecom \
     -H "Content-Type: application/json" \
     -d '{"bot_id":"<BOT_ID>","secret":"<SECRET>"}'

On success: "✅ WeCom channel configured. WeCom client → Contacts → Smart Bot to find it."

Weixin setup (Personal WeChat via iLink QR login)

Weixin uses a QR code login — no app_id/app_secret needed. The token from the QR scan is saved directly in channels.yml.

Step 1 — Fetch QR code

Run the script in --fetch-qr mode to get the QR URL without blocking:

QR_JSON=$(ruby "SKILL_DIR/weixin_setup.rb" --fetch-qr 2>/dev/null)
echo "$QR_JSON"

Parse the JSON output:

• qrcode_url — the URL to open in browser (this IS the QR code content)
• qrcode_id — the session ID needed for polling

If the output contains "error", show it and stop.

Step 2 — Show QR code to user (browser or manual fallback)

Build the local QR page URL (include current Unix timestamp as since to detect new logins only):

http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/weixin-qr.html?url=<URL-encoded qrcode_url>&since=<current_unix_timestamp>

Try browser first — attempt to open the QR page using the browser tool:

browser(action="navigate", url="<qr_page_url>")

If browser succeeds: Tell the user:

I've opened the WeChat QR code in your browser. Please scan it with WeChat, then confirm in the app.

If browser fails (not configured or unavailable): Fall back to manual — tell the user:

Please open the following link in your browser to scan the WeChat QR code:

http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/weixin-qr.html?url=<URL-encoded qrcode_url>

Scan the QR code with WeChat and confirm in the app. I'm already watching for your scan — no need to reply.

Do NOT wait for the user to reply "done". Immediately proceed to Step 3 and start polling — exactly as in the browser-succeeds path. The polling script must already be running while the user scans, so it can observe the scaned → confirmed transition; otherwise a real scan can be misread as a stale session.

The page renders a proper scannable QR code image. Do NOT open the raw qrcode_url directly — that page shows "请使用微信扫码打开" with no actual QR image.

Step 3 — Wait for scan and save credentials

As soon as the QR page has been presented to the user — whether you opened it via the browser tool or gave the user the manual link — immediately run the polling script in the background. In both cases, do NOT wait for the user to confirm or reply "done" before starting the poll — the script must already be running while the user scans:

ruby "SKILL_DIR/weixin_setup.rb" --qrcode-id "$QRCODE_ID"

Where $QRCODE_ID is the qrcode_id from Step 2's JSON output.

Run this command with timeout: 60. If it doesn't succeed, retry up to 3 times with the same $QRCODE_ID — the QR code stays valid for 5 minutes. Only stop retrying if:

• Exit code is 0 → success
• Output contains "stale-session" → the qrcode_id was already consumed by a prior login; immediately restart from Step 1 (do NOT retry with same id)
• Output contains "expired" → QR expired, offer to restart from Step 1
• Output contains "timed out" → offer to restart from Step 1
• 3 retries exhausted → show error and offer to restart from Step 1

Tell the user while waiting:

Waiting for you to scan the QR code and confirm in WeChat... (this may take a moment)

If exit code is 0: "✅ Weixin channel configured! You can now message your bot on WeChat."

If exit code is non-0 or times out: Show the error and offer to retry from Step 2.

Discord setup

Discord requires manual portal interaction (hCaptcha gates Application creation). The browser just navigates the user to the portal; the user clicks through and pastes the bot token + app id back.

Step 1 — Open the developer portal

Get the portal URL from the script and open it in the browser:

PORTAL_URL=$(ruby "SKILL_DIR/discord_setup.rb" --portal-url)

Open it: browser(action="navigate", url="<PORTAL_URL>"). If the browser tool is not configured, invoke browser-setup first, then retry.

Step 2 — Guide the user through the portal (one round-trip)

Tell the user all of the following in a single message, then call ask_user to collect the values in one reply:

In the Discord Developer Portal I just opened:

1. Click New Application (top-right). Name it whatever you like (e.g. "Open Clacky"), check the ToS box, click Create.
2. In the left nav click Bot.
3. Scroll down to Privileged Gateway Intents and turn on MESSAGE CONTENT INTENT, then click Save Changes.
4. Scroll up, click Reset Token → Yes, do it!. Click Copy to copy the bot token. (This is the only time the token is shown — don't navigate away before copying.)
5. In the left nav click General Information. Copy the Application ID.

Paste both values back here in this format (one line):

token=YOUR_BOT_TOKEN app_id=YOUR_APPLICATION_ID

If the user is chatting in a non-English language, append the localized label in parens after each bolded English button name (e.g. **Bot**（机器人）). The English label stays primary — it's what they physically click in the portal.

Use ask_user to collect the reply. Parse with tolerant regex (token=\S+, app_id=\d+).

If the reply is malformed (missing either field), apologise briefly and ask again with the exact same format reminder. Up to 3 retries; after that, surface the original message and stop.

Step 3 — Validate, save, invite, wait

1. Validate the token and save credentials:

   ruby "SKILL_DIR/discord_setup.rb" --validate "<BOT_TOKEN>"

   On success the script prints {"bot_id":"...","username":"..."} and the adapter starts.

2. Generate the invite URL using the application id from Step 2:

   ruby "SKILL_DIR/discord_setup.rb" --invite-url "<APP_ID>"

   Open it: browser(action="navigate", url="<INVITE_URL>"). Tell the user:

   Pick your server from the dropdown → Continue → Authorize. I'll detect when the bot joins.

   If the dropdown is empty, you don't have a server yet — open https://discord.com/channels/@me, click Add a Server (the + button on the left sidebar) → Create My Own → For me and my friends → name it → Create, then re-open the invite link.

3. Wait for the bot to join a guild (long-poll, 10 min timeout). Run with timeout: 620:

   ruby "SKILL_DIR/discord_setup.rb" --watch-guild

   On exit 0: "✅ Discord channel configured! Bot is in <guild_name>. Mention it or DM it from any channel." On timeout: offer to re-open the invite URL — the bot token stays valid.

Telegram setup (Bot API)

Telegram setup is by far the simplest — no browser automation, no QR. The user creates a bot via @BotFather and pastes the token here.