openclacky 1.0.3 → 1.0.5

data/lib/clacky/server/channel/adapters/telegram/api_client.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "net/https"
+require "openssl"
+require "securerandom"
+require "uri"
+
+module Clacky
+  module Channel
+    module Adapters
+      module Telegram
+        # Telegram Bot API HTTP client.
+        # Spec: https://core.telegram.org/bots/api
+        #
+        # All requests POST JSON to https://<base>/bot<TOKEN>/<method>.
+        # File downloads use https://<base>/file/bot<TOKEN>/<file_path>.
+        #
+        # `base_url` is configurable to allow self-hosted Bot API servers
+        # (https://github.com/tdlib/telegram-bot-api), which is the practical
+        # escape hatch for users on networks where api.telegram.org is blocked.
+        class ApiClient
+          DEFAULT_BASE_URL  = "https://api.telegram.org"
+          LONG_POLL_TIMEOUT = 25  # seconds; server holds the request open up to this long
+          OPEN_TIMEOUT      = 10
+          # Read timeout must comfortably exceed the long-poll window so we
+          # don't tear down healthy connections mid-poll.
+          POLL_READ_TIMEOUT = LONG_POLL_TIMEOUT + 10
+
+          class ApiError < StandardError
+            attr_reader :code, :description
+            def initialize(code, description)
+              @code = code
+              @description = description
+              super("Telegram API error #{code}: #{description}")
+            end
+          end
+
+          class TimeoutError < StandardError; end
+
+          def initialize(token:, base_url: DEFAULT_BASE_URL)
+            @token    = token.to_s
+            @base_url = (base_url.to_s.empty? ? DEFAULT_BASE_URL : base_url).chomp("/")
+          end
+
+          # Long-poll for updates. Returns the raw `result` array (possibly empty).
+          # `offset` is the highest update_id + 1 from the previous batch.
+          def get_updates(offset: nil, allowed_updates: %w[message])
+            params = { timeout: LONG_POLL_TIMEOUT, allowed_updates: allowed_updates }
+            params[:offset] = offset if offset
+            post("getUpdates", params, read_timeout: POLL_READ_TIMEOUT)
+          end
+
+          # Send a plain or Markdown-formatted message. Returns the Message hash.
+          def send_message(chat_id:, text:, parse_mode: nil, reply_to_message_id: nil, message_thread_id: nil, disable_web_page_preview: true)
+            params = {
+              chat_id:                  chat_id,
+              text:                     text,
+              disable_web_page_preview: disable_web_page_preview
+            }
+            params[:parse_mode]              = parse_mode          if parse_mode
+            params[:reply_to_message_id]     = reply_to_message_id if reply_to_message_id
+            params[:message_thread_id]       = message_thread_id   if message_thread_id
+            post("sendMessage", params)
+          end
+
+          # Edit the text of a previously sent message. Returns the edited Message hash.
+          def edit_message_text(chat_id:, message_id:, text:, parse_mode: nil, disable_web_page_preview: true)
+            params = {
+              chat_id:                  chat_id,
+              message_id:               message_id,
+              text:                     text,
+              disable_web_page_preview: disable_web_page_preview
+            }
+            params[:parse_mode] = parse_mode if parse_mode
+            post("editMessageText", params)
+          end
+
+          # Send a chat action (e.g. "typing") — auto-expires after 5s client-side.
+          def send_chat_action(chat_id:, action: "typing", message_thread_id: nil)
+            params = { chat_id: chat_id, action: action }
+            params[:message_thread_id] = message_thread_id if message_thread_id
+            post("sendChatAction", params)
+          end
+
+          # Send a photo by local file path. Returns the Message hash.
+          def send_photo(chat_id:, photo_path:, caption: nil, reply_to_message_id: nil)
+            params = { chat_id: chat_id }
+            params[:caption]             = caption             if caption
+            params[:reply_to_message_id] = reply_to_message_id if reply_to_message_id
+            post_multipart("sendPhoto", params, file_field: "photo", file_path: photo_path)
+          end
+
+          # Send a document (arbitrary file). Returns the Message hash.
+          def send_document(chat_id:, document_path:, filename: nil, caption: nil, reply_to_message_id: nil)
+            params = { chat_id: chat_id }
+            params[:caption]             = caption             if caption
+            params[:reply_to_message_id] = reply_to_message_id if reply_to_message_id
+            post_multipart("sendDocument", params, file_field: "document", file_path: document_path, filename: filename)
+          end
+
+          # Resolve a file_id to a file_path via getFile, then download the bytes.
+          # Returns the raw byte string.
+          def download_file(file_id)
+            file = post("getFile", { file_id: file_id })
+            path = file["file_path"]
+            raise ApiError.new(0, "getFile returned no file_path") if path.to_s.empty?
+
+            uri = URI("#{@base_url}/file/bot#{@token}/#{path}")
+            http_get_raw(uri)
+          end
+
+
+          def post(method_name, params, read_timeout: 30)
+            uri = URI("#{@base_url}/bot#{@token}/#{method_name}")
+            http = build_http(uri, read_timeout: read_timeout)
+
+            req = Net::HTTP::Post.new(uri.request_uri, "Content-Type" => "application/json")
+            req.body = JSON.generate(params)
+
+            res  = http.request(req)
+            body = parse_body(res)
+            unwrap(body, method_name)
+          rescue Net::ReadTimeout, Net::OpenTimeout
+            raise TimeoutError, "#{method_name} timed out"
+          end
+
+          def post_multipart(method_name, params, file_field:, file_path:, filename: nil)
+            uri      = URI("#{@base_url}/bot#{@token}/#{method_name}")
+            boundary = "----clacky-tg-#{SecureRandom.hex(8)}"
+            body     = String.new(encoding: "BINARY")
+
+            params.each do |k, v|
+              body << "--#{boundary}\r\n"
+              body << %(Content-Disposition: form-data; name="#{k}"\r\n\r\n)
+              body << v.to_s.dup.force_encoding("BINARY")
+              body << "\r\n"
+            end
+
+            file_bytes = File.binread(file_path)
+            body << "--#{boundary}\r\n"
+            body << %(Content-Disposition: form-data; name="#{file_field}"; filename="#{filename || File.basename(file_path)}"\r\n)
+            body << "Content-Type: #{mime_for(file_path)}\r\n\r\n"
+            body << file_bytes
+            body << "\r\n--#{boundary}--\r\n"
+
+            http = build_http(uri, read_timeout: 60)
+            req  = Net::HTTP::Post.new(uri.request_uri,
+                                       "Content-Type" => "multipart/form-data; boundary=#{boundary}")
+            req.body = body
+
+            unwrap(parse_body(http.request(req)), method_name)
+          end
+
+          def http_get_raw(uri)
+            http = build_http(uri, read_timeout: 60)
+            res  = http.request(Net::HTTP::Get.new(uri.request_uri))
+            unless res.is_a?(Net::HTTPSuccess)
+              raise ApiError.new(res.code.to_i, "GET #{uri.path} → HTTP #{res.code}: #{res.body.to_s.slice(0, 200)}")
+            end
+            res.body
+          rescue Net::ReadTimeout, Net::OpenTimeout
+            raise TimeoutError, "file download timed out"
+          end
+
+          def build_http(uri, read_timeout:)
+            http              = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl      = uri.scheme == "https"
+            http.verify_mode  = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+            http.open_timeout = OPEN_TIMEOUT
+            http.read_timeout = read_timeout
+            http
+          end
+
+          def parse_body(res)
+            JSON.parse(res.body)
+          rescue JSON::ParserError
+            raise ApiError.new(res.code.to_i, "non-JSON response from Telegram: #{res.body.to_s.slice(0, 200)}")
+          end
+
+          def unwrap(body, method_name)
+            if body["ok"]
+              body["result"]
+            else
+              raise ApiError.new(body["error_code"].to_i, "#{method_name}: #{body["description"]}")
+            end
+          end
+
+          def mime_for(path)
+            case File.extname(path).downcase
+            when ".png"           then "image/png"
+            when ".gif"           then "image/gif"
+            when ".webp"          then "image/webp"
+            when ".jpg", ".jpeg"  then "image/jpeg"
+            when ".pdf"           then "application/pdf"
+            when ".txt", ".md"    then "text/plain"
+            else                       "application/octet-stream"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/clacky/server/channel/channel_config.rb

