fix(gateway): implement yuanbao channel with real app_key/app_secret protocol

[huangcheng]

Problem

The Yuanbao (Tencent 元宝) channel was completely unusable: after configuring the correct App Key / App Secret, the channel probe failed with "credentials incomplete: missing Token, Bot ID".

Root cause

harness-gateway==0.8.5 ships a placeholder YuanbaoConfig stub that:

1. Requires the wrong credentials (token / bot_id) — and ChannelConfig.from_dict silently drops the unknown app_key / app_secret fields the dashboard persists, so the probe always reports missing Token / Bot ID.
2. Implements a non-existent HTTP-callback protocol. Even if the probe passed, the channel could never send or receive a single message.

The real Tencent Yuanbao protocol is: exchange app_key:app_secret for a signed token via HMAC-SHA256 against POST /api/v5/robotLogic/sign-token, then connect to wss://bot-wss.yuanbao.tencent.com/wss/connection and speak a binary protobuf (ConnMsg) wire protocol.

Fix

The upstream harness-gateway repository is currently not publicly accessible, so this ships a working channel inside Octop for now. Once upstream publishes a real implementation this can be removed.

• infra/gateway/channels/yuanbao.py (new) — self-contained implementation:
  • YuanbaoConfig(app_key, app_secret, api_domain, ws_url) with missing_credentials() validation.
  • Hand-rolled protobuf codec (ConnMsg, auth-bind, ping, send_c2c_message / send_group_message, InboundMessagePush).
  • HMAC-SHA256 sign-token with cached refresh (300s margin) and retry on code 10099.
  • WSS lifecycle: auth-bind, heartbeat driven by the server-reported PingRsp.heartInterval, push handling with PushAck, kickout handling, anti-loopback (skip own messages).
  • Exponential-backoff reconnect ([1,2,5,10,30,60]s); non-retryable close codes 4012/4013/4014/4018/4019/4021; token refresh on auth codes 41103/41104/41108.
  • Structured after the same package's qq.py.
• gateway.py — registers the yuanbao channel via manager.add_channel(instance) to bypass the broken stub, and probes via a real sign-token + auth-bind round trip. Missing credentials now correctly report "missing App Key / App Secret".
• i18n — relabel app_key as "App Key" (was "Client ID") in both en.json and zh.json.
• tests — 28 unit tests covering the protobuf codec round trips, sign-token signature, parse_inbound, and the probe credential-validation path (no live network).

Protocol details were reverse-engineered from the official openclaw-plugin-yuanbao@2.17.0 proto descriptors and client, and verified against production.

Test plan

• make all — 1391 passed, 2 skipped
• make lint + make typecheck (mypy --strict, 334 files) clean
• Live smoke test with real credentials against bot.yuanbao.tencent.com: probe_yuanbao() ✅ → YuanbaoChannel.start() auth-bind success ✅ → heartbeat cycle ✅ → clean stop() ✅
• Full end-to-end: booted an Octop server, configured the Volcano Engine (Ark) provider with DeepSeek V4, attached the yuanbao channel, and confirmed a real user message in the 元宝 app was received and answered.

Follow-ups

• Once the TencentCloud/harness-gateway repository is accessible, this implementation ports almost verbatim into upstream (correct required_credentials + relocate the channel class), at which point the Octop-side shim can be dropped.
• Media upload (COS), typing heartbeat, and message chunking are intentionally not implemented; can be added on demand.

Changelog

Updated CHANGELOG.md under [Unreleased].

[Pandakingxbc]

Hi huangcheng,

Many thanks for your contribution. We also reviewed the issue you identified.

We noticed that the PR was closed, but you are very welcome to continue participating in the Octop community. We are starting a channel support testing and contribution activity around harness-gateway and Octop/Orca, and we would be happy to have your help.

The channel part is a good area to contribute: harness-gateway provides the unified BaseChannel / ChannelManager abstraction, while Octop/Orca integrates channels with agents, sessions, media, slash commands, HITL approvals, and proactive push.

We plan to test the following aspects:

1. Channel lifecycle: create, update, enable/disable, delete, start/stop, reconnect.
2. Credential probing: missing credentials, invalid credentials, successful connection checks.
3. Inbound messages: text, group/DM routing, mentions, duplicated messages, session isolation.
4. Outbound replies: normal replies, streaming deltas, long-response placeholders, typing indicators.
5. Media support: image, file, audio/video where supported, inbound persistence, outbound upload.
6. Proactive push: cron/task push, remembered routing metadata, stale/ephemeral metadata cleanup.
7. Octop integration: dashboard channel API, runtime status, DB persistence, per-agent channel binding.
8. Agent flow: channel message → Octop session/thread → HarnessAgent request → response back to channel.
9. Slash and HITL: /approve, /reject, /pending and tool-approval flows from IM channels.
10. Reliability and safety: rate limits, timeout handling, reconnect behavior, error messages, secret handling.

If you are interested, we can coordinate on one channel first and provide a concrete test checklist. we will open the harness-gateway in few weeks. Looking forward to your contribution.

[huangcheng]

Hi @Pandakingxbc,

Thanks a lot for the warm message — glad the review of the issue was useful.

Quick note on the closure: it was accidental. My fork was deleted by mistake, which auto-closed this PR (closed PRs with a deleted head repo can't be reopened), so I've resubmitted the same change as #36 (same commit 419d68b, same description). Happy to address any review feedback there.

I'd love to join the channel testing and contribution activity. The 10 areas you listed line up well with what I ran into while implementing the yuanbao channel — credential probing, inbound/outbound routing, reconnect/token-refresh behavior, and media upload (which I intentionally left out) all seem like great candidates for a shared test checklist.

Since yuanbao is the channel I know best right now (real app_key/app_secret sign-token + WSS protobuf protocol, verified end-to-end in production), I'd suggest we coordinate on it first — I can help write the concrete test checklist for it, and port the implementation upstream to harness-gateway once the repo opens up.

Looking forward to collaborating!