feat(channels/zalo): OA OAuth + webhook transport (#966)

CLAUDE.md

@@ -89,6 +89,7 @@ ui/desktop/                   Wails v2 desktop app (React frontend + embedded ga
 - **Config:** JSON5 at `GOCLAW_CONFIG` env. Secrets in `.env.local` or env vars, never in config.json
 - **Security:** Rate limiting, input guard (detection-only), CORS, shell deny patterns, SSRF protection, path traversal prevention, AES-256-GCM encryption. All security logs: `slog.Warn("security.*")`
 - **Telegram formatting:** LLM output → `SanitizeAssistantContent()` → `markdownToTelegramHTML()` → `chunkHTML()` → `sendHTML()`. Tables rendered as ASCII in `<pre>` tags
+- **Reply-to plumbing:** `metadata["reply_to_message_id"]` is the cross-channel reply key. Stamped on group inbound (telegram, pancake comments) by default; opted-in per channel for DMs via `channels.DMQuoteChannel` (currently `zalo_oa` only). Channel `Send` translates the key to platform-specific payload — Telegram `ReplyParameters`, Zalo OA `message.quote_message_id`, Pancake `comment_id`. First chunk only; media sends drop quote. Zalo OA silently retries without quote on `FamilyPayload` errors (expired/deleted source).
 - **i18n:** Web UI uses `i18next` with namespace-split locale files in `ui/web/src/i18n/locales/{lang}/`. Backend uses `internal/i18n` message catalog with `i18n.T(locale, key, args...)`. Locale propagated via `store.WithLocale(ctx)` — WS `connect` param `locale`, HTTP `Accept-Language` header. Supported: en (default), vi, zh. New user-facing strings: add key to `internal/i18n/keys.go`, add translations to all 3 catalog files. New UI strings: add key to all 3 locale dirs. Bootstrap templates (SOUL.md, etc.) stay English-only (LLM consumption).
 
 ## Running

cmd/gateway.go

@@ -27,7 +27,8 @@ import (
 	slackchannel "github.com/nextlevelbuilder/goclaw/internal/channels/slack"
 	"github.com/nextlevelbuilder/goclaw/internal/channels/telegram"
 	"github.com/nextlevelbuilder/goclaw/internal/channels/whatsapp"
-	"github.com/nextlevelbuilder/goclaw/internal/channels/zalo"
+	zalobot "github.com/nextlevelbuilder/goclaw/internal/channels/zalo/bot"
+	zalooa "github.com/nextlevelbuilder/goclaw/internal/channels/zalo/oa"
 	zalopersonal "github.com/nextlevelbuilder/goclaw/internal/channels/zalo/personal"
 	"github.com/nextlevelbuilder/goclaw/internal/config"
 	"github.com/nextlevelbuilder/goclaw/internal/edition"
@@ -460,7 +461,8 @@ func runGateway() {
 		instanceLoader.RegisterFactory(channels.TypeTelegram, telegram.FactoryWithStoresAndAudio(pgStores.Agents, pgStores.ConfigPermissions, pgStores.Teams, pgStores.SubagentTasks, pgStores.PendingMessages, audioMgr))
 		instanceLoader.RegisterFactory(channels.TypeDiscord, discord.FactoryWithStoresAndAudio(pgStores.Agents, pgStores.ConfigPermissions, pgStores.PendingMessages, audioMgr))
 		instanceLoader.RegisterFactory(channels.TypeFeishu, feishu.FactoryWithPendingStoreAndAudio(pgStores.PendingMessages, audioMgr))
-		instanceLoader.RegisterFactory(channels.TypeZaloOA, zalo.Factory)
+		instanceLoader.RegisterFactory(channels.TypeZaloBot, zalobot.Factory)
+		instanceLoader.RegisterFactory(channels.TypeZaloOA, zalooa.Factory(pgStores.ChannelInstances))
 		instanceLoader.RegisterFactory(channels.TypeZaloPersonal, zalopersonal.FactoryWithPendingStore(pgStores.PendingMessages))
 		instanceLoader.RegisterFactory(channels.TypeWhatsApp, whatsapp.FactoryWithDBAudio(pgStores.DB, pgStores.PendingMessages, "pgx", audioMgr, pgStores.BuiltinTools))
 		instanceLoader.RegisterFactory(channels.TypeSlack, slackchannel.FactoryWithPendingStore(pgStores.PendingMessages))

cmd/gateway_channels_setup.go

@@ -17,7 +17,7 @@ import (
 	slackchannel "github.com/nextlevelbuilder/goclaw/internal/channels/slack"
 	"github.com/nextlevelbuilder/goclaw/internal/channels/telegram"
 	"github.com/nextlevelbuilder/goclaw/internal/channels/whatsapp"
-	"github.com/nextlevelbuilder/goclaw/internal/channels/zalo"
+	zalobot "github.com/nextlevelbuilder/goclaw/internal/channels/zalo/bot"
 	zalopersonal "github.com/nextlevelbuilder/goclaw/internal/channels/zalo/personal"
 	"github.com/nextlevelbuilder/goclaw/internal/channels/zalo/personal/zalomethods"
 	"github.com/nextlevelbuilder/goclaw/internal/config"
@@ -86,12 +86,12 @@ func registerConfigChannels(cfg *config.Config, channelMgr *channels.Manager, ms
 
 	if cfg.Channels.Zalo.Enabled {
 		if cfg.Channels.Zalo.Token == "" {
-			recordMissingConfig(channels.TypeZaloOA, "Set channels.zalo.token in config.")
-		} else if z, err := zalo.New(cfg.Channels.Zalo, msgBus, pgStores.Pairing); err != nil {
-			channelMgr.RecordFailure(channels.TypeZaloOA, "", err)
+			recordMissingConfig(channels.TypeZaloBot, "Set channels.zalo.token in config.")
+		} else if z, err := zalobot.New(cfg.Channels.Zalo, msgBus, pgStores.Pairing); err != nil {
+			channelMgr.RecordFailure(channels.TypeZaloBot, "", err)
 			slog.Error("failed to initialize zalo channel", "error", err)
 		} else {
-			channelMgr.RegisterChannel(channels.TypeZaloOA, z)
+			channelMgr.RegisterChannel(channels.TypeZaloBot, z)
 			slog.Info("zalo channel enabled (config)")
 		}
 	}
@@ -152,6 +152,8 @@ func wireChannelRPCMethods(server *gateway.Server, pgStores *store.Stores, chann
 	// Register channel instances WS RPC methods
 	if pgStores.ChannelInstances != nil {
 		methods.NewChannelInstancesMethods(pgStores.ChannelInstances, pgStores.Agents, msgBus, msgBus).Register(server.Router())
+		methods.NewZaloOAMethods(pgStores.ChannelInstances, msgBus).Register(server.Router())
+		methods.NewZaloWebhookMethods(pgStores.ChannelInstances).Register(server.Router())
 		zalomethods.NewQRMethods(pgStores.ChannelInstances, msgBus).Register(server.Router())
 		zalomethods.NewContactsMethods(pgStores.ChannelInstances).Register(server.Router())
 		whatsapp.NewQRMethods(pgStores.ChannelInstances, channelMgr).Register(server.Router())

cmd/gateway_consumer_normal.go

@@ -215,12 +215,7 @@ func processNormalMessage(
 
 	// Build outbound metadata for reply-to + thread routing BEFORE RegisterRun
 	// so block.reply handler can use it for routing intermediate messages.
-	outMeta := channels.CopyFinalRoutingMeta(msg.Metadata)
-	if isGroup {
-		if mid := msg.Metadata["message_id"]; mid != "" {
-			outMeta["reply_to_message_id"] = mid
-		}
-	}
+	outMeta := buildOutboundReplyMeta(msg.Metadata, msg.Channel, isGroup, deps.ChannelMgr)
 
 	// Register run with channel manager for streaming/reaction event forwarding.
 	// Use localKey (composite key with topic suffix) so streaming/reaction events
@@ -529,3 +524,21 @@ func processNormalMessage(
 		}
 	}(agentID, msg.Channel, msg.ChatID, sessionKey, runID, peerKind, msg.Content, outMeta, blockReply, ptd, msg.TenantID, agentLoop.UUID(), agentLoop.OtherConfig())
 }
+
+// buildOutboundReplyMeta clones routing metadata and stamps reply_to_message_id
+// on group inbounds (always) and DM inbounds for channels that opt into the
+// DMQuoteChannel capability.
+func buildOutboundReplyMeta(in map[string]string, channelName string, isGroup bool, mgr *channels.Manager) map[string]string {
+	out := channels.CopyFinalRoutingMeta(in)
+	mid := in["message_id"]
+	if mid == "" {
+		return out
+	}
+	switch {
+	case isGroup:
+		out["reply_to_message_id"] = mid
+	case mgr != nil && mgr.QuoteInboundOnDM(channelName):
+		out["reply_to_message_id"] = mid
+	}
+	return out
+}

cmd/gateway_consumer_reply_meta_test.go

@@ -0,0 +1,84 @@
+package cmd
+
+import (
+	"context"
+	"testing"
+
+	"github.com/nextlevelbuilder/goclaw/internal/bus"
+	"github.com/nextlevelbuilder/goclaw/internal/channels"
+)
+
+// quoteOptInChannel implements channels.Channel + channels.DMQuoteChannel.
+type quoteOptInChannel struct{ name string }
+
+func (q *quoteOptInChannel) Name() string                                          { return q.name }
+func (q *quoteOptInChannel) Type() string                                          { return q.name }
+func (q *quoteOptInChannel) Start(ctx context.Context) error                       { return nil }
+func (q *quoteOptInChannel) Stop(ctx context.Context) error                        { return nil }
+func (q *quoteOptInChannel) Send(ctx context.Context, _ bus.OutboundMessage) error { return nil }
+func (q *quoteOptInChannel) IsRunning() bool                                       { return true }
+func (q *quoteOptInChannel) IsAllowed(_ string) bool                               { return true }
+func (q *quoteOptInChannel) QuoteInboundOnDM() bool                                { return true }
+
+// plainChannel implements only Channel.
+type plainChannel struct{ name string }
+
+func (p *plainChannel) Name() string                                          { return p.name }
+func (p *plainChannel) Type() string                                          { return p.name }
+func (p *plainChannel) Start(ctx context.Context) error                       { return nil }
+func (p *plainChannel) Stop(ctx context.Context) error                        { return nil }
+func (p *plainChannel) Send(ctx context.Context, _ bus.OutboundMessage) error { return nil }
+func (p *plainChannel) IsRunning() bool                                       { return true }
+func (p *plainChannel) IsAllowed(_ string) bool                               { return true }
+
+func TestBuildOutboundReplyMeta_DMOptedIn(t *testing.T) {
+	t.Parallel()
+	mgr := channels.NewManager(bus.New())
+	mgr.RegisterChannel("zalo_oa", &quoteOptInChannel{name: "zalo_oa"})
+
+	out := buildOutboundReplyMeta(map[string]string{"message_id": "mid-1"}, "zalo_oa", false, mgr)
+	if out["reply_to_message_id"] != "mid-1" {
+		t.Errorf("reply_to_message_id = %q, want mid-1", out["reply_to_message_id"])
+	}
+}
+
+func TestBuildOutboundReplyMeta_DMNotOptedIn(t *testing.T) {
+	t.Parallel()
+	mgr := channels.NewManager(bus.New())
+	mgr.RegisterChannel("telegram", &plainChannel{name: "telegram"})
+
+	out := buildOutboundReplyMeta(map[string]string{"message_id": "mid-1"}, "telegram", false, mgr)
+	if _, ok := out["reply_to_message_id"]; ok {
+		t.Errorf("reply_to_message_id must not be stamped on telegram DM, got out=%v", out)
+	}
+}
+
+func TestBuildOutboundReplyMeta_GroupAlwaysStamps(t *testing.T) {
+	t.Parallel()
+	mgr := channels.NewManager(bus.New())
+	mgr.RegisterChannel("telegram", &plainChannel{name: "telegram"})
+
+	out := buildOutboundReplyMeta(map[string]string{"message_id": "mid-2"}, "telegram", true, mgr)
+	if out["reply_to_message_id"] != "mid-2" {
+		t.Errorf("group must stamp regardless of capability; got %q", out["reply_to_message_id"])
+	}
+}
+
+func TestBuildOutboundReplyMeta_NoMessageID(t *testing.T) {
+	t.Parallel()
+	mgr := channels.NewManager(bus.New())
+	mgr.RegisterChannel("zalo_oa", &quoteOptInChannel{name: "zalo_oa"})
+
+	out := buildOutboundReplyMeta(map[string]string{}, "zalo_oa", false, mgr)
+	if _, ok := out["reply_to_message_id"]; ok {
+		t.Errorf("missing message_id must not produce a quote; got out=%v", out)
+	}
+}
+
+func TestBuildOutboundReplyMeta_NilManager(t *testing.T) {
+	t.Parallel()
+	out := buildOutboundReplyMeta(map[string]string{"message_id": "x"}, "anything", false, nil)
+	if _, ok := out["reply_to_message_id"]; ok {
+		t.Errorf("nil manager DM must not stamp; got out=%v", out)
+	}
+}

cmd/gateway_errors.go

@@ -94,6 +94,7 @@ func isExternalChannel(channelType string) bool {
 		channels.TypeDiscord,
 		channels.TypeFeishu,
 		channels.TypeWhatsApp,
+		channels.TypeZaloBot,
 		channels.TypeZaloOA,
 		channels.TypeZaloPersonal,
 		channels.TypePancake,

cmd/gateway_errors_test.go

@@ -24,6 +24,7 @@ func TestIsExternalChannel(t *testing.T) {
 		{"discord", channels.TypeDiscord, true},
 		{"feishu", channels.TypeFeishu, true},
 		{"whatsapp", channels.TypeWhatsApp, true},
+		{"zalo_bot", channels.TypeZaloBot, true},
 		{"zalo_oa", channels.TypeZaloOA, true},
 		{"zalo_personal", channels.TypeZaloPersonal, true},
 		{"pancake", channels.TypePancake, true},

cmd/gateway_lifecycle.go

@@ -3,13 +3,15 @@ package cmd
 import (
 	"context"
 	"log/slog"
+	"net/http"
 	"os"
 	"strings"
 	"time"
 
 	"github.com/nextlevelbuilder/goclaw/internal/bus"
 	"github.com/nextlevelbuilder/goclaw/internal/cache"
 	"github.com/nextlevelbuilder/goclaw/internal/channels"
+	zalocommon "github.com/nextlevelbuilder/goclaw/internal/channels/zalo/common"
 	"github.com/nextlevelbuilder/goclaw/internal/config"
 	"github.com/nextlevelbuilder/goclaw/internal/edition"
 	"github.com/nextlevelbuilder/goclaw/internal/heartbeat"
@@ -207,10 +209,26 @@ func (d *gatewayDeps) runLifecycle(
 
 	// Mount channel webhook handlers on the main mux (e.g. Feishu /feishu/events).
 	// This allows webhook-based channels to share the main server port.
+	zaloPrefixMounted := false
 	for _, route := range d.channelMgr.WebhookHandlers() {
 		mux.Handle(route.Path, route.Handler)
 		slog.Info("webhook route mounted on gateway", "path", route.Path)
+		if route.Path == zalocommon.WebhookPathPrefix {
+			zaloPrefixMounted = true
+		}
+	}
+	// Always mount the Zalo webhook prefix so wizard-created channels added
+	// after boot are reachable without restart. The shared router 404s
+	// unknown slugs, so an unmounted-yet-registered channel never silently
+	// drops. Bare /channels/zalo/webhook always returns 404 to avoid the
+	// http.ServeMux 301 redirect leaking the prefix path.
+	if !zaloPrefixMounted {
+		mux.Handle(zalocommon.WebhookPathPrefix, zalocommon.SharedRouter())
+		slog.Info("webhook route mounted on gateway", "path", zalocommon.WebhookPathPrefix, "source", "shared_router_default")
 	}
+	mux.HandleFunc(zalocommon.WebhookPathBare, func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "not found", http.StatusNotFound)
+	})
 
 	tsCleanup := initTailscale(ctx, d.cfg, mux)
 	if tsCleanup != nil {

docker-compose.selfservice.yml

@@ -9,6 +9,12 @@
 #   # or: make up WITH_WEB_NGINX=1
 #
 # Dashboard via nginx: http://localhost:3000
+#
+# NOTE: nginx.conf uses a static `upstream goclaw_backend` block, which
+# resolves the backend hostname only once at config load. K8s with a stable
+# Service ClusterIP is fine. In docker-compose, if the backend container is
+# recreated and gets a new IP, restart the UI container to refresh the
+# resolution: `docker compose restart goclaw-ui`.
 
 services:
   goclaw-ui:

docker-compose.yml

@@ -47,8 +47,10 @@ services:
       - GOCLAW_GATEWAY_TOKEN=${GOCLAW_GATEWAY_TOKEN:-}
       - GOCLAW_ENCRYPTION_KEY=${GOCLAW_ENCRYPTION_KEY:-}
       - GOCLAW_SKILLS_DIR=/app/data/skills
+      - GOCLAW_AUTO_UPGRADE=${GOCLAW_AUTO_UPGRADE:-true}
       # Debug
       - GOCLAW_TRACE_VERBOSE=${GOCLAW_TRACE_VERBOSE:-0}
+      - GOCLAW_LOG_LEVEL=${GOCLAW_LOG_LEVEL:-info}
     volumes:
       - goclaw-data:/app/data
       - goclaw-workspace:/app/workspace

docs/00-architecture-overview.md

@@ -14,6 +14,7 @@ flowchart TD
         TG[Telegram]
         DC[Discord]
         FS[Feishu / Lark]
+        ZB[Zalo Bot]
         ZL[Zalo OA]
         ZLP[Zalo Personal]
         WA[WhatsApp]
@@ -77,7 +78,7 @@ flowchart TD
 
     WS --> WSS
     HTTP --> HTTPS
-    TG & DC & FS & ZL & ZLP & WA & SL --> CM
+    TG & DC & FS & ZB & ZL & ZLP & WA & SL --> CM
 
     WSS --> MR
     HTTPS --> MR
@@ -113,7 +114,7 @@ flowchart TD
 | `internal/bootstrap/` | System prompt files (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, BOOTSTRAP.md) + seeding + truncation |
 | `internal/config/` | Config loading (JSON5) + env var overlay |
 | `internal/skills/` | SKILL.md loader (5-tier hierarchy) + BM25 search + hot-reload via fsnotify |
-| `internal/channels/` | Channel manager + adapters: Telegram (forum topics, STT, bot commands), Feishu/Lark (streaming cards, media), Zalo OA, Zalo Personal, Discord, WhatsApp, Slack |
+| `internal/channels/` | Channel manager + adapters: Telegram (forum topics, STT, bot commands), Feishu/Lark (streaming cards, media), Zalo Bot (static-token), Zalo OA (OAuth), Zalo Personal, Discord, WhatsApp, Slack |
 | `internal/mcp/` | MCP server bridge (stdio, SSE, streamable-HTTP transports) |
 | `internal/scheduler/` | Lane-based concurrency control (main, subagent, cron, team lanes) with per-session serialization. Per-edition rate limits (`MaxSubagentConcurrent`, `MaxSubagentDepth`) with tenant-scoped concurrency |
 | `internal/memory/` | Memory system (pgvector hybrid search) |