openclacky 1.5.17 → 1.5.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23761f95ba9b1fa52c2acc37020fd4e903a92d8f49c0c97668d5cfbb6e572329
-  data.tar.gz: 16838f20ba7d650e15952c738c35b93ca418a8df81baaeb6f9fd0263c5754e65
+  metadata.gz: bdaf1f7be658187d9515e3fcd1ca37a1ec8bdf04267b434a4d5722c3cbee3970
+  data.tar.gz: a7a62edc84b707407fd06b186627b1a705a8e9977b60b88453e23759dc43f4b4
 SHA512:
-  metadata.gz: d0a29e5ab8a0e6b21e1f2a2f36657bcb8043cfc9d904671acdead8157f082ac032c2d1f7f0a0cee16c0f72a7fdbb939020b3abfe52145a9eea722f4f4856bac2
-  data.tar.gz: '050389221f4f71ab6e54a6038606f0d1f48f1a6571116c5b052493362158a850fe0f1a90a4d520b35fff875315fd1292610bab104366251626d5d9fdcb5b7f54'
+  metadata.gz: 574f85b7317b21b2d231f009405275a6aa77df9758bd2bb9d861a948d1bf35f32d876c1c154fb87f8248786490734aab84a6568ba522e37e840913216510f504
+  data.tar.gz: 6509de425a59612b5fad807c172affad49bee4da8b83d59ba9a204c3355814c1ef8f1b8ee233bee43755c624c3bbf4b9c7278378bf3b68e7faebcfc7096a6530