@@ -109,6 +109,17 @@ module Clacky
           base_url:      raw["base_url"],
           allowed_users: raw["allowed_users"]
         }.compact
+      when :discord
+        {
+          bot_token:     raw["bot_token"]
+        }.compact
+      when :telegram
+        {
+          bot_token:     raw["bot_token"],
+          base_url:      raw["base_url"],
+          parse_mode:    raw.key?("parse_mode") ? raw["parse_mode"] : "Markdown",
+          allowed_users: raw["allowed_users"]
+        }.compact
       else
         # Unknown platform — pass all non-meta keys as symbol-keyed hash
         raw.reject { |k, _| k == "enabled" }

data/lib/clacky/server/channel.rb

@@ -24,6 +24,8 @@ require_relative "channel/adapters/base"
 require_relative "channel/adapters/feishu/adapter"
 require_relative "channel/adapters/wecom/adapter"
 require_relative "channel/adapters/weixin/adapter"
+require_relative "channel/adapters/discord/adapter"
+require_relative "channel/adapters/telegram/adapter"
 
 require_relative "channel/channel_config"
 require_relative "channel/channel_ui_controller"

data/lib/clacky/server/http_server.rb

@@ -57,7 +57,9 @@ module Clacky
       def show_assistant_message(content, files:)
         return if content.nil? || content.to_s.strip.empty?
 
