@chrysb/alphaclaw 0.1.25 → 0.2.0

package/lib/server/constants.js

@@ -264,6 +264,7 @@ const SETUP_API_PREFIXES = [
   "/api/openclaw",
   "/api/devices",
   "/api/sync-cron",
+  "/api/telegram",
 ];
 
 module.exports = {

package/lib/server/helpers.js

@@ -63,6 +63,8 @@ const normalizeIp = (ip) => String(ip || "").replace(/^::ffff:/, "");
 
 const isTruthyEnvFlag = (value) =>
   ["1", "true", "yes", "on"].includes(String(value || "").trim().toLowerCase());
+const isDebugEnabled = () =>
+  isTruthyEnvFlag(process.env.ALPHACLAW_DEBUG) || isTruthyEnvFlag(process.env.DEBUG);
 
 const getClientKey = (req) =>
   normalizeIp(
@@ -172,6 +174,33 @@ const readGoogleCredentials = () => {
   }
 };
 
+const kSecretKeyMatchers = [
+  /(?:^|_)TOKEN(?:$|_)/i,
+  /(?:^|_)API_KEY(?:$|_)/i,
+  /(?:^|_)PASSWORD(?:$|_)/i,
+  /(?:^|_)SECRET(?:$|_)/i,
+  /(?:^|_)PRIVATE_KEY(?:$|_)/i,
+];
+
+const isSensitiveKey = (key) =>
+  kSecretKeyMatchers.some((matcher) => matcher.test(String(key || "")));
+
+const buildSecretReplacements = (...sources) => {
+  const replacements = [];
+  const seen = new Set();
+  for (const source of sources) {
+    for (const [rawKey, rawValue] of Object.entries(source || {})) {
+      const key = String(rawKey || "").trim();
+      const value = String(rawValue || "");
+      if (!key || !value || !isSensitiveKey(key)) continue;
+      if (seen.has(value)) continue;
+      seen.add(value);
+      replacements.push([value, `\${${key}}`]);
+    }
+  }
+  return replacements.sort((a, b) => b[0].length - a[0].length);
+};
+
 module.exports = {
   normalizeOpenclawVersion,
   compareVersionParts,
@@ -180,6 +209,7 @@ module.exports = {
   getCodexAccountId,
   normalizeIp,
   isTruthyEnvFlag,
+  isDebugEnabled,
   getClientKey,
   resolveGithubRepoUrl,
   createPkcePair,
@@ -189,4 +219,6 @@ module.exports = {
   getBaseUrl,
   getApiEnableUrl,
   readGoogleCredentials,
+  isSensitiveKey,
+  buildSecretReplacements,
 };

package/lib/server/onboarding/github.js

@@ -1,5 +1,4 @@
-const ensureGithubRepoAccessible = async ({ repoUrl, repoName, remoteUrl, githubToken }) => {
-  void remoteUrl;
+const ensureGithubRepoAccessible = async ({ repoUrl, repoName, githubToken }) => {
   const ghHeaders = {
     Authorization: `token ${githubToken}`,
     "User-Agent": "openclaw-railway",

package/lib/server/onboarding/index.js

@@ -5,7 +5,6 @@ const { ensureGithubRepoAccessible } = require("./github");
 const { buildOnboardArgs, writeSanitizedOpenclawConfig } = require("./openclaw");
 const { installControlUiSkill, syncBootstrapPromptFiles } = require("./workspace");
 const { installHourlyGitSyncScript, installHourlyGitSyncCron } = require("./cron");
-const { isTruthyEnvFlag } = require("../helpers");
 
 const createOnboardingService = ({
   fs,
@@ -43,12 +42,11 @@ const createOnboardingService = ({
     writeEnvFile(varsToSave);
     reloadEnv();
 
-    const remoteUrl = `https://${githubToken}@github.com/${repoUrl}.git`;
+    const remoteUrl = `https://github.com/${repoUrl}.git`;
     const [, repoName] = repoUrl.split("/");
     const repoCheck = await ensureGithubRepoAccessible({
       repoUrl,
       repoName,
-      remoteUrl,
       githubToken,
     });
     if (!repoCheck.ok) {
@@ -103,11 +101,15 @@ const createOnboardingService = ({
 
     installControlUiSkill({ fs, openclawDir: OPENCLAW_DIR, baseUrl: getBaseUrl(req) });
 
-    const shouldForcePush = isTruthyEnvFlag(process.env.OPENCLAW_DEBUG_FORCE_PUSH);
-    const pushArgs = shouldForcePush ? "-u --force" : "-u";
     await shellCmd(
-      `cd ${OPENCLAW_DIR} && git add -A && git commit -m "initial setup" && git push ${pushArgs} origin main`,
-      { timeout: 30000 },
+      `alphaclaw git-sync -m "initial setup"`,
+      {
+        timeout: 30000,
+        env: {
+          ...process.env,
+          GITHUB_TOKEN: githubToken,
+        },
+      },
     ).catch((e) => console.error("[onboard] Git push error:", e.message));
     console.log("[onboard] Initial state committed and pushed");
 

package/lib/server/onboarding/openclaw.js

@@ -1,3 +1,5 @@
+const { buildSecretReplacements } = require("../helpers");
+
 const buildOnboardArgs = ({ varMap, selectedProvider, hasCodexOauth, workspaceDir }) => {
   const onboardArgs = [
     "--non-interactive",
@@ -149,18 +151,9 @@ const writeSanitizedOpenclawConfig = ({ fs, openclawDir, varMap }) => {
   }
 
   let content = JSON.stringify(cfg, null, 2);
-  const replacements = [
-    [process.env.OPENCLAW_GATEWAY_TOKEN, "${OPENCLAW_GATEWAY_TOKEN}"],
-    [varMap.ANTHROPIC_API_KEY, "${ANTHROPIC_API_KEY}"],
-    [varMap.ANTHROPIC_TOKEN, "${ANTHROPIC_TOKEN}"],
-    [varMap.TELEGRAM_BOT_TOKEN, "${TELEGRAM_BOT_TOKEN}"],
-    [varMap.DISCORD_BOT_TOKEN, "${DISCORD_BOT_TOKEN}"],
-    [varMap.OPENAI_API_KEY, "${OPENAI_API_KEY}"],
-    [varMap.GEMINI_API_KEY, "${GEMINI_API_KEY}"],
-    [varMap.BRAVE_API_KEY, "${BRAVE_API_KEY}"],
-  ];
+  const replacements = buildSecretReplacements(varMap, process.env);
   for (const [secret, envRef] of replacements) {
-    if (secret && secret.length > 8) {
+    if (secret) {
       content = content.split(secret).join(envRef);
     }
   }

package/lib/server/onboarding/workspace.js

@@ -1,5 +1,6 @@
 const path = require("path");
-const { kSetupDir } = require("../constants");
+const { kSetupDir, OPENCLAW_DIR } = require("../constants");
+const { renderTopicRegistryMarkdown } = require("../topic-registry");
 
 const resolveSetupUiUrl = (baseUrl) => {
   const normalizedBaseUrl = String(baseUrl || "").trim().replace(/\/+$/, "");
@@ -19,16 +20,38 @@ const resolveSetupUiUrl = (baseUrl) => {
   return "http://localhost:3000";
 };
 
+// Single assembly point for TOOLS.md: template + topic registry.
+// Idempotent — always rebuilds from source so deploys never clobber topic data.
+const isTelegramWorkspaceEnabled = (fs) => {
+  try {
+    const configPath = `${OPENCLAW_DIR}/openclaw.json`;
+    const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    return Object.keys(cfg.channels?.telegram?.groups || {}).length > 0;
+  } catch {
+    return false;
+  }
+};
+
 const syncBootstrapPromptFiles = ({ fs, workspaceDir, baseUrl }) => {
   try {
+    const setupUiUrl = resolveSetupUiUrl(baseUrl);
     const bootstrapDir = `${workspaceDir}/hooks/bootstrap`;
     fs.mkdirSync(bootstrapDir, { recursive: true });
     fs.copyFileSync(path.join(kSetupDir, "core-prompts", "AGENTS.md"), `${bootstrapDir}/AGENTS.md`);
+
     const toolsTemplate = fs.readFileSync(path.join(kSetupDir, "core-prompts", "TOOLS.md"), "utf8");
-    const toolsContent = toolsTemplate.replace(
+    let toolsContent = toolsTemplate.replace(
       /\{\{SETUP_UI_URL\}\}/g,
-      resolveSetupUiUrl(baseUrl),
+      setupUiUrl,
     );
+
+    const topicSection = renderTopicRegistryMarkdown({
+      includeSyncGuidance: isTelegramWorkspaceEnabled(fs),
+    });
+    if (topicSection) {
+      toolsContent += topicSection;
+    }
+
     fs.writeFileSync(`${bootstrapDir}/TOOLS.md`, toolsContent);
     console.log("[onboard] Bootstrap prompt files synced");
   } catch (e) {

package/lib/server/routes/auth.js

@@ -2,7 +2,8 @@ const crypto = require("crypto");
 const { kLoginCleanupIntervalMs } = require("../constants");
 
 const registerAuthRoutes = ({ app, loginThrottle }) => {
-  const SETUP_PASSWORD = process.env.SETUP_PASSWORD || "";
+  const SETUP_PASSWORD = String(process.env.SETUP_PASSWORD || "").trim();
+  const kAuthMisconfigured = !SETUP_PASSWORD;
   const kSessionTtlMs = 7 * 24 * 60 * 60 * 1000;
 
   const signSessionPayload = (payload) =>
@@ -50,7 +51,13 @@ const registerAuthRoutes = ({ app, loginThrottle }) => {
   };
 
   app.post("/api/auth/login", (req, res) => {
-    if (!SETUP_PASSWORD) return res.json({ ok: true });
+    if (kAuthMisconfigured) {
+      return res.status(503).json({
+        ok: false,
+        error:
+          "Server misconfigured: SETUP_PASSWORD is missing. Set it in your deployment environment variables and restart.",
+      });
+    }
     const now = Date.now();
     const clientKey = loginThrottle.getClientKey(req);
     const state = loginThrottle.getOrCreateLoginAttemptState(clientKey, now);
@@ -92,18 +99,29 @@ const registerAuthRoutes = ({ app, loginThrottle }) => {
   }, kLoginCleanupIntervalMs).unref();
 
   const isAuthorizedRequest = (req) => {
-    if (!SETUP_PASSWORD) return true;
+    if (kAuthMisconfigured) return false;
     const requestPath = req.path || "";
     if (requestPath.startsWith("/auth/google/callback")) return true;
     if (requestPath.startsWith("/auth/codex/callback")) return true;
     const cookies = cookieParser(req);
-    const query = req.query || {};
-    const token = cookies.setup_token || query.token;
+    const token = cookies.setup_token;
     return verifySessionToken(token);
   };
 
   const requireAuth = (req, res, next) => {
-    if (!SETUP_PASSWORD) return next();
+    if (kAuthMisconfigured) {
+      if (req.path.startsWith("/api/")) {
+        return res.status(503).json({
+          error:
+            "Server misconfigured: SETUP_PASSWORD is missing. Set it in your deployment environment variables and restart.",
+        });
+      }
+      return res
+        .status(503)
+        .send(
+          "Setup auth is not configured. Set SETUP_PASSWORD in your deployment environment and restart.",
+        );
+    }
     if (req.path.startsWith("/auth/google/callback")) return next();
     if (req.path.startsWith("/auth/codex/callback")) return next();
     if (isAuthorizedRequest(req)) return next();

package/lib/server/routes/proxy.js

@@ -3,13 +3,13 @@ const registerProxyRoutes = ({ app, proxy, SETUP_API_PREFIXES, requireAuth }) =>
     req.url = "/";
     proxy.web(req, res);
   });
-  app.all("/openclaw/*", requireAuth, (req, res) => {
+  app.all("/openclaw/*path", requireAuth, (req, res) => {
     req.url = req.url.replace(/^\/openclaw/, "");
     proxy.web(req, res);
   });
-  app.all("/assets/*", requireAuth, (req, res) => proxy.web(req, res));
+  app.all("/assets/*path", requireAuth, (req, res) => proxy.web(req, res));
 
-  app.all("/webhook/*", (req, res) => {
+  app.all("/webhook/*path", (req, res) => {
     if (!req.headers.authorization && req.query.token) {
       req.headers.authorization = `Bearer ${req.query.token}`;
       delete req.query.token;
@@ -20,7 +20,7 @@ const registerProxyRoutes = ({ app, proxy, SETUP_API_PREFIXES, requireAuth }) =>
     proxy.web(req, res);
   });
 
-  app.all("/api/*", (req, res) => {
+  app.all("/api/*path", (req, res) => {
     if (SETUP_API_PREFIXES.some((p) => req.path.startsWith(p))) return;
     proxy.web(req, res);
   });

package/lib/server/routes/telegram.js

@@ -0,0 +1,407 @@
+const fs = require("fs");
+const { OPENCLAW_DIR } = require("../constants");
+const { isDebugEnabled } = require("../helpers");
+const topicRegistry = require("../topic-registry");
+const { syncConfigForTelegram } = require("../telegram-workspace");
+
+const getRequestBody = (req) => (req.body && typeof req.body === "object" ? req.body : {});
+const getRequestQuery = (req) => (req.query && typeof req.query === "object" ? req.query : {});
+const parseJsonString = (value) => {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+};
+const getRequestPayload = (req) => {
+  const body = getRequestBody(req);
+  const query = getRequestQuery(req);
+  const payloadFromQuery = parseJsonString(query.payload);
+  if (payloadFromQuery && typeof payloadFromQuery === "object" && !Array.isArray(payloadFromQuery)) {
+    return { ...payloadFromQuery, ...body };
+  }
+  return body;
+};
+const parseBooleanValue = (value, fallbackValue = false) => {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "on"].includes(normalized)) return true;
+    if (["false", "0", "no", "off", ""].includes(normalized)) return false;
+  }
+  return fallbackValue;
+};
+const resolveGroupId = (req) => {
+  const body = getRequestPayload(req);
+  const query = getRequestQuery(req);
+  const rawGroupId = body.groupId ?? body.chatId ?? query.groupId ?? query.chatId;
+  return rawGroupId == null ? "" : String(rawGroupId).trim();
+};
+const resolveAllowUserId = async ({ telegramApi, groupId, preferredUserId }) => {
+  const normalizedPreferred = String(preferredUserId || "").trim();
+  if (normalizedPreferred) return normalizedPreferred;
+  const admins = await telegramApi.getChatAdministrators(groupId);
+  const humanAdmins = admins.filter((entry) => !entry?.user?.is_bot);
+  if (humanAdmins.length === 0) return "";
+  const creator = humanAdmins.find((entry) => entry.status === "creator");
+  const targetAdmin = creator || humanAdmins[0];
+  return String(targetAdmin?.user?.id || "").trim();
+};
+const isMissingTopicError = (errorMessage) => {
+  const message = String(errorMessage || "").toLowerCase();
+  return [
+    "topic_id_invalid",
+    "message_thread_id_invalid",
+    "message_thread_not_found",
+    "topic_not_found",
+    "message thread not found",
+    "topic not found",
+    "invalid thread id",
+    "invalid topic id",
+  ].some((token) => message.includes(token));
+};
+
+const registerTelegramRoutes = ({ app, telegramApi, syncPromptFiles }) => {
+  // Verify bot token
+  app.get("/api/telegram/bot", async (req, res) => {
+    try {
+      const me = await telegramApi.getMe();
+      res.json({ ok: true, bot: me });
+    } catch (e) {
+      res.json({ ok: false, error: e.message });
+    }
+  });
+
+  // Verify group: checks bot membership, admin rights, topics enabled
+  app.post("/api/telegram/groups/verify", async (req, res) => {
+    const groupId = resolveGroupId(req);
+    if (!groupId) return res.status(400).json({ ok: false, error: "groupId is required" });
+
+    try {
+      const chat = await telegramApi.getChat(groupId);
+      const me = await telegramApi.getMe();
+      const member = await telegramApi.getChatMember(groupId, me.id);
+      const suggestedUserId = await resolveAllowUserId({
+        telegramApi,
+        groupId,
+        preferredUserId: "",
+      });
+
+      const isAdmin = member.status === "administrator" || member.status === "creator";
+      const isForum = !!chat.is_forum;
+
+      res.json({
+        ok: true,
+        chat: {
+          id: chat.id,
+          title: chat.title,
+          type: chat.type,
+          isForum,
+        },
+        bot: {
+          status: member.status,
+          isAdmin,
+          canManageTopics: isAdmin && (member.can_manage_topics !== false),
+        },
+        suggestedUserId: suggestedUserId || null,
+      });
+    } catch (e) {
+      res.json({ ok: false, error: e.message });
+    }
+  });
+
+  // List topics from registry
+  app.get("/api/telegram/groups/:groupId/topics", (req, res) => {
+    const group = topicRegistry.getGroup(req.params.groupId);
+    res.json({ ok: true, topics: group?.topics || {} });
+  });
+
+  // Create a topic via Telegram API + add to registry
+  app.post("/api/telegram/groups/:groupId/topics", async (req, res) => {
+    const { groupId } = req.params;
+    const payload = getRequestPayload(req);
+    const query = getRequestQuery(req);
+    const name = String(payload.name ?? query.name ?? "").trim();
+    const rawIconColor = payload.iconColor ?? query.iconColor;
+    const systemInstructions = String(
+      payload.systemInstructions ?? payload.systemPrompt ?? query.systemInstructions ?? query.systemPrompt ?? "",
+    ).trim();
+    const iconColorValue = rawIconColor == null ? null : Number.parseInt(String(rawIconColor), 10);
+    const iconColor = Number.isFinite(iconColorValue) ? iconColorValue : undefined;
+    if (!name) return res.status(400).json({ ok: false, error: "name is required" });
+
+    try {
+      const result = await telegramApi.createForumTopic(groupId, name, {
+        iconColor,
+      });
+      const threadId = result.message_thread_id;
+      topicRegistry.addTopic(groupId, threadId, {
+        name: result.name,
+        iconColor: result.icon_color,
+        ...(systemInstructions ? { systemInstructions } : {}),
+      });
+      syncConfigForTelegram({
+        fs,
+        openclawDir: OPENCLAW_DIR,
+        topicRegistry,
+        groupId,
+        requireMention: false,
+        resolvedUserId: "",
+      });
+      syncPromptFiles();
+      res.json({ ok: true, topic: { threadId, name: result.name, iconColor: result.icon_color } });
+    } catch (e) {
+      res.json({ ok: false, error: e.message });
+    }
+  });
+
+  // Bulk-create topics
+  app.post("/api/telegram/groups/:groupId/topics/bulk", async (req, res) => {
+    const { groupId } = req.params;
+    const payload = getRequestPayload(req);
+    const query = getRequestQuery(req);
+    const queryTopics = parseJsonString(query.topics);
+    const topics = Array.isArray(payload.topics)
+      ? payload.topics
+      : Array.isArray(queryTopics)
+        ? queryTopics
+        : [];
+    if (!Array.isArray(topics) || topics.length === 0) {
+      return res.status(400).json({ ok: false, error: "topics array is required" });
+    }
+
+    const results = [];
+    for (const t of topics) {
+      if (!t.name) {
+        results.push({ name: t.name, ok: false, error: "name is required" });
+        continue;
+      }
+      try {
+        const result = await telegramApi.createForumTopic(groupId, t.name, {
+          iconColor: t.iconColor || undefined,
+        });
+        const threadId = result.message_thread_id;
+        const systemInstructions = String(t.systemInstructions ?? t.systemPrompt ?? "").trim();
+        topicRegistry.addTopic(groupId, threadId, {
+          name: result.name,
+          iconColor: result.icon_color,
+          ...(systemInstructions ? { systemInstructions } : {}),
+        });
+        results.push({ name: result.name, threadId, ok: true });
+      } catch (e) {
+        results.push({ name: t.name, ok: false, error: e.message });
+      }
+    }
+    syncConfigForTelegram({
+      fs,
+      openclawDir: OPENCLAW_DIR,
+      topicRegistry,
+      groupId,
+      requireMention: false,
+      resolvedUserId: "",
+    });
+    syncPromptFiles();
+    res.json({ ok: true, results });
+  });
+
+  // Delete a topic
+  app.delete("/api/telegram/groups/:groupId/topics/:topicId", async (req, res) => {
+    const { groupId, topicId } = req.params;
+    try {
+      await telegramApi.deleteForumTopic(groupId, parseInt(topicId, 10));
+      topicRegistry.removeTopic(groupId, topicId);
+      syncConfigForTelegram({
+        fs,
+        openclawDir: OPENCLAW_DIR,
+        topicRegistry,
+        groupId,
+        requireMention: false,
+        resolvedUserId: "",
+      });
+      syncPromptFiles();
+      res.json({ ok: true });
+    } catch (e) {
+      if (!isMissingTopicError(e?.message)) {
+        return res.json({ ok: false, error: e.message });
+      }
+      topicRegistry.removeTopic(groupId, topicId);
+      syncConfigForTelegram({
+        fs,
+        openclawDir: OPENCLAW_DIR,
+        topicRegistry,
+        groupId,
+        requireMention: false,
+        resolvedUserId: "",
+      });
+      syncPromptFiles();
+      return res.json({
+        ok: true,
+        removedFromRegistryOnly: true,
+        warning: "Topic no longer exists in Telegram; removed stale registry entry.",
+      });
+    }
+  });
+
+  // Rename a topic
+  app.put("/api/telegram/groups/:groupId/topics/:topicId", async (req, res) => {
+    const { groupId, topicId } = req.params;
+    const payload = getRequestPayload(req);
+    const query = getRequestQuery(req);
+    const name = String(payload.name ?? query.name ?? "").trim();
+    const hasSystemInstructions = Object.prototype.hasOwnProperty.call(payload, "systemInstructions")
+      || Object.prototype.hasOwnProperty.call(payload, "systemPrompt")
+      || Object.prototype.hasOwnProperty.call(query, "systemInstructions")
+      || Object.prototype.hasOwnProperty.call(query, "systemPrompt");
+    const systemInstructions = String(
+      payload.systemInstructions ?? payload.systemPrompt ?? query.systemInstructions ?? query.systemPrompt ?? "",
+    ).trim();
+    if (!name) return res.status(400).json({ ok: false, error: "name is required" });
+    try {
+      const threadId = Number.parseInt(String(topicId), 10);
+      if (!Number.isFinite(threadId)) {
+        return res.status(400).json({ ok: false, error: "topicId must be numeric" });
+      }
+      const existingTopic = topicRegistry.getGroup(groupId)?.topics?.[String(threadId)] || {};
+      const existingName = String(existingTopic.name || "").trim();
+      const shouldRename = !existingName || existingName !== name;
+      if (shouldRename) {
+        try {
+          await telegramApi.editForumTopic(groupId, threadId, { name });
+        } catch (e) {
+          // Telegram returns TOPIC_NOT_MODIFIED when the name is unchanged.
+          if (!String(e.message || "").includes("TOPIC_NOT_MODIFIED")) {
+            throw e;
+          }
+        }
+      }
+      topicRegistry.updateTopic(groupId, threadId, {
+        ...existingTopic,
+        name,
+        ...(hasSystemInstructions ? { systemInstructions } : {}),
+      });
+      syncConfigForTelegram({
+        fs,
+        openclawDir: OPENCLAW_DIR,
+        topicRegistry,
+        groupId,
+        requireMention: false,
+        resolvedUserId: "",
+      });
+      syncPromptFiles();
+      return res.json({
+        ok: true,
+        topic: { threadId, name, ...(hasSystemInstructions ? { systemInstructions } : {}) },
+      });
+    } catch (e) {
+      return res.json({ ok: false, error: e.message });
+    }
+  });
+
+  // Configure openclaw.json for a group
+  app.post("/api/telegram/groups/:groupId/configure", async (req, res) => {
+    const { groupId } = req.params;
+    const payload = getRequestPayload(req);
+    const query = getRequestQuery(req);
+    const userId = payload.userId ?? query.userId ?? "";
+    const groupName = payload.groupName ?? query.groupName ?? "";
+    const requireMention = parseBooleanValue(payload.requireMention ?? query.requireMention, false);
+    try {
+      const resolvedUserId = await resolveAllowUserId({
+        telegramApi,
+        groupId,
+        preferredUserId: userId,
+      });
+      syncConfigForTelegram({
+        fs,
+        openclawDir: OPENCLAW_DIR,
+        topicRegistry,
+        groupId,
+        requireMention,
+        resolvedUserId,
+      });
+
+      // Save metadata in local topic registry only.
+      if (groupName) {
+        topicRegistry.setGroup(groupId, { name: groupName });
+        syncPromptFiles();
+      }
+
+      res.json({ ok: true, userId: resolvedUserId || null });
+    } catch (e) {
+      res.json({ ok: false, error: e.message });
+    }
+  });
+
+  // Get full topic registry
+  app.get("/api/telegram/topic-registry", (req, res) => {
+    res.json({ ok: true, registry: topicRegistry.readRegistry() });
+  });
+
+  // Workspace bootstrap info (lets UI jump straight to management)
+  app.get("/api/telegram/workspace", async (req, res) => {
+    try {
+      const debugEnabled = isDebugEnabled();
+      const configPath = `${OPENCLAW_DIR}/openclaw.json`;
+      const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+      const telegramConfig = cfg.channels?.telegram || {};
+      const configuredGroups = telegramConfig.groups || {};
+      const groupIds = Object.keys(configuredGroups);
+      if (groupIds.length === 0) {
+        return res.json({ ok: true, configured: false, debugEnabled });
+      }
+      const groupId = String(groupIds[0]);
+      const registryGroup = topicRegistry.getGroup(groupId);
+      let groupName = registryGroup?.name || groupId;
+      try {
+        const chat = await telegramApi.getChat(groupId);
+        if (chat?.title) groupName = chat.title;
+      } catch {}
+      return res.json({
+        ok: true,
+        configured: true,
+        groupId,
+        groupName,
+        topics: registryGroup?.topics || {},
+        debugEnabled,
+        concurrency: {
+          agentMaxConcurrent: cfg.agents?.defaults?.maxConcurrent ?? null,
+          subagentMaxConcurrent: cfg.agents?.defaults?.subagents?.maxConcurrent ?? null,
+        },
+      });
+    } catch (e) {
+      return res.json({ ok: false, error: e.message });
+    }
+  });
+
+  // Reset Telegram workspace onboarding state
+  app.post("/api/telegram/workspace/reset", (req, res) => {
+    try {
+      const configPath = `${OPENCLAW_DIR}/openclaw.json`;
+      const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+      const telegramGroups = Object.keys(cfg.channels?.telegram?.groups || {});
+      if (cfg.channels?.telegram) {
+        delete cfg.channels.telegram.groups;
+        delete cfg.channels.telegram.groupAllowFrom;
+      }
+      fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2));
+
+      // Remove corresponding groups from topic registry
+      const registry = topicRegistry.readRegistry();
+      if (registry && registry.groups) {
+        for (const groupId of telegramGroups) {
+          delete registry.groups[groupId];
+        }
+        topicRegistry.writeRegistry(registry);
+      }
+
+      syncPromptFiles();
+      return res.json({ ok: true });
+    } catch (e) {
+      return res.json({ ok: false, error: e.message });
+    }
+  });
+};
+
+module.exports = { registerTelegramRoutes };