data/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
+## [1.5.19] - 2026-10-10
+
+### Added
+- Add the built-in QQ official-bot channel (#615 - @chengoak)
+- Drag a session onto a project to move it (#610)
+- Add bookmarks to the chat navigator and tighten its layout (#617)
+- Scroll an overflowing session title on hover so it can be read in full (#618)
+- Add session lifecycle hooks (#607)
+- Rework the billing charts with a year heatmap and a 365-day range
+- Add an "Add Model" button to the model picker
+- Show an API Key hint in the model dialog and restyle the key link
+- Add oc-glm-5.3 and oc-kimi-k3 aliases with pricing and capability caps
+- Add abs-claude-sonnet-5-5 and abs-gpt-6.1-sol with corrected pricing
+- Add Xiaomi MiMo V2.6 models (#614)
+- Add the oc-minimax-m2.7 alias with its launch discount
+- Show a GLM/Kimi series promotion with a badge in the model picker
+- Forward Seedance reference images over the OpenAI-compatible video gateway (#616 - @codevoyager1984)
+- Document the input image limits and the content_filter retry in the media skill (#593 - @codevoyager1984)
+
+### Improved
+- Make the model picker visually distinct from the variant switcher
+- Explain model price discounts with a tooltip
+- Soften the chat navigator tick color
+- Hide the skills tab strip when only one tab is available
+- Tune the billing chart axis labels
+- Clarify ambient audio generation in the media skill (#606 - @YeEmrick)
+
+### Fixed
+- Stop the workspace file tree from flickering on reload
+- Deliver web-originated replies to IM after a finished progress card (#603, #605 - @chengoak)
+- Fall back to gem update when the OSS CDN fails (#583, #608 - @theluckystrike)
+- Keep the chat position when toggling preview fullscreen (#613)
+- Stop opening an empty variant panel for custom models
+- Use a white background for the context bar popovers
+- Point a rate limit error at switching models
+- Skip reasoning fields for non-Anthropic Converse models
+
+### More
+- Rename the billing panel title to Usage
+- Use 服务商 instead of 供应商 in model settings
+
+## [1.5.18] - 2026-10-02
+
+### Fixed
+- Tell users to switch to another model when a model request fails
+
 ## [1.5.17] - 2026-09-30
 
 ### Added

data/docs/session-observation-hooks.md

@@ -0,0 +1,86 @@
+# Agent task lifecycle hooks
+
+## Task lifecycle: on_start / on_complete
+
+> Availability: the additional context and abnormal completion paths require
+> the runtime change on branch `session-lifecycle-hooks`. They are not
+> available in 1.5.16. Upgrade the runtime before relying on these fields.
+
+Use the existing events without extra configuration. `on_start` runs after task
+and history initialization, before execution, and retains `deny` / `handled`.
+`on_complete` observes the outcome of each Agent turn, including normal completion,
+waiting, handled starts, denial, exceptions and interruption. Its return value is
+ignored, including `deny` and `handled`; all completion callbacks can run.
+
+Ruby callbacks receive `(input, agent, context)` or `(result, agent, context)`.
+The first two positions are unchanged; ordinary two-argument Ruby blocks ignore
+the extra argument. Existing completion callbacks must check `result[:status] ==
+:success` before doing success-only work. A handled result has `context[:handled]`
+set to true; skip follow-up work already performed by the handler.
+
+These are Agent-turn events for server, CLI and channel execution, not server
+persistence notifications. Queued input emits start only when consumed; steering
+inside an active turn does not create an extra start or completion. Automatic goal
+continuations have their own turn events. Normal completion fires before goal
+continuation, and exceptions still propagate after notification. A superseded
+turn's exception cleanup cannot settle its successor.
+
+Context contains `session_id`, `run_id` (process-local task ID, not durable),
+`source` (execution source, not authenticated identity), `input_created_at` (the
+optional timestamp passed to `run`), `observed_at` (UTC ISO8601), and `status`.
+Start status is `running`. No input text is added to context; input and result
+arguments can contain sensitive data.
+
+| Completion context status | Meaning |
+|---------------------------|---------|
+| `completed` | Result explicitly has `status: :success`, without a feedback request. This does not certify App generation or validation. |
+| `awaiting_user` | Successful result requests `awaiting_user_feedback`. |
+| `failed` | Exception or non-success result. Structured exceptions can supply `error_code`. |
+| `cancelled` | Interruption or denial. `reason` may be `user`, `replacement`, `hook_denied` or `tool_denied`. |
+
+Cancelled completion notifications carry `result[:status] == :cancelled`, even
+when the original denial return value remains unchanged for queue compatibility.
+An execution start alone does not establish recovery from a previous failure.
+
+```yaml
+id: session-observer
+name: Session Observer
+version: "0.1.0"
+contributes:
+  hooks:
+    - event: on_start
+      file: hooks/start.rb
+    - event: on_complete
+      file: hooks/complete.rb
+```
+
+```ruby
+# hooks/start.rb
+Clacky::ExtensionHookRegistry.add do |_input, _agent, context|
+  next unless context
+  Clacky::Logger.debug("[session-observer] started", session_id: context[:session_id],
+                       run_id: context[:run_id])
+  nil
+end
+```
+
+```ruby
+# hooks/complete.rb
+Clacky::ExtensionHookRegistry.add do |_result, _agent, context|
+  next unless context
+  Clacky::Logger.debug("[session-observer] settled", session_id: context[:session_id],
+                       status: context[:status], run_id: context[:run_id])
+  nil
+end
+```
+
+Use separate files for separate registrations: each Ruby file is required only
+once. Programmatic registration uses `agent.add_hook(:on_complete) { |result,
+agent, context| ... }`. Shell hooks keep their JSON payload shape; neither the
+Agent nor context is serialized, while abnormal completion results are now reported.
+
+Callbacks execute synchronously; keep them short and dispatch network work
+asynchronously. `StandardError` is logged without stopping later callbacks.
+The host does not persist, retry, replay or acknowledge hook delivery. Consumers
+must tolerate missing events and cannot infer inactivity solely from missing data.
+`agent.emit_event(persist: true)` is a separate frontend-history feature.

data/lib/clacky/agent/chunk_index.rb

@@ -41,6 +41,7 @@ module Clacky
         nested = []
         section_count = 0
         user_start = nil
+        user_task_id = nil
         archived_at = nil
         front_matter = false
         directory = File.dirname(path)
@@ -61,6 +62,7 @@ module Clacky
               section_count += 1
               nested << header[:nested_chunk] if header[:nested_chunk]
               user_start = header[:role] == "user" ? start : nil
+              user_task_id = header[:role] == "user" ? header[:task_id] : nil
             elsif user_start && !text.strip.empty?
               # Match replay's empty/metadata-only user handling without
               # retaining the rest of the user message or any assistant text.
@@ -69,8 +71,9 @@ module Clacky
               next if visible.empty? && events.empty? && files.empty?
 
               rounds.last[:length] = user_start - rounds.last[:start] if rounds.any?
-              rounds << { start: user_start }
+              rounds << { start: user_start, task_id: user_task_id }
               user_start = nil
+              user_task_id = nil
             end
           end
           rounds.last[:length] = position - rounds.last[:start] if rounds.any?

data/lib/clacky/agent/history_navigation.rb

@@ -12,7 +12,12 @@ module Clacky
         manifest = sources.map do |source|
           entry = { key: source[:key], version: source[:version], count: navigation_source_count(source),
                     volatile: !!source[:rounds] || source[:continuation].to_a.any? }
-          entry[:identities] = source[:rounds].map { |round| round[:user_msg].values_at(:created_at, :task_id) } if source[:rounds]
+          if source[:rounds]
+            entry[:identities] = source[:rounds].map { |round| round[:user_msg].values_at(:created_at, :task_id) }
+          else
+            task_ids = source[:index][:rounds].map { |round| round[:task_id] }
+            entry[:task_ids] = task_ids if task_ids.any?
+          end
           entry
         end
         { sources: manifest, total: manifest.sum { |source| source[:count] } }

data/lib/clacky/agent/hook_manager.rb

@@ -26,20 +26,27 @@ module Clacky
 
     # @return [Hash] `{action: :allow}`, `{action: :deny, reason:}`, or
     #   `{action: :handled, result:}` when a hook fulfilled the event itself.
-    # on_start receives (user_input, agent) after task/history initialization.
+    # on_start receives (user_input, agent, context) after task/history initialization.
     # Its handled result is returned unchanged from Agent#run; the extension
     # supplies the run-result status and any queue/feedback flags it needs.
     # on_start is not fired for steering input inside an already running turn.
-    # Extra trailing arg: the agent that owns this hook chain, so ext hooks can
+    # The agent follows the event payload, so ext hooks can
     # call `agent.emit_event(...)`. Blocks are procs — those declaring fewer
-    # params (`|call|`, `|call, result|`) silently ignore it.
+    # params (`|call|`, `|call, result|`) silently ignore extra arguments.
+    # Start/complete append context after the agent. Completion is observation-only.
     def trigger(event, *args)
       validate_event!(event)
+      # Keep payload hashes positional: Ruby 2.6 otherwise promotes their keys
+      # into keyword arguments, breaking existing tool hooks.
+      context = args.pop if [:on_start, :on_complete].include?(event) && args.length == 2
       result = { action: :allow }
 
       @hooks[event].each do |hook|
         begin
-          hook_result = hook.call(*args, @agent)
+          callback_args = [*args, @agent]
+          callback_args << context.dup if context
+          hook_result = hook.call(*callback_args)
+          next if event == :on_complete
           next unless hook_result.is_a?(Hash)
           # First deny wins and stops the chain: a weaker later verdict must
           # never clobber a stronger earlier one, and the first deny's reason

data/lib/clacky/agent.rb

@@ -490,6 +490,8 @@ module Clacky
       # method-level and must be able to reference them on any exit path.
       result = nil
       run_turn_started = false
+      completion_sent = false
+      run_context = nil
 
       # Intercept /goal ... commands before any task/LLM work. Control-plane
       # commands (status/pause/resume/clear) return immediately without a turn;
@@ -520,6 +522,9 @@ module Clacky
 
       # Start new task for Time Machine
       task_id = start_new_task(title: display_text.to_s.empty? ? user_input.to_s : display_text.to_s)
+      run_context = { session_id: @session_id, run_id: task_id.to_s,
+                      source: @source.to_s, input_created_at: created_at,
+                      observed_at: Time.now.utc.iso8601(6), status: "running" }
 
       # Continuation of a previously-interrupted task (e.g. user sent a
       # supplementary message without stopping the running task) keeps the
@@ -589,13 +594,15 @@ module Clacky
       @input_mutex.synchronize { @accepting_steering = true }
       notify_input_queue
       # The task and user history already exist. A terminal verdict skips the
-      # loop and completion hooks; ensure still cleans up this started turn.
-      hook_result = @hooks.trigger(:on_start, user_input)
+      # loop; ensure still reports completion and cleans up this started turn.
+      hook_result = @hooks.trigger(:on_start, user_input, run_context)
       case hook_result[:action]
       when :deny
+        run_context[:reason] = "hook_denied"
         @ui&.show_warning(hook_result[:reason] || "Task denied by hook")
         return result = build_result.merge(queue_paused: true)
       when :handled
+        run_context[:handled] = true
         return result = hook_result[:result]
       end
 
@@ -793,6 +800,7 @@ module Clacky
       notify_input_queue
       result = build_result(awaiting_user_feedback: awaiting_user_feedback)
       result[:queue_paused] = true if awaiting_user_feedback || task_interrupted
+      run_context[:reason] = "tool_denied" if task_interrupted
 
       # Run skill evolution hooks after main loop completes
       # Skip if task was interrupted by user (denied tool) or awaiting user feedback
@@ -825,7 +833,8 @@ module Clacky
           awaiting_user_feedback: awaiting_user_feedback
         )
       end
-      @hooks.trigger(:on_complete, result)
+      completion_sent = true
+      complete_run_hook(result, run_context)
 
       # Standing-goal loop: after a completed turn, ask the judge whether the
       # goal is met. If not (and budget/health allow), auto-run the next turn
@@ -840,6 +849,8 @@ module Clacky
       result[:queue_paused] = true if @goal_manager&.state&.paused?
       result
     rescue Clacky::AgentInterrupted
+      result = { status: :cancelled }
+      run_context[:reason] = (Thread.current[:interrupt_reason] || :user).to_s if run_context
       # A cancelled fan-out captured its subagents' progress but never reached
       # observe() to persist it — anchor those trails now so a page reload
       # after the interrupt still shows what the subagents did.
@@ -852,6 +863,7 @@ module Clacky
       # Let CLI handle the interrupt message
       raise
     rescue StandardError => e
+      run_context[:error_code] = e.error_code if run_context && e.respond_to?(:error_code)
       # Log complete error information to debug_logs for troubleshooting
       @debug_logs << {
         timestamp: Time.now.iso8601,
@@ -871,6 +883,11 @@ module Clacky
       result = build_result(:error, error: e.message)
       raise
     ensure
+      # A recursive goal continuation owns its own completion. Do not let an
+      # unwinding predecessor settle a newer turn or report the same turn twice.
+      if run_context && !completion_sent && task_id == @current_task_id
+        complete_run_hook(result, run_context)
+      end
       if run_turn_started && task_id == @current_task_id
         @input_mutex.synchronize do
           @accepting_steering = false
@@ -888,6 +905,25 @@ module Clacky
       Clacky::Telemetry.task!(result: result) if run_turn_started
     end
 
+    private def complete_run_hook(result, context)
+      result = { status: :error } unless result.is_a?(Hash)
+      cancelled = context[:reason] || [:cancelled, :interrupted].include?(result[:status])
+      status = if cancelled
+                 "cancelled"
+               elsif result[:status] != :success
+                 "failed"
+               elsif result[:awaiting_user_feedback]
+                 "awaiting_user"
+               else
+                 "completed"
+               end
+      # Denied work can retain its historical return value for queue control,
+      # but completion observers must never interpret it as a successful run.
+      notification = cancelled ? result.merge(status: :cancelled) : result
+      @hooks.trigger(:on_complete, notification,
+                     context.merge(status: status, observed_at: Time.now.utc.iso8601(6)))
+    end
+
     # Shared by initial input and steering; only the execution thread writes history.
     private def append_user_input(user_input, files: nil, reference_contexts: nil,
                                   display_text: nil, created_at: nil, references_display: nil,

data/lib/clacky/billing/platform_billing.rb

@@ -24,6 +24,7 @@ module Clacky
         "dsk-deepseek-v4-flash-vision-exp" => "deepseek-v4-flash-vision-exp",
         # gpt via bedrock (abs-, OpenAI-compatible endpoint)
         "abs-gpt-6-astra"  => "global.openai.gpt-6-astra",
+        "abs-gpt-6.1-sol"  => "global.openai.gpt-6.1-sol",
         "abs-gpt-6-sol"    => "global.openai.gpt-6-sol",
         "abs-gpt-6-luna"   => "global.openai.gpt-6-luna",
         "abs-gpt-5.6-sol"   => "global.openai.gpt-5.6-sol",
@@ -37,10 +38,18 @@ module Clacky
         "abs-claude-opus-4-8"   => "global.anthropic.claude-opus-4-8",
         "abs-claude-opus-4-7"   => "global.anthropic.claude-opus-4-7",
         "abs-claude-opus-4-6"   => "global.anthropic.claude-opus-4-6",
+        "abs-claude-sonnet-5-5" => "global.anthropic.claude-sonnet-5-5",
         "abs-claude-sonnet-5"   => "global.anthropic.claude-sonnet-5",
         "abs-claude-sonnet-4-6" => "global.anthropic.claude-sonnet-4-6",
         "abs-claude-sonnet-4-5" => "global.anthropic.claude-sonnet-4-5",
         "abs-claude-haiku-4-5"  => "global.anthropic.claude-haiku-4-5",
+        # GLM / Kimi / MiniMax via TokHub (oc-). The gateway books these under
+        # the alias itself, so the mapping is an identity — it exists so the
+        # billing UI can resolve the alias instead of dropping the record as
+        # unknown.
+        "oc-glm-5.3"            => "oc-glm-5.3",
+        "oc-kimi-k3"            => "oc-kimi-k3",
+        "oc-minimax-m2.7"       => "oc-minimax-m2.7",
         # gemini chat (or-)
         "or-gemini-3-1-pro"   => "gemini-3.1-pro-preview",
         "or-gemini-3-8-flash" => "gemini-3.8-flash",

data/lib/clacky/default_extensions/advisor/hooks/advisor.rb

@@ -127,7 +127,7 @@ module Clacky
       # rounds with no tool calls at all (e.g. the very first "hi"). The
       # pending event is emitted synchronously so the UI can show a "working"
       # state immediately instead of the card popping in out of nowhere.
-      def finish_run
+      def finish_run(analyze: true)
         snapshot = @mutex.synchronize do
           snap = {
             tools: @tools_this_run,
@@ -139,6 +139,7 @@ module Clacky
           @tools_this_run = 0
           snap
         end
+        return unless analyze
         Clacky::Logger.info("[Advisor] finish_run",
                             session: @agent.session_id.to_s,
                             tools: snapshot[:tools],

data/lib/clacky/default_extensions/advisor/hooks/advisor_complete.rb

@@ -4,8 +4,9 @@ require_relative "advisor"
 
 # on_complete: a run has ended — reset the per-run analysis budget so the
 # next run starts fresh.
-Clacky::ExtensionHookRegistry.add do |_result, agent|
+Clacky::ExtensionHookRegistry.add do |result, agent, context|
   next unless Clacky::Advisor.enabled_for?(agent)
 
-  Clacky::Advisor.worker_for(agent).finish_run
+  successful = result.is_a?(Hash) && result[:status] == :success && !context&.dig(:handled)
+  Clacky::Advisor.worker_for(agent).finish_run(analyze: successful)
 end

data/lib/clacky/default_skills/channel-manager/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: channel-manager
 name_zh: 渠道管理
-description_zh: 接入飞书、企业微信、微信、钉钉、Discord、Telegram 等 IM 渠道，支持配置、启停、诊断和发消息。
+description_zh: 接入飞书、企业微信、微信、钉钉、Discord、Telegram、QQ 等 IM 渠道，支持配置、启停、诊断和发消息。
 description: |
-  Configure IM platform channels (Feishu, WeCom, Weixin, Discord, Telegram, DingTalk) for openclacky.
+  Configure IM platform channels (Feishu, WeCom, Weixin, Discord, Telegram, DingTalk, QQ) for openclacky.
   Uses browser automation for navigation; guides the user to paste credentials and perform UI steps.
-  Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "setup discord", "setup telegram", "setup dingtalk",
+  Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "setup discord", "setup telegram", "setup dingtalk", "setup qq",
   "channel config", "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor",
-  "send message to weixin", "send message to feishu", "send message to wecom", "send message to discord", "send message to telegram", "send message to dingtalk".
+  "send message to weixin", "send message to feishu", "send message to wecom", "send message to discord", "send message to telegram", "send message to dingtalk", "send message to qq".
   Subcommands: setup, status, enable <platform>, disable <platform>, reconfigure, doctor, send.
 argument-hint: "setup | status | enable <platform> | disable <platform> | reconfigure | doctor | send <platform> <message>"
 allowed-tools:
@@ -30,13 +30,13 @@ Configure IM platform channels for openclacky.
 
 | User says | Subcommand |
 |---|---|
-| `channel setup`, `setup feishu`, `setup wecom`, `setup weixin`, `setup wechat`, `setup discord`, `setup telegram`, `setup dingtalk` | setup |
+| `channel setup`, `setup feishu`, `setup wecom`, `setup weixin`, `setup wechat`, `setup discord`, `setup telegram`, `setup dingtalk`, `setup qq` | setup |
 | `channel status` | status |
-| `channel enable feishu/wecom/weixin/discord/telegram/dingtalk` | enable |
-| `channel disable feishu/wecom/weixin/discord/telegram/dingtalk` | disable |
+| `channel enable feishu/wecom/weixin/discord/telegram/dingtalk/qq` | enable |
+| `channel disable feishu/wecom/weixin/discord/telegram/dingtalk/qq` | disable |
 | `channel reconfigure` | reconfigure |
 | `channel doctor` | doctor |
-| `send <message> to weixin/feishu/wecom/discord/telegram/dingtalk` | send |
+| `send <message> to weixin/feishu/wecom/discord/telegram/dingtalk/qq` | send |
 
 ---
 
@@ -80,6 +80,7 @@ dingtalk   ✅ yes    ✅ yes    client_id: ding_xxx...
 - 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)
+- QQ: show `app_id` (truncated to 12 chars) and `sandbox: true/false`
 
 If the API is unreachable or returns an empty list: "No channels configured yet. Run `/channel-manager setup` to get started."
 
@@ -96,6 +97,7 @@ Ask:
 > 4. Discord
 > 5. Telegram (Bot API)
 > 6. DingTalk
+> 7. QQ (official bot, C2C & group @)
 
 ---
 
@@ -391,6 +393,56 @@ On success:
 
 ---
 
+### QQ setup (official QQ bot)
+
+QQ bots are created on the QQ Open Platform (q.qq.com). The user registers a bot, enables the C2C / group-message scopes, and pastes the App ID / App Secret here. The adapter connects over the QQ Gateway WebSocket; no browser automation is required from this skill.
+
+#### Step 1 — Create the bot on the QQ Open Platform
+
+Tell the user (localize if they are chatting in Chinese):
+
+> 1. Open the QQ Open Platform: https://q.qq.com (sandbox testing: use the sandbox toggle / sandbox AppID in the bot admin console).
+> 2. Register / log in and create a robot (机器人). After creation you will find **AppID** and **AppSecret** in the bot's "开发设置 / Development Settings" page.
+> 3. In "功能配置 / 配置" (or the sandbox panel), make sure the bot has the private-chat (C2C) and group @ message permissions enabled; add yourself as a sandbox tester if you are testing before release.
+> 4. Paste the credentials back here in one line:
+>
+> `app_id=YOUR_APPID app_secret=YOUR_APPSECRET sandbox=true_or_false`
+
+Wait for the reply. Parse with tolerant regex (`app_id=\S+`, `app_secret=\S+`, `sandbox=(true|false)`; default `sandbox=false` when omitted).
+
+Optionally validate the credentials before saving (best-effort; requires outbound access to api.bot.qq.com). The token endpoint is shared by production and sandbox — only the openapi host differs — so validation takes no `--sandbox` flag:
+
+```bash
+ruby "SKILL_DIR/qq_setup.rb" --validate "<APP_ID> <APP_SECRET>"
+```
+
+#### Step 2 — Save credentials
+
+The server persists the credentials and immediately opens the gateway WebSocket:
+
+```bash
+curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/qq \
+  -H "Content-Type: application/json" \
+  -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","sandbox":<TRUE_OR_FALSE>}'
+```
+
+- `200` — credentials saved; the QQ gateway session starts.
+- `4xx` — show the returned error (bad AppID/Secret, or permission not granted) and offer to retry.
+
+#### Step 3 — Verify
+
+Tell the user:
+
+> ✅ QQ channel configured. Send your bot a private message, or @ it in a group.
+>
+> Notes:
+> - Before release, only accounts added as sandbox testers can reach the bot.
+> - QQ bots reply in the passive window (5 minutes after the user's message); very long tasks may reply after the window closes.
+> - Channel (频道 / guild) messages are parsed but outbound replies are not supported yet — use C2C or groups.
+> - Optional: restrict who can use the bot via the `allowed_users` list (QQ openid values).
+
+---
+
 ## `enable`
 
 Call the server API to re-enable the platform (this reads from disk, sets enabled, saves, and hot-reloads):
@@ -466,6 +518,7 @@ Check each item, report ✅ / ❌ with remediation:
    - Weixin: `token` present and non-empty in `channels.yml`
    - Discord: `bot_token` present and non-empty in `channels.yml`
    - Telegram: `bot_token` present and non-empty
+   - QQ: `app_id`, `app_secret` present and non-empty
 3. **Feishu credentials** (if enabled) — run the token API call, check `code=0`.
 4. **Weixin token** (if enabled) — call `GET /api/channels` and check `has_token: true` for the weixin entry.
 5. **Telegram credentials** (if enabled) — call `getMe` against the Bot API:
@@ -495,6 +548,13 @@ Check each item, report ✅ / ❌ with remediation:
    ```
    - `WebSocket connected` → ✅
    - `Stream endpoint error` or `token error` → ❌ "DingTalk credentials invalid — re-run setup"
+8. **QQ credentials** (if enabled) — search today's log:
+   ```bash
+   grep -iE "QQ gateway|qq gateway|gateway ready|AppID|app_id.*invalid" \
+     ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log
+   ```
+   - gateway ready / identified → ✅
+   - invalid app_id / app_secret or identify failed → ❌ "QQ credentials invalid — re-run setup"
 
 ---
 
@@ -505,7 +565,7 @@ Proactively send a message to a user via an IM channel adapter.
 ### Parse the request
 
 Extract two things from the user's instruction:
-- **platform** — one of `weixin`, `feishu`, `wecom`, `discord`, `telegram`, `dingtalk`
+- **platform** — one of `weixin`, `feishu`, `wecom`, `discord`, `telegram`, `dingtalk`, `qq`
 - **message** — the text content to send
 
 If the platform cannot be inferred, ask the user to clarify.
@@ -545,6 +605,7 @@ curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/
 ### Constraints & notes
 
 - **Weixin (iLink protocol)**: Every outbound message requires a `context_token` that is obtained from the most recent inbound message from that user. The token is cached in memory and reset on server restart. If the server was restarted since the user last wrote, the token is gone and the send will fail — the user must message the bot again.
+- **QQ**: C2C/group replies reuse the recent inbound `msg_id` (passive reply window, ~5 minutes); proactive sends outside that window may be rejected.
 - **Feishu / WeCom / Discord / Telegram**: No per-message token required. As long as the adapter is running and the `user_id` / `chat_id` (or Discord channel/user id) is valid, the message will be delivered. For Telegram specifically, the `user_id` must be a Telegram chat_id that the bot can write to — the user must have sent at least one message to the bot first.
 - This feature is intended for **proactive notifications** (e.g. task completion, reminders). It is not a replacement for the normal reply flow triggered by inbound messages.
 

data/lib/clacky/default_skills/channel-manager/qq_setup.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# QQ channel setup helper for the channel-manager skill.
+#
+# Usage:
+#   qq_setup.rb --validate "<APP_ID> <APP_SECRET>" [--sandbox]
+#
+# Exchanges the AppID/AppSecret for a bot access_token via the QQ Open
+# Platform, so the skill can validate credentials BEFORE posting them to the
+# server API. Prints a small JSON document on success; exits non-zero with an
+# error message on failure. Uses only the Ruby standard library.
+
+require "json"
+require "net/http"
+require "uri"
+
+PORTAL_URL = "https://q.qq.com"
+# The token endpoint is shared by production and sandbox ("不区分正式环境、沙箱环境");
+# only the openapi host differs.
+TOKEN_URL = "https://api.bot.qq.com/app/getAppAccessToken"
+
+def fail!(message)
+  warn({ "ok" => false, "error" => message }.to_json)
+  exit 1
+end
+
+def print_usage
+  warn "Usage: #{$PROGRAM_NAME} --validate \"<APP_ID> <APP_SECRET>\" [--sandbox]"
+  warn "       #{$PROGRAM_NAME} --portal-url"
+  exit 2
+end
+
+def parse_pair(pair)
+  app_id, app_secret = pair.to_s.split(/\s+/, 2)
+  fail!("missing app_id or app_secret") if app_id.nil? || app_id.empty? || app_secret.nil? || app_secret.empty?
+  [app_id, app_secret]
+end
+
+def request_token(app_id, app_secret)
+  uri = URI(TOKEN_URL)
+  http = Net::HTTP.new(uri.host, uri.port)
+  http.use_ssl = true
+  http.open_timeout = 10
+  http.read_timeout = 10
+
+  req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
+  req.body = { appId: app_id, clientSecret: app_secret }.to_json
+  http.request(req)
+end
+
+def parse_body(res)
+  JSON.parse(res.body)
+rescue JSON::ParserError
+  fail!("non-JSON response (HTTP #{res.code})")
+end
+
+def validate!(pair, sandbox: false)
+  app_id, app_secret = parse_pair(pair)
+  res = request_token(app_id, app_secret)
+  data = parse_body(res)
+  if res.is_a?(Net::HTTPSuccess) && data["access_token"]
+    puts({ "ok" => true, "app_id" => app_id, "sandbox" => sandbox, "expires_in" => data["expires_in"] }.to_json)
+  else
+    fail!(data["message"] || data["msg"] || "token request failed (HTTP #{res.code})")
+  end
+end
+
+mode = ARGV.first
+print_usage if mode.nil?
+
+case mode
+when "--portal-url"
+  puts PORTAL_URL
+when "--validate"
+  validate!(ARGV[1], sandbox: ARGV.include?("--sandbox"))
+else
+  print_usage
+end