-        @events << { type: "assistant_message", session_id: @session_id, content: content }
+        # Rewrite local image paths to /api/local-image proxy URLs for browser rendering
+        rewritten = Utils::FileProcessor.rewrite_local_image_urls(content.to_s)
+        @events << { type: "assistant_message", session_id: @session_id, content: rewritten }
       end
 
       def show_tool_call(name, args)
@@ -242,7 +244,15 @@ module Clacky
             Clacky::Logger.warn("[HttpServer] Forced exit after graceful shutdown timeout.")
             exit!(0)
           end
-          # Stop channel and browser managers in parallel to minimize shutdown time.
+          # Detach the inherited (shared) listen socket BEFORE shutdown so that
+          # WEBrick's cleanup_listener does not call shutdown(SHUT_RDWR)+close on
+          # it — that would propagate to every process sharing the underlying
+          # kernel socket (Master + new worker), breaking subsequent accept()
+          # on Linux. macOS's BSD stack tolerates this; Linux does not.
+          if @inherited_socket && server.listeners.include?(@inherited_socket)
+            server.listeners.delete(@inherited_socket)
+            Clacky::Logger.info("[HttpServer PID=#{Process.pid}] detached inherited socket fd=#{@inherited_socket.fileno} before shutdown")
+          end
           t1 = Thread.new { @channel_manager.stop rescue nil }
           t2 = Thread.new { Clacky::BrowserManager.instance.stop rescue nil }
           t1.join(1.5)
@@ -397,6 +407,7 @@ module Clacky
         when ["POST",   "/api/tool/browser"]      then api_tool_browser(req, res)
         when ["POST",   "/api/upload"]            then api_upload_file(req, res)
         when ["POST",   "/api/open-file"]         then api_open_file(req, res)
+        when ["GET",    "/api/local-image"]       then api_serve_local_image(req, res)
         when ["GET",    "/api/version"]           then api_get_version(res)
         when ["POST",   "/api/version/upgrade"]   then api_upgrade_version(req, res)
         when ["POST",   "/api/restart"]           then api_restart(req, res)
@@ -1002,10 +1013,14 @@ module Clacky
       def api_get_version(res)
         current = Clacky::VERSION
         latest  = fetch_latest_version_cached
+        brand   = Clacky::BrandConfig.load
+        cli_cmd = brand.branded? && brand.package_name && !brand.package_name.empty? ? brand.package_name : "openclacky"
         json_response(res, 200, {
           current:      current,
           latest:       latest,
-          needs_update: latest ? version_older?(current, latest) : false
+          needs_update: latest ? version_older?(current, latest) : false,
+          launcher:     ENV["CLACKY_LAUNCHER"] || "cli",
+          cli_command:  cli_cmd
         })
       end
 
@@ -1555,6 +1570,43 @@ module Clacky
         json_response(res, 500, { ok: false, error: e.message })
       end
 
