Channel Manager

Channel Manager Skill

Terminology

When conversing in Chinese, refer to a user-created agent profile as 专家 (not 智能体) when asking whether to bind a channel instance to one — matches the desktop/web UI's Chinese labels. English conversations keep "agent".

Configure IM platform channels for octo. Supported platforms: feishu, weixin, wecom, dingtalk, discord, telegram.

How channels work in octo

• Config lives in ~/.octo/channels.yml (YAML, mode 600). Edit it directly with read_file / write_file.
• The server API is written 127.0.0.1:8088 throughout this skill, the default address. If the Environment section has an Octo server: line, use that address in every command instead.
• Each platform can have multiple bot instances — e.g. 3 Feishu bots in one group, each bound to a different expert agent. Instances are named; the name becomes the adapter_id used in profile channel_bindings.
• Adapters run inside octo serve, started alongside the HTTP server (skip with --no-channel). Config changes are applied on save via POST /api/channels/<platform> — no full restart needed.
• Weixin login state lives separately in ~/.octo/weixin-credentials.json, written by the QR-login flow this skill drives (POST /api/channels/weixin/login on the running serve).

channels.yml schema (multi-instance):

channels:
  feishu:
    - name: code-review-bot       # instance name (adapter_id); omit for single-instance
      enabled: true | false
      app_id: string              # required
      app_secret: string          # required
      domain: string              # optional, default https://open.feishu.cn
      allowed_users: string       # optional, comma-separated user IDs; empty = allow all
    - name: ops-bot               # second instance, same platform
      enabled: true
      app_id: ...
      app_secret: ...
  weixin:
    - enabled: true | false
      token: string               # bot token; optional if cred_path exists
      cred_path: string           # optional, default ~/.octo/weixin-credentials.json
      base_url: string            # optional, default https://ilinkai.weixin.qq.com
      allowed_users: string
  dingtalk:
    - name: ...                   # optional
      enabled: true | false
      client_id: string           # required (AppKey)
      client_secret: string       # required (AppSecret)
      allowed_users: string
  wecom:
    - name: ...
      enabled: true | false
      bot_id: string              # required, intelligent robot Bot ID (starts with "aib")
      secret: string              # required, robot secret
      allowed_users: string
  discord:
    - name: ...
      enabled: true | false
      bot_token: string           # required, from the Discord Developer Portal
      allowed_users: string
  telegram:
    - name: ...
      enabled: true | false
      bot_token: string           # required, from @BotFather
      base_url: string            # optional, default https://api.telegram.org
      parse_mode: string          # optional, default "Markdown"; empty string disables
      allowed_users: string

New instance on an existing platform: append another - entry under the platform key with a unique name. The name field is the adapter_id; single-instance setups can omit it (the platform name is used as the default).

Hot-reload after config change

After writing channels.yml, apply the change without a full restart:

curl -s -X POST "http://127.0.0.1:8088/api/channels/<platform>/reload"

• HTTP 200 → the adapter started immediately. Done.
• Connection refused → the server isn't running. Ask to start it with octo serve.

Use this in place of restart_server throughout this skill. The tool is no longer available in the desktop build (the server runs in-process with no supervisor), so hot-reload via the API is the only zero-downtime path.

Command Parsing

status

1. Read ~/.octo/channels.yml. If missing or empty: "No channels configured yet. Run /channel-manager setup to get started." and stop.
2. Check whether the server (which hosts the adapters) is responding:

   curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8088/api/health

   200 → RUNNING. Non-200 / connection refused → STOPPED.

   Do NOT use pgrep -f "octo.*serve": the server process is named octo-desktop in the desktop build and won't match. The health check works uniformly across octo serve, desktop, and TUI-hosted serves.

3. Display:

Channel Status                       (adapter process: RUNNING/STOPPED)
─────────────────────────────────────────────────────
Platform   Enabled   Details
feishu     ✅ yes    app_id: cli_xxx…
weixin     ✅ yes    credentials: present
dingtalk   ❌ no     (not configured)
─────────────────────────────────────────────────────

• Feishu: show app_id truncated to 12 chars.
• Weixin: show whether token is set or a credential file exists (cred_path, else ~/.octo/weixin-credentials.json). Never print the token value.
• DingTalk: show client_id truncated to 12 chars. Never print client_secret.
• WeCom: show bot_id truncated to 12 chars. Never print secret.
• Discord: show whether bot_token is set (token: present). Never print the token value.
• Telegram: show whether bot_token is set (token: present). Never print the token value.