+      # GET /api/local-image?path=file:///path/to/image.png
+      # GET /api/local-image?path=/path/to/image.png
+      #
+      # Serves a local image file with the correct Content-Type.
+      # Used by the Web UI to render local images that would otherwise be blocked
+      # by the browser's security policy (file:// from http:// origin).
+      #
+      def api_serve_local_image(req, res)
+        raw_path = URI.decode_www_form(req.query_string.to_s).to_h["path"].to_s
+        return json_response(res, 400, { error: "path is required" }) if raw_path.empty?
+
+        # Strip file:// prefix if present
+        path = raw_path.sub(%r{\Afile://}, "")
+        path = CGI.unescape(path)
+        path = File.expand_path(path)
+
+        # On WSL the file may be specified as a Windows path (e.g. "C:/Users/…").
+        # Convert it to the Linux-side path so File.exist? works.
+        path = Utils::EnvironmentDetector.win_to_linux_path(path)
+
+        # Security: only serve image files
+        ext = File.extname(path).downcase
+        unless Utils::FileProcessor::LOCAL_IMAGE_EXTENSIONS.include?(ext)
+          return json_response(res, 403, { error: "not an image file" })
+        end
+
+        return json_response(res, 404, { error: "file not found" }) unless File.exist?(path)
+
+        mime = Utils::FileProcessor::MIME_TYPES[ext] || "application/octet-stream"
+        res.status         = 200
+        res["Content-Type"] = mime
+        res["Cache-Control"] = "private, max-age=3600"
+        res.body = File.binread(path)
+      rescue => e
+        json_response(res, 500, { error: e.message })
+      end
+
       # POST /api/channels/:platform
       # Body: { fields... }  (platform-specific credential fields)
       # Saves credentials and optionally (re)starts the adapter.
@@ -1568,6 +1620,7 @@ module Clacky
 
         # Record when the token was last updated so clients can detect re-login
         fields[:token_updated_at] = Time.now.to_i if platform == :weixin && fields.key?(:token)
+        fields[:token_updated_at] = Time.now.to_i if platform == :discord && fields.key?(:bot_token)
 
         # Validate credentials against live API before persisting.
         # Merge with existing config so partial updates (e.g. allowed_users only) still validate correctly.
@@ -1649,6 +1702,19 @@ module Clacky
             has_token:         !raw["token"].to_s.strip.empty?,
             token_updated_at:  raw["token_updated_at"]  # Unix timestamp, nil if never set
           }
+        when :discord
+          {
+            allowed_users:    raw["allowed_users"] || [],
+            has_token:        !raw["bot_token"].to_s.strip.empty?,
+            token_updated_at: raw["token_updated_at"]
+          }
+        when :telegram
+          {
+            base_url:      raw["base_url"] || Clacky::Channel::Adapters::Telegram::ApiClient::DEFAULT_BASE_URL,
+            parse_mode:    raw.key?("parse_mode") ? raw["parse_mode"] : "Markdown",
+            allowed_users: raw["allowed_users"] || [],
+            has_token:     !raw["bot_token"].to_s.strip.empty?
+          }
         else
           {}
         end

data/lib/clacky/ui2/ui_controller.rb

@@ -733,8 +733,9 @@ module Clacky
         @legacy_progress_handles ||= {}
 
         if phase.to_s == "done"
-          handle = @legacy_progress_handles.delete(type)
+          handle = @legacy_progress_handles[type]
           handle&.finish(final_message: message)
+          @legacy_progress_handles.delete(type)
           return
         end
 

data/lib/clacky/utils/file_processor.rb

@@ -523,8 +523,79 @@ module Clacky
       nil
     end
 
+    # Image extensions that can be inlined as data URLs in markdown content.
+    LOCAL_IMAGE_EXTENSIONS = %w[.png .jpg .jpeg .gif .webp].freeze
+
+    # Replace local image paths in markdown content with base64 data URLs.
+    #
+    # Handles both `file:///path/to/img.png` and bare `/path/to/img.png` in
+    # markdown image syntax `![alt](src)`.
+    #
+    # @param content [String] markdown text potentially containing local image references
+    # @return [String] content with local images replaced by data URLs
+    def self.inline_local_images(content)
+      return content if content.nil? || content.empty?
+
+      content.gsub(%r{(!\[[^\]]*\])\((file://)?(/[^)]+)\)}) do
+        prefix     = $1
+        _scheme    = $2
+        raw_path   = $3
+        path       = CGI.unescape(raw_path)
+        ext        = File.extname(path).downcase
+        full_match = $&
+
+        unless LOCAL_IMAGE_EXTENSIONS.include?(ext) && File.exist?(path)
+          next full_match
+        end
+
+        begin
+          data_url = image_path_to_data_url(path)
+          Clacky::Logger.info("file_processor.inline_local_images", path: path, size: File.size(path))
+          "#{prefix}(#{data_url})"
+        rescue StandardError => e
+          Clacky::Logger.warn("file_processor.inline_local_images.failed", path: path, error: e.message)
+          full_match
+        end
+      end
+    end
+
     private_class_method :parse_zip_listing, :parse_tar_listing, :save_preview, :sanitize_filename,
                          :downscale_png_chunky, :downscale_via_cli
+
+    # -------------------------------------------------------------------------
+    # Local image URL rewriting
+    # -------------------------------------------------------------------------
+
+    # Rewrite local image paths in markdown content to use the /api/local-image proxy.
+    #
+    # Matches two patterns inside `![alt](url)`:
+    #   1. file:// URLs  →  ![alt](/api/local-image?path=file:///abs/path.png)
+    #   2. bare absolute paths  →  ![alt](/api/local-image?path=/abs/path.png)
+    #
+    # https:// URLs and non-image files are left untouched.
+    #
+    # @param content [String, nil] markdown text
+    # @return [String, nil] rewritten content (or original if nothing matched)
+    def self.rewrite_local_image_urls(content)
+      return content if content.nil? || content.empty?
+
+      content.gsub(/!\[([^\]]*)\]\(((?:file:\/\/)?\/[^)]+)\)/) do |match|
+        alt  = Regexp.last_match(1)
+        href = Regexp.last_match(2)
+
+        # Extract the filesystem path from the href
+        path = href.sub(%r{\Afile://}, "")
+        path = CGI.unescape(path)
+
+        ext = File.extname(path).downcase
+        if LOCAL_IMAGE_EXTENSIONS.include?(ext) && File.exist?(path)
+          encoded = CGI.escape(href)
+          "![#{alt}](/api/local-image?path=#{encoded})"
+        else
+          match # return original match unchanged
+        end
+      end
+    end
   end
   end
 end

data/lib/clacky/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clacky
-  VERSION = "1.0.3"
+  VERSION = "1.0.5"
 end

data/lib/clacky/web/app.css

@@ -5764,6 +5764,16 @@ body.setup-mode[data-theme="dark"] {
   color: #fff;
 }
 
+.channel-logo-discord {
+  background: linear-gradient(135deg, #5865f2, #4752c4);
+  color: #fff;
+}
+
+.channel-logo-telegram {
+  background: linear-gradient(135deg, #2aabee, #229ed9);
+  color: #fff;
+}
+
 .channel-card-name {
   font-size: 15px;
   font-weight: 600;
@@ -6210,6 +6220,40 @@ body.setup-mode[data-theme="dark"] {
   line-height: 1.5;
 }
 
+/* Restart-failed state — shows both recovery paths (tray + CLI) */
+.vup-restart-failed {
+  padding: 4px 0 2px;
+}
+.vup-restart-failed-title {
+  margin: 0 0 6px;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--color-error, #ef4444);
+}
+.vup-restart-failed-desc {
+  margin: 0 0 8px;
+  font-size: 12px;
+  color: var(--color-text-muted);
+  line-height: 1.5;
+}
+.vup-restart-failed-options {
+  margin: 0 0 10px;
+  padding-left: 18px;
+  font-size: 12px;
+  color: var(--color-text-primary);
+  line-height: 1.6;
+}
+.vup-restart-failed-options li + li {
+  margin-top: 4px;
+}
+.vup-cmd {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 11.5px;
+  background: var(--color-surface-muted, rgba(127,127,127,.12));
+  padding: 1px 6px;
+  border-radius: 4px;
+}
+
 
 
 /* ── Profile / My Data Panel ───────────────────────────────────────────────

data/lib/clacky/web/channels.js

@@ -35,6 +35,22 @@ const Channels = (() => {
         setupCmd:  "/channel-setup setup weixin",
         testCmd:   "/channel-setup doctor",
       },
+      discord: {
+        logo:      "D",
+        logoClass: "channel-logo-discord",
+        name:      "Discord",
+        desc:      I18n.t("channels.discord.desc"),
+        setupCmd:  "/channel-setup setup discord",
+        testCmd:   "/channel-setup doctor",
+      },
+      telegram: {
+        logo:      "T",
+        logoClass: "channel-logo-telegram",
+        name:      "Telegram",
+        desc:      I18n.t("channels.telegram.desc"),
+        setupCmd:  "/channel-setup setup telegram",
+        testCmd:   "/channel-setup doctor",
+      },
     };
   }
 

data/lib/clacky/web/i18n.js

@@ -130,6 +130,11 @@ const I18n = (() => {
       "upgrade.failed":            "Upgrade failed. Try again or run manually: gem update openclacky",
       "upgrade.reconnecting":      "Restarting server…",
       "upgrade.restart.success":   "✓ Restarted successfully!",
+      "upgrade.restart.timeout.title":   "Hot restart didn't complete",
+      "upgrade.restart.timeout.desc":    "The server didn't come back within 30 s. Please recover using one of the methods below:",
+      "upgrade.restart.timeout.tray":    "From the tray menu, choose “Quit” and start the app again.",
+      "upgrade.restart.timeout.cli":     "If you launched from a terminal, run: {{cmd}}",
+      "upgrade.restart.timeout.retry":   "Try Again",
       "upgrade.tooltip.upgrading":    "Upgrading — click to see progress",
       "upgrade.tooltip.new":         "v{{latest}} available — click to upgrade",
       "upgrade.tooltip.ok":          "v{{current}} (up to date)",
@@ -347,7 +352,7 @@ const I18n = (() => {
 
       // ── Channels panel ──
       "channels.title":           "Channels",
-      "channels.subtitle":        "Connect IM platforms so your users can chat with the assistant via Feishu, WeCom or Weixin",
+      "channels.subtitle":        "Connect IM platforms so your users can chat with the assistant via Feishu, WeCom, Weixin or Telegram",
       "channels.loading":         "Loading…",
       "channels.badge.running":         "Running",
       "channels.badge.enabled":         "Enabled",
@@ -368,6 +373,8 @@ const I18n = (() => {
       "channels.feishu.desc":     "Connect via Feishu open platform WebSocket long connection",
       "channels.wecom.desc":      "Connect via WeCom intelligent robot WebSocket",
       "channels.weixin.desc":     "Connect via WeChat iLink bot (QR login, HTTP long-poll)",
+      "channels.discord.desc":    "Connect via Discord bot, invite via OAuth2 authorization link",
+      "channels.telegram.desc":   "Connect via Telegram Bot API (HTTPS long-poll, token from @BotFather)",
 
       // ── Settings panel ──
       "settings.title":           "Settings",
@@ -383,6 +390,8 @@ const I18n = (() => {
       "settings.models.field.baseurl":    "Base URL",
       "settings.models.field.apikey":     "API Key",
       "settings.models.field.getApiKey":  "How to get →",
+      "settings.models.field.docsGuide.question": "New to AI keys?",
+      "settings.models.field.docsGuide.cta":      "See the guide →",
       "settings.models.placeholder.provider": "— Choose provider —",
       "settings.models.placeholder.model":    "e.g. claude-sonnet-4-5",
       "settings.models.placeholder.baseurl":  "https://api.anthropic.com",
@@ -471,6 +480,8 @@ const I18n = (() => {
       "onboard.key.baseurl":        "Base URL",
       "onboard.key.apikey":         "API Key",
       "onboard.key.getApiKey":      "How to get →",
+      "onboard.key.docsGuide.question": "New to AI keys?",
+      "onboard.key.docsGuide.cta":      "See the guide →",
       "onboard.key.btn.test":       "Test & Continue →",
       "onboard.key.btn.back":       "← Back",
       "onboard.provider.custom":    "Custom",
@@ -628,6 +639,11 @@ const I18n = (() => {
       "upgrade.failed":            "升级失败，请重试或手动执行：gem update openclacky",
       "upgrade.reconnecting":      "服务重启中…",
       "upgrade.restart.success":   "✓ 重启成功！",
+      "upgrade.restart.timeout.title":   "热重启未完成",
+      "upgrade.restart.timeout.desc":    "服务在 30 秒内未恢复。请通过以下任一方式重启：",
+      "upgrade.restart.timeout.tray":    "在系统托盘菜单中选择「退出」，然后重新打开应用。",
+      "upgrade.restart.timeout.cli":     "如果是终端启动，请执行命令： {{cmd}}",
+      "upgrade.restart.timeout.retry":   "重试",
       "upgrade.tooltip.upgrading":    "升级中，点击查看进度",
       "upgrade.tooltip.new":         "v{{latest}} 可用，点击升级",
       "upgrade.tooltip.ok":          "v{{current}}（已是最新）",
@@ -844,7 +860,7 @@ const I18n = (() => {
 
       // ── Channels panel ──
       "channels.title":           "频道",
-      "channels.subtitle":        "连接即时通讯平台，让用户通过飞书、企业微信或微信与助手对话",
+      "channels.subtitle":        "连接即时通讯平台，让用户通过飞书、企业微信、微信或 Telegram 与助手对话",
       "channels.loading":         "加载中…",
       "channels.loadError":       "加载频道失败：{{msg}}",
       "channels.badge.running":         "运行中",
@@ -865,6 +881,8 @@ const I18n = (() => {
       "channels.feishu.desc":     "通过飞书开放平台 WebSocket 长连接接入",
       "channels.wecom.desc":      "通过企业微信智能机器人 WebSocket 接入",
       "channels.weixin.desc":     "通过微信 iLink 机器人接入（扫码登录，HTTP 长轮询）",
+      "channels.discord.desc":    "通过 Discord 机器人接入，授权链接邀请 Bot 加入服务器",
+      "channels.telegram.desc":   "通过 Telegram Bot API 接入（HTTPS 长轮询，token 来自 @BotFather）",
 
       // ── Settings panel ──
       "settings.title":           "设置",
@@ -880,6 +898,8 @@ const I18n = (() => {
       "settings.models.field.baseurl":    "Base URL",
       "settings.models.field.apikey":     "API Key",
       "settings.models.field.getApiKey":  "如何获取 →",
+      "settings.models.field.docsGuide.question": "不会配置 AI 模型？",
+      "settings.models.field.docsGuide.cta":      "查看指南 →",
       "settings.models.placeholder.provider": "— 选择服务商 —",
       "settings.models.placeholder.model":    "如 claude-sonnet-4-5",
       "settings.models.placeholder.baseurl":  "https://api.anthropic.com",
@@ -968,6 +988,8 @@ const I18n = (() => {
       "onboard.key.baseurl":        "Base URL",
       "onboard.key.apikey":         "API Key",
       "onboard.key.getApiKey":      "如何获取 →",
+      "onboard.key.docsGuide.question": "不会配置 AI 模型？",
+      "onboard.key.docsGuide.cta":      "查看指南 →",
       "onboard.key.btn.test":       "测试并继续 →",
       "onboard.key.btn.back":       "← 返回",
       "onboard.provider.custom":    "自定义",

data/lib/clacky/web/index.html

@@ -883,7 +883,12 @@
         </div>
       </div>
 
-      <div id="setup-test-result" class="setup-test-result"></div>
+      <div class="setup-docs-hint" style="font-size:12px;margin-top:2px;text-align:left;">
+        <span style="color:var(--muted,#6b7280);" data-i18n="onboard.key.docsGuide.question">New to AI keys?</span>
+        <a id="setup-docs-link" href="https://www.openclacky.com/docs/ai-key-guide" target="_blank" rel="noopener" style="margin-left:4px;color:var(--accent,#6366f1);text-decoration:none;" data-i18n="onboard.key.docsGuide.cta">See the guide →</a>
+      </div>
+
+      <div id="setup-test-result" class="setup-test-result" style="min-height:0;"></div>
 
       <div class="setup-key-actions">
         <button id="setup-btn-back" class="setup-back-btn" data-i18n="onboard.key.btn.back">← Back</button>

data/lib/clacky/web/settings.js

@@ -141,6 +141,10 @@ const Settings = (() => {
       </div>
 
       <div class="model-card-footer">
+        ${!model.api_key_masked ? `<span class="model-card-docs-link" style="font-size:12px;">
+          <span style="color:var(--muted,#6b7280);">${I18n.t("settings.models.field.docsGuide.question")}</span>
+          <a href="https://www.openclacky.com/docs/ai-key-guide" target="_blank" rel="noopener" style="margin-left:4px;color:var(--accent,#6366f1);text-decoration:none;">${I18n.t("settings.models.field.docsGuide.cta")}</a>
+        </span>` : ""}
         <span class="model-test-result" data-index="${index}"></span>
         <div class="model-card-actions-row">
           ${!isDefault ? `<button class="btn-set-default" data-index="${index}" title="${I18n.t("settings.models.btn.setDefault")}">${I18n.t("settings.models.btn.setDefault")}</button>` : ""}