If the process is STOPPED but at least one platform is enabled, ask: "octo serve 未运行，是否现在启动？" If the user agrees and you can start it safely, run octo serve in the background. If it is RUNNING but started before a recent config change, trigger a hot reload (see "Hot-reload after config change") so the new config takes effect without a restart.

setup

Ask which platform to connect. ask_user_question takes at most 4 options, so ask it in two steps rather than cramming all six in: first the family, then the platform within it.

Which platform would you like to connect?

1. Feishu (飞书)
2. Telegram (Bot API)
3. Discord
4. Something else (WeChat, WeCom, DingTalk)

If they pick "Something else", ask again with those three:

Which one?

1. Weixin (Personal WeChat via iLink QR login)
2. WeCom (企业微信 intelligent robot)
3. DingTalk (钉钉)

After a platform is chosen, ask whether this is a new configuration or an additional instance on an existing platform:

Is this a new platform setup, or adding another bot instance to an existing one?

(If the platform isn't configured yet, skip this question.)

Adding an instance to an existing platform: append a new - entry under the platform key with a name. Ask the user for a name (e.g. "code-review-bot", "ops-bot"), then proceed to the platform-specific credentials steps below. The name is the adapter_id — it appears in InboundEvent and is used for profile channel_bindings.

After credentials are validated and saved, ask:

Do you want to bind this bot instance to an expert agent? If yes, which agent?

List the available agents via GET /api/agents. When the user picks one, call POST /api/agents/:id/bind with {"platform": "<platform>", "adapter_id": "<name>", "chat_id": "<group or DM id>"}. The adapter_id must match the instance name in channels.yml.

Unbinding — when the user asks to unbind (解绑 / 改回默认 agent / 换回默认):

Call DELETE /api/agents/:id/bind with the same body {"platform": "<platform>", "adapter_id": "<name>", "chat_id": "<group or DM id>"}. The match is exact on all three fields (platform, adapter_id, chat_id) — the chat_id for a DM is the user's IM id (e.g. the weixin user_id from the login response). After the call the agent's channel_bindings no longer contains that entry and the chat falls back to the default agent. Confirm success by checking the response — the returned agent JSON must not list the removed binding.

The chat_id to use for unbind is the same one used at bind time. If you don't have it handy, list the agent via GET /api/agents/:id and read channel_bindings for the exact platform / adapter_id / chat_id triple.

Feishu setup

Phase 1 — Create the app

1. Tell the user to open https://open.feishu.cn/app (log in if needed), then: "Click 'Create Enterprise Self-Built App' (创建企业自建应用), fill in a name (e.g. octo) and description, and submit. Reply done." Wait for "done". Always create a new app — do NOT reuse existing apps.

Phase 2 — Enable Bot capability

2. "On the Add App Capabilities page, find the Bot (机器人) card and click Add. Reply done." Wait for "done".

Phase 3 — Get credentials

3. "Open 'Credentials & Basic Info' (凭证与基础信息) in the left menu, copy App ID and App Secret, and paste them here as: App ID: xxx, App Secret: xxx". Parse app_id and app_secret from the reply.

Phase 4 — Add message permissions

4. "Open 'Permission Management' (权限管理) → bulk import (批量导入), clear the example content, paste the JSON below, and confirm. Reply done." Wait for "done".

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message.p2p_msg:readonly",
      "im:message:send_as_bot"
    ],
    "user": []
  }
}

Phase 5 — Validate and save

5. Validate the credentials:

   curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
     -H "Content-Type: application/json" \
     -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}'

   Check for "code":0. On failure show the error and re-ask for credentials (up to 3 tries).
6. Merge into ~/.octo/channels.yml (preserve other platforms), then chmod 600 ~/.octo/channels.yml:

   channels:
     feishu:
       - name: <NAME>             # user-chosen instance name
         enabled: true
         app_id: <APP_ID>
         app_secret: <APP_SECRET>

Phase 6 — Configure event subscription (Long Connection)

CRITICAL: octo's Feishu adapter uses a WebSocket long connection, and Feishu refuses to save the long-connection event config until a client is connected. So the adapter must be running first.

7. Tell the user to (re)start octo serve and wait until the log prints [feishu] connected to WebSocket.
8. "In 'Events & Callbacks' (事件与回调), select 'Long Connection' (长连接) mode and save. Then click Add Event, search im.message.receive_v1, and add it. Reply done." Wait for "done".

Phase 7 — Publish

9. "Open 'Version Management & Release' (版本管理与发布), create a version (e.g. 1.0.0) and publish it. Reply done." Wait for "done".
10. "✅ Feishu channel configured." Trigger a hot reload (see "Hot-reload after config change") so the new adapter starts immediately. If the server isn't running, ask the user to start octo serve first. Then say: "Find the bot in Feishu and send it a message."

Weixin setup (Personal WeChat via iLink QR login)

Weixin uses a QR-code login — no app credentials needed.

Do NOT pgrep for octo serve before this flow — on desktop the server runs as octo-desktop and won't match. Just call the API; if it fails with connection refused, then offer to start the server.

1. Start the QR login flow via the serve API (the response carries the QR link):

   curl -s -X POST http://127.0.0.1:8088/api/channels/weixin/login
   # → {"status":"pending","qr_url":"https://…"}      (or "already_logged_in")

   Pass -d '{"force":true}' to re-login over existing credentials.
2. If the response is already_logged_in:
   • Do not tell the user the credentials are definitely valid. The cached token may have expired.
   • Say: "检测到本地已保存微信登录态，但无法确认是否仍有效。是否重新扫码登录？（回复 重新登录 强制重新扫码，回复 继续 直接复用当前登录态）"
   • If the user replies 重新登录, call POST /api/channels/weixin/login with -d '{"force":true}' and continue from step 3.
   • If the user replies 继续 (or any other confirmation), proceed to step 4.
3. Relay the QR link to the user:

   Open this link and scan the QR code with WeChat, then confirm login in the app: <qr_url from the response>

4. Poll until the flow finishes (every ~3s, up to 5 minutes):

   curl -s http://127.0.0.1:8088/api/channels/weixin/login

   • "status":"done" — credentials are saved to ~/.octo/weixin-credentials.json. Continue.
   • "status":"pending" with a new qr_url — the QR expired and was refreshed; relay the new link.
   • "status":"failed" — show the error and offer to retry from step 1. This agent-driven flow is the only way to log in; the web Channels panel intentionally has no inline QR button.
5. Enable the platform in ~/.octo/channels.yml (preserve other platforms), then chmod 600:

   channels:
     weixin:
       - enabled: true

   The adapter reads ~/.octo/weixin-credentials.json automatically; only set cred_path if the user keeps credentials elsewhere.
6. After writing channels.yml, trigger a hot reload (see "Hot-reload after config change") so the new adapter starts immediately. If the server isn't running, tell the user to start octo serve.
7. "✅ Weixin channel configured. Once octo serve is running, message the bot on WeChat."

DingTalk setup

1. Tell the user to open https://open-dev.dingtalk.com/ (log in if needed), then: "Create an internal app (企业内部应用): Application Development → Create Application. Reply done." Wait for "done".
2. "In the app, open 'Add Application Capabilities' (添加应用能力) and add the Bot (机器人) capability. In the bot's message receiving mode, select Stream mode (Stream 模式) — octo connects over a WebSocket stream, no callback URL needed. Save/publish the capability. Reply done." Wait for "done".
3. "Open 'Credentials & Basic Info' (凭证与基础信息), copy Client ID (AppKey) and Client Secret (AppSecret), and paste them here as: Client ID: xxx, Client Secret: xxx". Parse the reply.
4. Validate:

   curl -s -X POST "https://api.dingtalk.com/v1.0/oauth2/accessToken" \
     -H "Content-Type: application/json" \
     -d '{"appKey":"<CLIENT_ID>","appSecret":"<CLIENT_SECRET>"}'

   Success returns an accessToken field. On failure show the error and re-ask (up to 3 tries).
5. Merge into ~/.octo/channels.yml (preserve other platforms), then chmod 600:

   channels:
     dingtalk:
       - name: <NAME>
         enabled: true
         client_id: <CLIENT_ID>
         client_secret: <CLIENT_SECRET>

6. Trigger a hot reload (see "Hot-reload after config change"). If the server isn't running, remind the user to start octo serve. Then say: "✅ DingTalk channel configured. Publish the app version if you haven't, then message the robot in DingTalk."