chatccc 0.2.203 → 0.2.204

package/README.md

@@ -133,7 +133,7 @@ Write-Host ''
 chatccc
 ```
 
-如果一切顺利，浏览器会自动打开 `http://127.0.0.1:18080` 的 Web 配置页面。按页面提示填入飞书 App ID / App Secret，点击"保存并启动"即可。
+如果一切顺利，系统默认浏览器会自动打开 `http://localhost:18080/` 的 Web 配置页面。按页面提示填入飞书 App ID / App Secret，点击"保存并启动"即可。
 
 > **只想装 ChatCCC 本体？** 如果你已经有 Node.js，直接 `npm install -g chatccc && chatccc` 即可，不需要跑上面的完整脚本。
 
@@ -151,7 +151,7 @@ chatccc
 
 旧版本留在仓库或包目录下的 `config.json`、`logs/`、`state/` 会在首次启动时自动迁移到用户目录。
 
-首次启动时，如果还没有有效配置，ChatCCC 会自动打开本地 Web 配置向导（默认 `http://127.0.0.1:18080`）。
+每次直接运行 `chatccc` 时，无论是否已经完成配置，ChatCCC 默认都会用系统默认浏览器打开本地 Web UI（默认 `http://localhost:18080/`，修改 `config.port` 后跟随实际端口）。可在首次配置向导或管理页的 **Web UI** 设置中关闭；关闭后从下一次直接启动起生效。由 `/restart`、`/update` 或 Web UI 发起的内部重启始终不会重复打开浏览器。Linux 服务器没有 `DISPLAY`/`WAYLAND_DISPLAY` 时会跳过打开，并在终端输出 SSH 隧道访问提示。主页顶部的 **Agent Team** 入口会跳转到独立的 `/agent-team` 页面。
 
 #### 从源码运行
 
@@ -260,11 +260,14 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
     "appId": "cli_xxxxxxxxxxxx",
     "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxx"
   },
-  "platforms": {
-    "feishu": { "enabled": true, "platformType": "feishu" },
-    "ilink": { "enabled": true, "reuseTokenOnStart": true }
-  },
-  "chromeDevtools": {
+  "platforms": {
+    "feishu": { "enabled": true, "platformType": "feishu" },
+    "ilink": { "enabled": true, "reuseTokenOnStart": true }
+  },
+  "webUi": {
+    "openOnStart": true
+  },
+  "chromeDevtools": {
     "enabled": false,
     "port": 15166,
     "chromePath": ""
@@ -305,9 +308,10 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
 | `feishu.appId` / `feishu.appSecret` | 飞书应用凭证 |
 | `platforms.feishu.enabled` | 是否启用飞书 |
 | `platforms.feishu.platformType` | 飞书平台类型，默认 `feishu` |
-| `platforms.ilink.enabled` | 是否启用微信 iLink |
-| `platforms.ilink.reuseTokenOnStart` | 启动时是否复用已有微信登录 token |
-| `chromeDevtools.enabled` | 是否启用常驻 Chrome CDP；默认 false |
+| `platforms.ilink.enabled` | 是否启用微信 iLink |
+| `platforms.ilink.reuseTokenOnStart` | 启动时是否复用已有微信登录 token |
+| `webUi.openOnStart` | 直接启动时是否打开系统默认浏览器；默认 true，内部重启始终跳过 |
+| `chromeDevtools.enabled` | 是否启用常驻 Chrome CDP；默认 false |
 | `chromeDevtools.port` | Chrome CDP 端口；默认 15166 |
 | `chromeDevtools.chromePath` | Chrome 可执行文件路径；留空时自动探测 |
 | `port` | 本地 Web 配置面板和中继服务端口 |

package/config.sample.json

@@ -3,11 +3,14 @@
     "appId": "",
     "appSecret": ""
   },
-  "platforms": {
-    "feishu": { "enabled": true, "platformType": "feishu" },
-    "ilink": { "enabled": true, "reuseTokenOnStart": true }
-  },
-  "chromeDevtools": {
+  "platforms": {
+    "feishu": { "enabled": true, "platformType": "feishu" },
+    "ilink": { "enabled": true, "reuseTokenOnStart": true }
+  },
+  "webUi": {
+    "openOnStart": true
+  },
+  "chromeDevtools": {
     "enabled": false,
     "port": 15166,
     "chromePath": ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.203",
+  "version": "0.2.204",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",

package/src/__tests__/config-reload.test.ts

@@ -38,10 +38,11 @@ import {
 //      原地切换复用同一 server，重新读端口只会引入混乱）
 // ---------------------------------------------------------------------------
 
-const baseAppConfig: AppConfig = {
-  feishu: { appId: "INITIAL_APP", appSecret: "INITIAL_SECRET" },
-  platforms: { feishu: { enabled: true }, ilink: { enabled: true } },
-  chromeDevtools: { enabled: false, port: 15166, chromePath: "" },
+const baseAppConfig: AppConfig = {
+  feishu: { appId: "INITIAL_APP", appSecret: "INITIAL_SECRET" },
+  platforms: { feishu: { enabled: true }, ilink: { enabled: true } },
+  webUi: { openOnStart: true },
+  chromeDevtools: { enabled: false, port: 15166, chromePath: "" },
   port: 18080,
   gitTimeoutSeconds: 180,
   allowInterrupt: false,
@@ -216,7 +217,7 @@ describe("applyLoadedConfig — config 对象引用契约", () => {
     expect(config.codex.path).toBe("/refresh/codex");
   });
 
-  it("刷新 chromeDevtools 配置但保持 config 引用", () => {
+  it("刷新 chromeDevtools 配置但保持 config 引用", () => {
     const refBefore = config;
 
     applyLoadedConfig({
@@ -226,7 +227,19 @@ describe("applyLoadedConfig — config 对象引用契约", () => {
 
     expect(config).toBe(refBefore);
     expect(config.chromeDevtools).toEqual({ enabled: true, port: 15166, chromePath: "C:/Chrome/chrome.exe" });
-  });
+  });
+
+  it("刷新 webUi 启动开关但保持 config 引用", () => {
+    const refBefore = config;
+
+    applyLoadedConfig({
+      ...structuredClone(baseAppConfig),
+      webUi: { openOnStart: false },
+    });
+
+    expect(config).toBe(refBefore);
+    expect(config.webUi).toEqual({ openOnStart: false });
+  });
 
   it("空 feishu 凭证也能正确刷入（向导回滚到空的反向场景）", () => {
     applyLoadedConfig({

package/src/__tests__/config-sample.test.ts

@@ -59,7 +59,16 @@ describe("config.sample.json", () => {
     expect(sample.chromeDevtools?.enabled).toBe(false);
     expect(sample.chromeDevtools?.port).toBe(15166);
     expect(sample.chromeDevtools?.chromePath).toBe("");
-  });
+  });
+
+  it("opens the Web UI on direct startup by default", () => {
+    const configSamplePath = join(process.cwd(), "config.sample.json");
+    const sample = JSON.parse(readFileSync(configSamplePath, "utf8")) as {
+      webUi?: { openOnStart?: unknown };
+    };
+
+    expect(sample.webUi?.openOnStart).toBe(true);
+  });
 
   it("keeps raw stream logs disabled by default for every agent", () => {
     const configSamplePath = join(process.cwd(), "config.sample.json");

package/src/__tests__/startup-lifecycle.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  INTERNAL_RESTART_ENV_VAR,
+  buildWebUiUrl,
+  createInternalRestartEnv,
+  openWebUiInDefaultBrowser,
+  shouldAutoOpenWebUi,
+} from "../startup-lifecycle.ts";
+
+describe("ChatCCC startup lifecycle", () => {
+  it("opens the Web UI by default for a direct start", () => {
+    expect(shouldAutoOpenWebUi({ env: {} })).toBe(true);
+    expect(shouldAutoOpenWebUi({ env: {}, openOnStart: true })).toBe(true);
+  });
+
+  it("respects the persisted openOnStart preference", () => {
+    expect(shouldAutoOpenWebUi({ env: {}, openOnStart: false })).toBe(false);
+  });
+
+  it("never opens the Web UI for an internal restart", () => {
+    expect(shouldAutoOpenWebUi({
+      env: { [INTERNAL_RESTART_ENV_VAR]: "1" },
+      openOnStart: true,
+    })).toBe(false);
+  });
+
+  it("marks internal restart children without losing the inherited environment", () => {
+    expect(createInternalRestartEnv({ PATH: "test-path", CUSTOM: "value" })).toEqual({
+      PATH: "test-path",
+      CUSTOM: "value",
+      [INTERNAL_RESTART_ENV_VAR]: "1",
+    });
+  });
+
+  it("uses localhost and the configured port for the Web UI URL", () => {
+    expect(buildWebUiUrl(18080)).toBe("http://localhost:18080/");
+    expect(buildWebUiUrl(18081)).toBe("http://localhost:18081/");
+  });
+
+  it("opens the configured URL in the Windows default browser", () => {
+    const child = {
+      on: vi.fn().mockReturnThis(),
+      unref: vi.fn(),
+    };
+    const spawnImpl = vi.fn(() => child as never);
+
+    expect(openWebUiInDefaultBrowser(18081, {
+      platform: "win32",
+      spawnImpl,
+    })).toBe(true);
+    expect(spawnImpl).toHaveBeenCalledWith(
+      "cmd.exe",
+      ["/c", "start", "", "http://localhost:18081/"],
+      {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+      },
+    );
+    expect(child.on).toHaveBeenCalledWith("error", expect.any(Function));
+    expect(child.unref).toHaveBeenCalledOnce();
+  });
+
+  it("opens the configured URL with xdg-open on a Linux desktop", () => {
+    const child = {
+      on: vi.fn().mockReturnThis(),
+      unref: vi.fn(),
+    };
+    const spawnImpl = vi.fn(() => child as never);
+
+    expect(openWebUiInDefaultBrowser(18080, {
+      platform: "linux",
+      env: { DISPLAY: ":0" },
+      spawnImpl,
+    })).toBe(true);
+    expect(spawnImpl).toHaveBeenCalledWith(
+      "xdg-open",
+      ["http://localhost:18080/"],
+      { detached: true, stdio: "ignore" },
+    );
+  });
+
+  it("skips xdg-open and prints an SSH tunnel hint on headless Linux", () => {
+    const spawnImpl = vi.fn();
+    const onInfo = vi.fn();
+
+    expect(openWebUiInDefaultBrowser(18080, {
+      platform: "linux",
+      env: {},
+      spawnImpl,
+      onInfo,
+    })).toBe(false);
+    expect(spawnImpl).not.toHaveBeenCalled();
+    expect(onInfo).toHaveBeenCalledWith(expect.stringContaining("ssh -L 18080:127.0.0.1:18080"));
+    expect(onInfo).toHaveBeenCalledWith(expect.stringContaining("http://localhost:18080/"));
+  });
+});

package/src/__tests__/web-ui.test.ts

@@ -1,11 +1,44 @@
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
 import { describe, it, expect } from "vitest";
 import {
+  AGENT_TEAM_PAGE_HTML,
   PAGE_HTML,
   chooseStartPath,
+  createUiRouter,
   getRestartRequiredReasons,
   unflattenConfig,
 } from "../web-ui.ts";
 
+describe("Agent Team page", () => {
+  it("adds a prominent global entry to the ChatCCC page", () => {
+    expect(PAGE_HTML).toContain('href="/agent-team"');
+    expect(PAGE_HTML).toContain('class="agent-team-entry"');
+    expect(PAGE_HTML).toContain("Agent Team");
+    expect(PAGE_HTML).toContain("linear-gradient");
+  });
+
+  it("contains only the Agent Team title as page content", () => {
+    expect(AGENT_TEAM_PAGE_HTML).toContain("<title>Agent Team</title>");
+    expect(AGENT_TEAM_PAGE_HTML).toContain("<h1>Agent Team</h1>");
+    expect(AGENT_TEAM_PAGE_HTML).not.toContain("dashboard-view");
+    expect(AGENT_TEAM_PAGE_HTML).not.toContain("wizard-view");
+  });
+
+  it("serves the Agent Team page from its own route", async () => {
+    const server = createServer(createUiRouter());
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = (server.address() as AddressInfo).port;
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/agent-team`);
+      expect(response.status).toBe(200);
+      expect(await response.text()).toBe(AGENT_TEAM_PAGE_HTML);
+    } finally {
+      await new Promise<void>((resolve, reject) => server.close((err) => err ? reject(err) : resolve()));
+    }
+  });
+});
+
 describe("unflattenConfig", () => {
   it("maps Claude subagent model into claude.subagentModel", () => {
     expect(
@@ -66,6 +99,18 @@ describe("unflattenConfig", () => {
       },
     });
   });
+
+  it("maps the Web UI startup preference into webUi config", () => {
+    expect(
+      unflattenConfig({
+        CHATCCC_WEB_UI_OPEN_ON_START: false,
+      }),
+    ).toEqual({
+      webUi: {
+        openOnStart: false,
+      },
+    });
+  });
 });
 
 describe("getRestartRequiredReasons", () => {
@@ -75,6 +120,7 @@ describe("getRestartRequiredReasons", () => {
       feishu: { enabled: true, platformType: "feishu" },
       ilink: { enabled: true, reuseTokenOnStart: true },
     },
+    webUi: { openOnStart: true },
     chromeDevtools: { enabled: false, port: 15166, chromePath: "" },
     port: 18080,
     claude: {
@@ -142,6 +188,12 @@ describe("getRestartRequiredReasons", () => {
 });
 
 describe("dashboard edit modal", () => {
+  it("keeps the embedded dashboard script syntactically valid", () => {
+    const script = PAGE_HTML.match(/<script>([\s\S]*)<\/script>/)?.[1];
+    expect(script).toBeTruthy();
+    expect(() => new Function(script ?? "")).not.toThrow();
+  });
+
   it("shows the edit modal and overlay when a section edit button is clicked", () => {
     expect(PAGE_HTML).toContain("function editSection(section)");
     expect(PAGE_HTML).toContain("document.getElementById('edit-modal').classList.remove('hidden');");
@@ -158,6 +210,13 @@ describe("dashboard edit modal", () => {
     expect(PAGE_HTML).toContain("生效范围：保存后下一条消息或下个新会话生效");
     expect(PAGE_HTML).toContain("生效范围：飞书开关、App ID、App Secret 或平台类型变更需要重启 ChatCCC");
   });
+
+  it("shows the Web UI startup switch in both the wizard and dashboard", () => {
+    expect(PAGE_HTML).toContain('id="field-CHATCCC_WEB_UI_OPEN_ON_START"');
+    expect(PAGE_HTML).toContain('id="cfg-WEB_UI_OPEN_ON_START"');
+    expect(PAGE_HTML).toContain("editSection('webUi')");
+    expect(PAGE_HTML).toContain("下次直接启动生效；内部重启始终不打开");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/config.ts

@@ -150,10 +150,11 @@ export interface RawStreamLogsConfig {
   ccc: RawStreamAgentLogConfig;
 }
 
-export interface AppConfig {
-  feishu: FeishuConfig;
-  platforms: PlatformsConfig;
-  chromeDevtools: ChromeDevtoolsConfig;
+export interface AppConfig {
+  feishu: FeishuConfig;
+  platforms: PlatformsConfig;
+  webUi: { openOnStart: boolean };
+  chromeDevtools: ChromeDevtoolsConfig;
   port: number;
   gitTimeoutSeconds: number;
   /** 若为 false，AI 生成过程中用户发送消息不会打断，须先点「停止」再发送新消息 */
@@ -418,9 +419,10 @@ function normalizeRawStreamAgentLogConfig(raw: unknown): RawStreamAgentLogConfig
 
 function loadConfig(): AppConfig {
   const defaults: AppConfig = {
-    feishu: { appId: "", appSecret: "" },
-    platforms: { feishu: { enabled: true }, ilink: { enabled: true } },
-    chromeDevtools: { enabled: false, port: 15166, chromePath: "" },
+    feishu: { appId: "", appSecret: "" },
+    platforms: { feishu: { enabled: true }, ilink: { enabled: true } },
+    webUi: { openOnStart: true },
+    chromeDevtools: { enabled: false, port: 15166, chromePath: "" },
     port: 18080,
     gitTimeoutSeconds: 180,
     allowInterrupt: false,
@@ -495,6 +497,7 @@ function loadConfig(): AppConfig {
     };
     codex?: { enabled?: unknown; defaultAgent?: unknown; path?: unknown; command?: unknown; model?: unknown; alternativeModel?: unknown; effort?: unknown };
     ccc?: { DEEPSEEK_API_KEY?: unknown; DEEPSEEK_BASE_URL?: unknown; model?: unknown };
+    webUi?: { openOnStart?: unknown };
     chromeDevtools?: { enabled?: unknown; port?: unknown; chromePath?: unknown };
     rawStreamLogs?: unknown;
   };
@@ -510,6 +513,7 @@ function loadConfig(): AppConfig {
   const cursorRaw = (parsed.cursor ?? {}) as NonNullable<typeof parsed.cursor>;
   const codexRaw = (parsed.codex ?? {}) as NonNullable<typeof parsed.codex>;
   const cccRaw = (parsed.ccc ?? {}) as NonNullable<typeof parsed.ccc>;
+  const webUiRaw = (parsed.webUi ?? {}) as NonNullable<typeof parsed.webUi>;
   const chromeDevtoolsRaw = (parsed.chromeDevtools ?? {}) as NonNullable<typeof parsed.chromeDevtools>;
   const rawStreamLogsRaw = typeof parsed.rawStreamLogs === "object" && parsed.rawStreamLogs !== null
     ? parsed.rawStreamLogs as unknown as Record<string, unknown>
@@ -577,7 +581,7 @@ function loadConfig(): AppConfig {
       appId: feishu.appId ?? "",
       appSecret: feishu.appSecret ?? "",
     },
-    platforms: {
+    platforms: {
       feishu: {
         enabled: typeof (parsed.platforms as unknown as Record<string, unknown> | undefined)?.feishu === "object"
           ? Boolean(((parsed.platforms as unknown as Record<string, unknown>).feishu as Record<string, unknown>).enabled ?? true)
@@ -595,9 +599,13 @@ function loadConfig(): AppConfig {
         reuseTokenOnStart: typeof (parsed.platforms as unknown as Record<string, unknown> | undefined)?.ilink === "object"
           ? Boolean(((parsed.platforms as unknown as Record<string, unknown>).ilink as Record<string, unknown>).reuseTokenOnStart ?? true)
           : true,
-      },
-    },
-    chromeDevtools: {
+      },
+    },
+    webUi: {
+      // 兼容升级前没有 webUi 字段的 config.json：缺省仍按“自动打开”处理。
+      openOnStart: typeof webUiRaw.openOnStart === "boolean" ? webUiRaw.openOnStart : true,
+    },
+    chromeDevtools: {
       enabled: typeof chromeDevtoolsRaw.enabled === "boolean" ? chromeDevtoolsRaw.enabled : false,
       port: Number.isInteger(chromeDevtoolsPort) && chromeDevtoolsPort >= 1 && chromeDevtoolsPort <= 65535
         ? chromeDevtoolsPort

package/src/index.ts

@@ -28,12 +28,18 @@ import { WSClient, EventDispatcher, Domain } from "@larksuiteoapi/node-sdk";
 import WebSocket from "ws";
 
 import { appendStartupTrace, attachRelayWebSocket, ensureSingleInstance, freeRelayListenPort, installCrashLogging, waitForPortFree } from "./shared.ts";
-import { createUiRouter, setExtraApiHandler, setReloadConfigHook, startSetupMode } from "./web-ui.ts";
+import { createUiRouter, setExtraApiHandler, setReloadConfigHook, startSetupMode } from "./web-ui.ts";
+import {
+  buildWebUiUrl,
+  openWebUiInDefaultBrowser,
+  shouldAutoOpenWebUi,
+} from "./startup-lifecycle.ts";
 import { buildPlatformStartupPlan } from "./platform-startup.ts";
 import { makeTraceId, logTrace } from "./trace.ts";
 import {
-  CHATCCC_PORT,
-  APP_ID,
+  CHATCCC_PORT,
+  config,
+  APP_ID,
   APP_SECRET,
   FEISHU_ENABLED,
   FEISHU_PLATFORM_TYPE,
@@ -720,11 +726,17 @@ async function startConfiguredPlatforms(
 // Main
 // ---------------------------------------------------------------------------
 
-async function main(): Promise<void> {
-  appendStartupTrace("main: entered", {
-    argv: process.argv.join(" ").slice(0, 400),
-    CHATCCC_PORT,
-    PROJECT_ROOT,
+async function main(): Promise<void> {
+  // 用户直接运行 chatccc 时打开系统默认浏览器；由 `/restart`、`/update`
+  // 或 Web UI 拉起的替代进程会携带内部标记，不重复打扰用户。
+  const autoOpenWebUi = shouldAutoOpenWebUi({
+    openOnStart: config.webUi.openOnStart,
+  });
+  appendStartupTrace("main: entered", {
+    argv: process.argv.join(" ").slice(0, 400),
+    CHATCCC_PORT,
+    PROJECT_ROOT,
+    autoOpenWebUi,
   });
 
   // 黑匣子：所有未捕获异常 / 信号 / beforeExit 都同步写入 startup-trace.log（appendFileSync）。
@@ -780,9 +792,18 @@ async function main(): Promise<void> {
     console.log(`${"=".repeat(60)}`);
     console.log(`  发送消息: POST http://127.0.0.1:${SIM_PORT}/api/sim/inject-message`);
     console.log(`  消息日志: ~/.chatccc/sim/messages.jsonl`);
-    console.log(`${"=".repeat(60)}\n`);
-
-    installShutdownHandlers(simServer);
+    console.log(`${"=".repeat(60)}\n`);
+
+    if (autoOpenWebUi) {
+      const url = buildWebUiUrl(SIM_PORT);
+      const opened = openWebUiInDefaultBrowser(SIM_PORT);
+      appendStartupTrace(
+        opened ? "web-ui: opening simulate browser" : "web-ui: simulate browser unavailable",
+        { url },
+      );
+    }
+
+    installShutdownHandlers(simServer);
     return;
   }
 
@@ -830,8 +851,9 @@ async function main(): Promise<void> {
     if (!APP_ID.trim() || !APP_SECRET.trim()) {
       // 凭证不全：进 setup 向导。注入 onActivate 回调让用户点"保存并启动"
       // 时，原地（同进程）调用 startBotService，复用 setup HTTP server。
-      startSetupMode(CHATCCC_PORT, {
-        onActivate: async (httpServer: Server) => {
+      startSetupMode(CHATCCC_PORT, {
+        openBrowser: autoOpenWebUi,
+        onActivate: async (httpServer: Server) => {
           reloadRuntimeConfig("setup-activate");
           appendStartupTrace("setup-activate: reloaded config from disk", {
             appIdMaskAfterReload: maskAppId(APP_ID),
@@ -867,17 +889,35 @@ async function main(): Promise<void> {
     await waitForPortFree(CHATCCC_PORT);
     appendStartupTrace("main: port free confirmed", { CHATCCC_PORT });
   }
-  const httpServer = createServer(createUiRouter());
-  await listenWithRetry(httpServer, CHATCCC_PORT, "127.0.0.1").catch((err: NodeJS.ErrnoException) => {
+  const httpServer = createServer(createUiRouter());
+  await listenWithRetry(httpServer, CHATCCC_PORT, "127.0.0.1").catch((err: NodeJS.ErrnoException) => {
     console.error(`\n[启动] 本地中继 WebSocket 监听失败：端口 ${CHATCCC_PORT}（${err.code ?? "?"} — ${err.message}）`);
     console.error(
       "  处理建议: 关闭占用该端口的其它程序，或在 config.json 的 port 字段里改成其它未占用端口（如 18081）。"
     );
     printServiceDidNotStart(`本地中继端口 ${CHATCCC_PORT} 无法监听（${err.code ?? "?"} — ${err.message}）`);
-    process.exit(1);
-  });
-
-  await startConfiguredPlatforms(httpServer, { failOnFeishuError: false });
+    process.exit(1);
+  });
+
+  // 必须等 HTTP server 真正监听后再发起打开请求，避免浏览器先到一步看到
+  // ERR_CONNECTION_REFUSED。Chrome CDP 守护仍保持自己原有的独立行为。
+  if (autoOpenWebUi) {
+    const url = buildWebUiUrl(CHATCCC_PORT);
+    const opened = openWebUiInDefaultBrowser(CHATCCC_PORT);
+    if (opened) {
+      console.log(`[WEB-UI] 已请求系统默认浏览器打开: ${url}`);
+      appendStartupTrace("web-ui: opening default browser", { url });
+    } else {
+      appendStartupTrace("web-ui: default browser unavailable", { url });
+    }
+  } else {
+    appendStartupTrace("web-ui: default browser skipped by lifecycle or preference", {
+      url: buildWebUiUrl(CHATCCC_PORT),
+      openOnStart: config.webUi.openOnStart,
+    });
+  }
+
+  await startConfiguredPlatforms(httpServer, { failOnFeishuError: false });
 
   installShutdownHandlers(httpServer);
 }

package/src/orchestrator.ts

@@ -91,6 +91,7 @@ import { applySharedPrefix } from "./shared-prefix.ts";
 import { cwdDisplayName, sessionChatName } from "./session-name.ts";
 import { reloadRuntimeConfig } from "./runtime-reload.ts";
 import { acquireUpdateCommandGuard } from "./update-command-guard.ts";
+import { createInternalRestartEnv } from "./startup-lifecycle.ts";
 export { type PlatformAdapter } from "./platform-adapter.ts";
 import type { ChatAvatarUsageHints, PlatformAdapter } from "./platform-adapter.ts";
 import type { CodexUsageSummary } from "./feishu-api.ts";
@@ -480,7 +481,12 @@ function syncUpdateAndRestart(): void {
 
   // 3. spawn new chatccc
   try {
-    const child = spawn(binPath, [], { detached: true, stdio: "ignore", shell: true });
+    const child = spawn(binPath, [], {
+      detached: true,
+      stdio: "ignore",
+      shell: true,
+      env: createInternalRestartEnv(),
+    });
     child.unref();
     updLog(`spawn new chatccc OK, childPid=${child.pid}, bin=${binPath}`);
     appendStartupTrace("update: spawn OK", { childPid: child.pid, binPath });
@@ -545,9 +551,10 @@ export async function handleCommand(
     appendStartupTrace("restart: spawn begin", { fromPid: process.pid });
     const child = spawn("npx", ["tsx", "src/index.ts"], {
       cwd: PROJECT_ROOT,
-      detached: true,
-      stdio: "ignore",
-      shell: true,
+      detached: true,
+      stdio: "ignore",
+      shell: true,
+      env: createInternalRestartEnv(),
     });
 
     child.on("error", (err) => {

package/src/startup-lifecycle.ts

@@ -0,0 +1,96 @@
+import { spawn, type ChildProcess } from "node:child_process";
+
+/**
+ * ChatCCC 自己拉起替代进程时使用的内部标记。
+ *
+ * 不能用“是否已有配置”判断是否打开控制台：首次配置和日常直接启动都应该
+ * 打开，而 `/restart`、`/update` 和 Web UI 重启都不应该打扰用户。环境变量
+ * 会自然穿过 cmd/bash/npx 这几层启动器，因此也适用于 Windows 与 Linux。
+ */
+export const INTERNAL_RESTART_ENV_VAR = "CHATCCC_INTERNAL_RESTART";
+
+type Environment = Record<string, string | undefined>;
+
+export function createInternalRestartEnv(
+  inherited: Environment = process.env,
+): NodeJS.ProcessEnv {
+  return {
+    ...inherited,
+    [INTERNAL_RESTART_ENV_VAR]: "1",
+  };
+}
+
+/** 用户直接启动时打开；ChatCCC 内部重启产生的替代进程不打开。 */
+interface AutoOpenWebUiOptions {
+  env?: Environment;
+  openOnStart?: boolean;
+}
+
+export function shouldAutoOpenWebUi(options: AutoOpenWebUiOptions = {}): boolean {
+  const env = options.env ?? process.env;
+  return options.openOnStart !== false && env[INTERNAL_RESTART_ENV_VAR] !== "1";
+}
+
+/** Web UI 始终使用 localhost，并跟随实际配置端口。 */
+export function buildWebUiUrl(port: number): string {
+  return `http://localhost:${port}/`;
+}
+
+interface OpenBrowserDeps {
+  platform?: NodeJS.Platform;
+  env?: Environment;
+  spawnImpl?: typeof spawn;
+  onError?: (message: string) => void;
+  onInfo?: (message: string) => void;
+}
+
+/**
+ * 调用操作系统默认浏览器打开 Web UI，与 Chrome CDP 守护功能完全独立。
+ * 返回值仅表示打开请求是否成功发起；浏览器是否复用标签页由系统浏览器决定。
+ */
+export function openWebUiInDefaultBrowser(
+  port: number,
+  deps: OpenBrowserDeps = {},
+): boolean {
+  const url = buildWebUiUrl(port);
+  const platform = deps.platform ?? process.platform;
+  const env = deps.env ?? process.env;
+  const spawnImpl = deps.spawnImpl ?? spawn;
+  const onError = deps.onError ?? ((message: string) => console.error(message));
+  const onInfo = deps.onInfo ?? ((message: string) => console.log(message));
+
+  // Linux 服务器通常没有图形会话。此时调用 xdg-open 只会制造噪音；
+  // 直接给出可复制的 SSH 隧道命令，让用户从自己的电脑访问本地 Web UI。
+  if (platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+    onInfo(
+      `[WEB-UI] 未检测到 Linux 图形桌面，跳过自动打开浏览器。` +
+      `可在本机执行 ssh -L ${port}:127.0.0.1:${port} <user>@<server>，` +
+      `然后访问 ${url}`,
+    );
+    return false;
+  }
+
+  try {
+    let child: ChildProcess;
+    if (platform === "win32") {
+      // `start` 会把第一个带引号的参数当窗口标题，空字符串是必要占位符。
+      child = spawnImpl("cmd.exe", ["/c", "start", "", url], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } else if (platform === "darwin") {
+      child = spawnImpl("open", [url], { detached: true, stdio: "ignore" });
+    } else {
+      child = spawnImpl("xdg-open", [url], { detached: true, stdio: "ignore" });
+    }
+    child.on("error", (err) => {
+      onError(`[WEB-UI] 自动打开浏览器失败: ${err.message}`);
+    });
+    child.unref();
+    return true;
+  } catch (err) {
+    onError(`[WEB-UI] 自动打开浏览器失败: ${(err as Error).message}`);
+    return false;
+  }
+}

package/src/web-ui.ts

@@ -12,7 +12,12 @@ import { readFile, writeFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawn, execSync } from "node:child_process";
+import { spawn, execSync } from "node:child_process";
+import {
+  buildWebUiUrl,
+  createInternalRestartEnv,
+  openWebUiInDefaultBrowser,
+} from "./startup-lifecycle.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = join(__dirname, "..");
@@ -32,6 +37,7 @@ interface AppConfig {
     feishu?: { enabled?: boolean; platformType?: string };
     ilink?: { enabled?: boolean; reuseTokenOnStart?: boolean };
   };
+  webUi?: { openOnStart?: boolean };
   chromeDevtools?: { enabled?: boolean; port?: number; chromePath?: string };
   port?: number;
   gitTimeoutSeconds?: number;
@@ -225,11 +231,12 @@ function spawnService(): { ok: boolean; pid?: number; error?: string } {
     return { ok: false, error: `Entry not found: ${indexPath}` };
   }
   try {
-    const child = spawn("npx", ["tsx", "src/index.ts"], {
-      cwd: PROJECT_ROOT,
-      detached: true,
-      stdio: "ignore",
-      shell: true,
+    const child = spawn("npx", ["tsx", "src/index.ts"], {
+      cwd: PROJECT_ROOT,
+      detached: true,
+      stdio: "ignore",
+      shell: true,
+      env: createInternalRestartEnv(),
     });
     child.unref();
     return { ok: true, pid: child.pid ?? undefined };
@@ -247,17 +254,19 @@ function scheduleRestart(): void {
   if (!existsSync(indexPath)) return;
   if (process.platform === "win32") {
     // Windows: ping 作为 sleep（ping 自己 3 次 ≈ 2 秒延迟）
-    spawn("cmd.exe", ["/c", "ping -n 3 127.0.0.1 > nul && npx tsx src/index.ts"], {
-      cwd: PROJECT_ROOT,
-      detached: true,
-      stdio: "ignore",
-      windowsHide: true,
+    spawn("cmd.exe", ["/c", "ping -n 3 127.0.0.1 > nul && npx tsx src/index.ts"], {
+      cwd: PROJECT_ROOT,
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      env: createInternalRestartEnv(),
     }).unref();
   } else {
-    spawn("bash", ["-c", "sleep 2 && npx tsx src/index.ts"], {
-      cwd: PROJECT_ROOT,
-      detached: true,
-      stdio: "ignore",
+    spawn("bash", ["-c", "sleep 2 && npx tsx src/index.ts"], {
+      cwd: PROJECT_ROOT,
+      detached: true,
+      stdio: "ignore",
+      env: createInternalRestartEnv(),
     }).unref();
   }
 }
@@ -405,11 +414,14 @@ export function unflattenConfig(flat: Record<string, unknown>): Record<string, u
       result.platforms = result.platforms || {};
       (result.platforms as Record<string, unknown>).feishu = (result.platforms as Record<string, unknown>).feishu || {};
       ((result.platforms as Record<string, unknown>).feishu as Record<string, unknown>).platformType = val;
-    } else if (key === "CHATCCC_ILINK_ENABLED") {
-      result.platforms = result.platforms || {};
-      (result.platforms as Record<string, unknown>).ilink = (result.platforms as Record<string, unknown>).ilink || {};
-      ((result.platforms as Record<string, unknown>).ilink as Record<string, unknown>).enabled = val === true || val === "true";
-    } else if (key === "CHATCCC_CHROME_DEVTOOLS_ENABLED") {
+    } else if (key === "CHATCCC_ILINK_ENABLED") {
+      result.platforms = result.platforms || {};
+      (result.platforms as Record<string, unknown>).ilink = (result.platforms as Record<string, unknown>).ilink || {};
+      ((result.platforms as Record<string, unknown>).ilink as Record<string, unknown>).enabled = val === true || val === "true";
+    } else if (key === "CHATCCC_WEB_UI_OPEN_ON_START") {
+      result.webUi = result.webUi || {};
+      (result.webUi as Record<string, unknown>).openOnStart = val === true || val === "true";
+    } else if (key === "CHATCCC_CHROME_DEVTOOLS_ENABLED") {
       result.chromeDevtools = result.chromeDevtools || {};
       (result.chromeDevtools as Record<string, unknown>).enabled = val === true || val === "true";
     } else if (key === "CHATCCC_CHROME_DEVTOOLS_PORT") {
@@ -585,11 +597,29 @@ async function handleForgetIlink(_req: IncomingMessage, res: ServerResponse): Pr
   }
 }
 
-// ---------------------------------------------------------------------------
-// HTML page (embedded template)
-// ---------------------------------------------------------------------------
-
-export const PAGE_HTML = `<!DOCTYPE html>
+// ---------------------------------------------------------------------------
+// HTML page (embedded template)
+// ---------------------------------------------------------------------------
+
+/** Agent Team 的首个占位页面：按产品约定只展示标题，不提前放入功能内容。 */
+export const AGENT_TEAM_PAGE_HTML = `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Agent Team</title>
+<style>
+*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
+body{min-height:100vh;display:grid;place-items:center;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:radial-gradient(circle at 50% 20%,#312e81 0,#111827 42%,#020617 100%);color:#fff}
+h1{font-size:clamp(40px,8vw,88px);font-weight:750;letter-spacing:-.04em;text-shadow:0 12px 42px rgba(129,140,248,.45)}
+</style>
+</head>
+<body>
+  <h1>Agent Team</h1>
+</body>
+</html>`;
+
+export const PAGE_HTML = `<!DOCTYPE html>
 <html lang="zh-CN">
 <head>
 <meta charset="UTF-8">
@@ -598,9 +628,14 @@ export const PAGE_HTML = `<!DOCTYPE html>
 <style>
 *,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
 body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#f1f5f9;color:#1e293b;line-height:1.6}
-header{background:#0f172a;color:#fff;padding:16px 24px;display:flex;align-items:center;justify-content:space-between}
-header h1{font-size:20px;font-weight:600}
-header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500}
+header{background:#0f172a;color:#fff;padding:16px 24px;display:flex;align-items:center;justify-content:space-between}
+header h1{font-size:20px;font-weight:600}
+header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500}
+.header-actions{display:flex;align-items:center;gap:12px}
+.agent-team-entry{display:inline-flex;align-items:center;gap:8px;padding:9px 16px;border:1px solid rgba(255,255,255,.2);border-radius:999px;background:linear-gradient(135deg,#6366f1,#8b5cf6 55%,#d946ef);color:#fff;text-decoration:none;font-size:14px;font-weight:700;letter-spacing:.01em;box-shadow:0 8px 24px rgba(99,102,241,.38);transition:transform .18s ease,box-shadow .18s ease,filter .18s ease}
+.agent-team-entry:hover{transform:translateY(-2px);box-shadow:0 12px 30px rgba(139,92,246,.52);filter:saturate(1.16)}
+.agent-team-entry:focus-visible{outline:3px solid rgba(196,181,253,.65);outline-offset:3px}
+.agent-team-entry .agent-team-icon{font-size:16px;line-height:1}
 .badge-running{background:#16a34a;color:#fff}
 .badge-stopped{background:#94a3b8;color:#fff}
 /* container 完全不限宽、不留左右内边距 —— step-2 是三列卡片需要尽量利用屏幕；
@@ -668,14 +703,18 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
 .toast-error{background:#ef4444}
 @keyframes slideIn{from{transform:translateX(100%);opacity:0}to{transform:translateX(0);opacity:1}}
 .spinner{display:inline-block;width:14px;height:14px;border:2px solid rgba(255,255,255,.3);border-top-color:#fff;border-radius:50%;animation:spin .6s linear infinite}
-@keyframes spin{to{transform:rotate(360deg)}}
-</style>
+@keyframes spin{to{transform:rotate(360deg)}}
+@media(max-width:520px){header{padding:12px 14px}.header-actions{gap:8px}.agent-team-entry{padding:8px 11px;font-size:13px}header .badge{padding:4px 8px}}
+</style>
 </head>
 <body>
-<header>
-  <h1>ChatCCC</h1>
-  <span id="header-badge" class="badge badge-stopped">未启动</span>
-</header>
+<header>
+  <h1>ChatCCC</h1>
+  <div class="header-actions">
+    <a href="/agent-team" class="agent-team-entry"><span class="agent-team-icon" aria-hidden="true">✦</span>Agent Team <span aria-hidden="true">→</span></a>
+    <span id="header-badge" class="badge badge-stopped">未启动</span>
+  </div>
+</header>
 <div class="container">
 
   <!-- ===== Setup Wizard ===== -->
@@ -723,7 +762,7 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
         </div>
       </div>
 
-      <!-- 微信 iLink -->
+      <!-- 微信 iLink -->
       <div style="background:#f8fafc;border:1px solid #e2e8f0;border-radius:8px;padding:14px;margin-bottom:12px" id="platform-block-ilink">
         <div style="display:flex;align-items:center;justify-content:space-between">
           <div>
@@ -732,9 +771,20 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
           </div>
           <input type="checkbox" class="agent-toggle" id="platform-enable-ilink" checked onchange="onWizardPlatformToggle('ilink', this.checked)">
         </div>
-      </div>
-
-      <!-- Chrome CDP -->
+      </div>
+
+      <!-- Web UI 启动行为 -->
+      <div style="background:#f8fafc;border:1px solid #e2e8f0;border-radius:8px;padding:14px;margin-bottom:12px" id="web-ui-startup-block">
+        <div style="display:flex;align-items:center;justify-content:space-between;gap:16px">
+          <div>
+            <div style="font-weight:600;font-size:14px">启动时打开 Web UI</div>
+            <div style="font-size:12px;color:#64748b">直接运行 ChatCCC 时用系统默认浏览器打开管理页面；内部重启始终不打开</div>
+          </div>
+          <input type="checkbox" class="agent-toggle" id="field-CHATCCC_WEB_UI_OPEN_ON_START" checked>
+        </div>
+      </div>
+
+      <!-- Chrome CDP -->
       <div style="background:#f8fafc;border:1px solid #e2e8f0;border-radius:8px;padding:14px;margin-bottom:12px" id="chrome-devtools-block">
         <div style="display:flex;align-items:center;justify-content:space-between">
           <div>
@@ -938,8 +988,8 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
       </div>
     </details>
 
-    <details class="card config-section">
-      <summary>微信 iLink</summary>
+    <details class="card config-section">
+      <summary>微信 iLink</summary>
       <div class="section-detail">
         <div class="config-row">
           <span class="key">状态</span>
@@ -955,8 +1005,17 @@ header .badge{font-size:13px;padding:4px 12px;border-radius:12px;font-weight:500
         <div class="hint" style="margin-top:6px;line-height:1.6">生效范围：微信 iLink 开关变更需要重启 ChatCCC。</div>
       </div>
     </details>
-
-    <details class="card config-section">
+
+    <details class="card config-section">
+      <summary>Web UI</summary>
+      <div class="section-detail">
+        <div class="config-row"><span class="key">直接启动时自动打开</span><span class="val" id="cfg-WEB_UI_OPEN_ON_START">-</span></div>
+        <div class="hint" style="margin-top:6px;line-height:1.6">生效范围：下次直接启动生效；内部重启始终不打开。Linux 无图形桌面时会跳过打开并输出 SSH 隧道提示。</div>
+        <button class="btn btn-outline" style="margin-top:8px" onclick="editSection('webUi')">编辑</button>
+      </div>
+    </details>
+
+    <details class="card config-section">
       <summary>Chrome CDP（选填）</summary>
       <div class="section-detail">
         <div class="config-row"><span class="key">状态</span><span class="val" id="cfg-CHROME_DEVTOOLS_ENABLED">-</span></div>
@@ -1054,8 +1113,9 @@ const AGENT_FIELDS = {
   cursor: ['CHATCCC_CURSOR_PATH','CHATCCC_CURSOR_MODEL','CHATCCC_CURSOR_ALTERNATIVE_MODEL','CHATCCC_CURSOR_AVATAR_BATTERY_MODE','CHATCCC_CURSOR_ON_DEMAND_MONTHLY_BUDGET'],
   codex: ['CHATCCC_CODEX_PATH','CHATCCC_CODEX_MODEL','CHATCCC_CODEX_ALTERNATIVE_MODEL','CHATCCC_CODEX_EFFORT']
 };
-const FEISHU_FIELDS = ['CHATCCC_APP_ID','CHATCCC_APP_SECRET'];
-const CHROME_DEVTOOLS_FIELDS = ['CHATCCC_CHROME_DEVTOOLS_ENABLED','CHATCCC_CHROME_DEVTOOLS_PORT','CHATCCC_CHROME_DEVTOOLS_PATH'];
+const FEISHU_FIELDS = ['CHATCCC_APP_ID','CHATCCC_APP_SECRET'];
+const WEB_UI_FIELDS = ['CHATCCC_WEB_UI_OPEN_ON_START'];
+const CHROME_DEVTOOLS_FIELDS = ['CHATCCC_CHROME_DEVTOOLS_ENABLED','CHATCCC_CHROME_DEVTOOLS_PORT','CHATCCC_CHROME_DEVTOOLS_PATH'];
 
 function cursorBatteryModeLabel(value) {
   return value === 'onDemandUse' ? 'On demand use 金额' : 'API 使用比例';
@@ -1063,6 +1123,7 @@ function cursorBatteryModeLabel(value) {
 
 function configEffectHint(section) {
   if (section === 'feishu') return '生效范围：App ID、App Secret、平台类型或飞书开关变更需要重启 ChatCCC；其它未变更项仅保存。';
+  if (section === 'webUi') return '生效范围：下次直接启动生效；内部重启始终不打开。';
   if (section === 'chromeDevtools') return '生效范围：保存后立即应用到 Chrome CDP 守护进程。';
   if (section === 'claude') return '生效范围：保存后下一条消息或下个新会话生效，当前生成不中断。';
   if (section === 'cursor') return '生效范围：保存后下一条消息或下个新会话生效，当前生成不中断。';
@@ -1312,9 +1373,11 @@ function renderStep1() {
   // 飞书凭证字段初始显隐
   var credFields = document.getElementById('feishu-cred-fields');
   if (credFields) credFields.style.display = feishuEnabled ? '' : 'none';
-  var ilToggle = document.getElementById('platform-enable-ilink');
-  if (ilToggle) ilToggle.checked = ilinkEnabled;
-  var cd = c.chromeDevtools || {};
+  var ilToggle = document.getElementById('platform-enable-ilink');
+  if (ilToggle) ilToggle.checked = ilinkEnabled;
+  var webUiOpenOnStart = document.getElementById('field-CHATCCC_WEB_UI_OPEN_ON_START');
+  if (webUiOpenOnStart) webUiOpenOnStart.checked = !c.webUi || c.webUi.openOnStart !== false;
+  var cd = c.chromeDevtools || {};
   var cdpEnabled = document.getElementById('field-CHATCCC_CHROME_DEVTOOLS_ENABLED');
   if (cdpEnabled) cdpEnabled.checked = cd.enabled === true;
   prefillNested('field-CHATCCC_CHROME_DEVTOOLS_PORT', cd.port || 15166);
@@ -1418,9 +1481,11 @@ function collectAllFields() {
   // 平台类型（下拉选择框，始终发送以保持与服务端同步）
   var ptEl = document.getElementById('field-CHATCCC_FEISHU_PLATFORM_TYPE');
   if (ptEl && ptEl.value.trim()) vars['CHATCCC_FEISHU_PLATFORM_TYPE'] = ptEl.value.trim();
-  vars.CHATCCC_FEISHU_ENABLED = !!state.platformsEnabled.feishu;
-  vars.CHATCCC_ILINK_ENABLED = !!state.platformsEnabled.ilink;
-  var cdpEnabledEl = document.getElementById('field-CHATCCC_CHROME_DEVTOOLS_ENABLED');
+  vars.CHATCCC_FEISHU_ENABLED = !!state.platformsEnabled.feishu;
+  vars.CHATCCC_ILINK_ENABLED = !!state.platformsEnabled.ilink;
+  var webUiOpenOnStartEl = document.getElementById('field-CHATCCC_WEB_UI_OPEN_ON_START');
+  vars.CHATCCC_WEB_UI_OPEN_ON_START = !webUiOpenOnStartEl || !!webUiOpenOnStartEl.checked;
+  var cdpEnabledEl = document.getElementById('field-CHATCCC_CHROME_DEVTOOLS_ENABLED');
   vars.CHATCCC_CHROME_DEVTOOLS_ENABLED = !!(cdpEnabledEl && cdpEnabledEl.checked);
   var cdpPortEl = document.getElementById('field-CHATCCC_CHROME_DEVTOOLS_PORT');
   vars.CHATCCC_CHROME_DEVTOOLS_PORT = (cdpPortEl && cdpPortEl.value.trim()) ? cdpPortEl.value.trim() : '15166';
@@ -1469,14 +1534,17 @@ function renderStep3() {
     lines.push('<div class="config-row"><span class="key">平台类型</span><span class="val">' + ptLabel + '</span></div>');
   }
 
-  lines.push('<h3 style="margin:16px 0 8px">微信 iLink</h3>');
-  lines.push('<div class="config-row"><span class="key">状态</span><span class="val">' + (state.platformsEnabled.ilink ? '已启用' : '已禁用') + '</span></div>');
+  lines.push('<h3 style="margin:16px 0 8px">微信 iLink</h3>');
+  lines.push('<div class="config-row"><span class="key">状态</span><span class="val">' + (state.platformsEnabled.ilink ? '已启用' : '已禁用') + '</span></div>');
 
   if (!state.platformsEnabled.feishu && !state.platformsEnabled.ilink) {
-    lines.push('<div style="color:#ef4444;margin-top:8px">未启用任何平台</div>');
-  }
-
-  lines.push('<h3 style="margin:16px 0 8px">Chrome CDP</h3>');
+    lines.push('<div style="color:#ef4444;margin-top:8px">未启用任何平台</div>');
+  }
+
+  lines.push('<h3 style="margin:16px 0 8px">Web UI</h3>');
+  lines.push('<div class="config-row"><span class="key">直接启动时自动打开</span><span class="val">' + (vars.CHATCCC_WEB_UI_OPEN_ON_START ? '已启用' : '已禁用') + '</span></div>');
+
+  lines.push('<h3 style="margin:16px 0 8px">Chrome CDP</h3>');
   lines.push('<div class="config-row"><span class="key">状态</span><span class="val">' + (vars.CHATCCC_CHROME_DEVTOOLS_ENABLED ? '已启用' : '已禁用') + '</span></div>');
   if (vars.CHATCCC_CHROME_DEVTOOLS_ENABLED) {
     lines.push('<div class="config-row"><span class="key">CDP 端口</span><span class="val">' + (vars.CHATCCC_CHROME_DEVTOOLS_PORT || '15166') + '</span></div>');
@@ -1684,11 +1752,14 @@ function updateDashboardUI() {
 
   // 微信 iLink "忘记扫码" 按钮：仅在 ilink 已启用且有已保存 token 时显示
   var ilinkForgetRow = document.getElementById('ilink-forget-row');
-  if (ilinkForgetRow) {
-    ilinkForgetRow.style.display = (ilinkEnabled && state.ilinkAuthExists) ? '' : 'none';
-  }
-
-  var chromeDevtools = c.chromeDevtools || {};
+  if (ilinkForgetRow) {
+    ilinkForgetRow.style.display = (ilinkEnabled && state.ilinkAuthExists) ? '' : 'none';
+  }
+
+  var webUi = c.webUi || {};
+  document.getElementById('cfg-WEB_UI_OPEN_ON_START').textContent = webUi.openOnStart !== false ? '已启用' : '已禁用';
+
+  var chromeDevtools = c.chromeDevtools || {};
   var cdpPort = chromeDevtools.port || 15166;
   document.getElementById('cfg-CHROME_DEVTOOLS_ENABLED').textContent = chromeDevtools.enabled ? '已启用' : '已禁用';
   document.getElementById('cfg-CHROME_DEVTOOLS_PORT').textContent = String(cdpPort);
@@ -1771,22 +1842,24 @@ async function pollUntilRunning() {
 // ---- Edit Modal ----
 var editSectionType = null;
 
-function editSection(section) {
+function editSection(section) {
   editSectionType = section;
-  var fields;
-  if (section === 'feishu') fields = FEISHU_FIELDS;
-  else if (section === 'chromeDevtools') fields = CHROME_DEVTOOLS_FIELDS;
+  var fields;
+  if (section === 'feishu') fields = FEISHU_FIELDS;
+  else if (section === 'webUi') fields = WEB_UI_FIELDS;
+  else if (section === 'chromeDevtools') fields = CHROME_DEVTOOLS_FIELDS;
   else fields = AGENT_FIELDS[section] || [];
 
-  var titleMap = { feishu: '飞书', chromeDevtools: 'Chrome CDP', claude: 'Claude Agent', cursor: 'Cursor Agent', codex: 'Codex Agent' };
+  var titleMap = { feishu: '飞书', webUi: 'Web UI', chromeDevtools: 'Chrome CDP', claude: 'Claude Agent', cursor: 'Cursor Agent', codex: 'Codex Agent' };
   document.getElementById('edit-modal-title').textContent = '编辑 ' + (titleMap[section] || section);
 
   document.getElementById('edit-modal-effect').textContent = configEffectHint(section);
 
   var html = '';
-  var labelMap = {
-    'CHATCCC_APP_ID': 'App ID', 'CHATCCC_APP_SECRET': 'App Secret',
-    'CHATCCC_CHROME_DEVTOOLS_ENABLED': '启用常驻 Chrome CDP（选填）',
+  var labelMap = {
+    'CHATCCC_APP_ID': 'App ID', 'CHATCCC_APP_SECRET': 'App Secret',
+    'CHATCCC_WEB_UI_OPEN_ON_START': '直接启动 ChatCCC 时自动打开 Web UI',
+    'CHATCCC_CHROME_DEVTOOLS_ENABLED': '启用常驻 Chrome CDP（选填）',
     'CHATCCC_CHROME_DEVTOOLS_PORT': 'CDP 端口',
     'CHATCCC_CHROME_DEVTOOLS_PATH': 'Chrome 路径（选填）',
     'CHATCCC_ANTHROPIC_MODEL': '模型', 'CHATCCC_ANTHROPIC_SUBAGENT_MODEL': 'Subagent 模型', 'CHATCCC_ANTHROPIC_EFFORT': 'Effort',
@@ -1796,8 +1869,9 @@ function editSection(section) {
     'CHATCCC_CURSOR_ON_DEMAND_MONTHLY_BUDGET': '每月On demand use预算',
     'CHATCCC_CODEX_PATH': 'CLI 路径', 'CHATCCC_CODEX_MODEL': '模型', 'CHATCCC_CODEX_ALTERNATIVE_MODEL': '备选模型', 'CHATCCC_CODEX_EFFORT': 'Effort'
   };
-  var hintMap = {
-    'CHATCCC_CHROME_DEVTOOLS_ENABLED': '依赖：本机 Google Chrome；ChatGPT 订阅到期查询需要在该 CDP Chrome 中登录 ChatGPT。',
+  var hintMap = {
+    'CHATCCC_WEB_UI_OPEN_ON_START': '关闭后可继续手动访问 http://localhost:<端口>/；/restart、/update 和 Web UI 重启无论此项为何值都不会自动打开。',
+    'CHATCCC_CHROME_DEVTOOLS_ENABLED': '依赖：本机 Google Chrome；ChatGPT 订阅到期查询需要在该 CDP Chrome 中登录 ChatGPT。',
     'CHATCCC_CHROME_DEVTOOLS_PORT': '默认 15166，健康检查端点为 http://127.0.0.1:15166/json/version。',
     'CHATCCC_CHROME_DEVTOOLS_PATH': '选填。留空时自动探测 Google Chrome。'
   };
@@ -1810,10 +1884,12 @@ function editSection(section) {
     var val = state.config[key] || '';
     // Also check nested config
     if (!val) {
-      if (section === 'feishu') {
+      if (section === 'feishu') {
         if (key === 'CHATCCC_APP_ID' && state.config.feishu) val = state.config.feishu.appId || '';
         else if (key === 'CHATCCC_APP_SECRET' && state.config.feishu) val = state.config.feishu.appSecret || '';
-      } else if (section === 'chromeDevtools' && state.config.chromeDevtools) {
+      } else if (section === 'webUi') {
+        val = !state.config.webUi || state.config.webUi.openOnStart !== false ? 'true' : 'false';
+      } else if (section === 'chromeDevtools' && state.config.chromeDevtools) {
         if (key === 'CHATCCC_CHROME_DEVTOOLS_ENABLED') val = state.config.chromeDevtools.enabled === true ? 'true' : 'false';
         else if (key === 'CHATCCC_CHROME_DEVTOOLS_PORT') val = state.config.chromeDevtools.port != null ? String(state.config.chromeDevtools.port) : '15166';
         else if (key === 'CHATCCC_CHROME_DEVTOOLS_PATH') val = state.config.chromeDevtools.chromePath || '';
@@ -1838,9 +1914,10 @@ function editSection(section) {
       }
     }
     var isSecret = key.includes('SECRET') || key.includes('API_KEY');
-    if (key === 'CHATCCC_CHROME_DEVTOOLS_ENABLED') {
-      var checked = val === true || val === 'true';
-      html += '<div class="form-group"><label style="display:flex;align-items:center;gap:8px"><input type="checkbox" id="edit-' + key + '"' + (checked ? ' checked' : '') + ' onchange="toggleEditChromeDevtoolsFields(this.checked)"> ' + (labelMap[key] || key) + '</label>';
+    if (key === 'CHATCCC_WEB_UI_OPEN_ON_START' || key === 'CHATCCC_CHROME_DEVTOOLS_ENABLED') {
+      var checked = val === true || val === 'true';
+      var changeHandler = key === 'CHATCCC_CHROME_DEVTOOLS_ENABLED' ? ' onchange="toggleEditChromeDevtoolsFields(this.checked)"' : '';
+      html += '<div class="form-group"><label style="display:flex;align-items:center;gap:8px"><input type="checkbox" id="edit-' + key + '"' + (checked ? ' checked' : '') + changeHandler + '> ' + (labelMap[key] || key) + '</label>';
       if (hintMap[key]) html += '<div class="hint" style="margin-top:6px;line-height:1.5">' + hintMap[key] + '</div>';
       html += '</div>';
     } else if (key === 'CHATCCC_CURSOR_AVATAR_BATTERY_MODE') {
@@ -1894,17 +1971,18 @@ function closeEditModal() {
   editSectionType = null;
 }
 
-async function saveEdit() {
-  var fields;
-  if (editSectionType === 'feishu') fields = FEISHU_FIELDS;
-  else if (editSectionType === 'chromeDevtools') fields = CHROME_DEVTOOLS_FIELDS;
+async function saveEdit() {
+  var fields;
+  if (editSectionType === 'feishu') fields = FEISHU_FIELDS;
+  else if (editSectionType === 'webUi') fields = WEB_UI_FIELDS;
+  else if (editSectionType === 'chromeDevtools') fields = CHROME_DEVTOOLS_FIELDS;
   else fields = AGENT_FIELDS[editSectionType] || [];
 
   var vars = {};
   fields.forEach(function(key){
     var el = document.getElementById('edit-' + key);
     if (!el) return;
-    if (key === 'CHATCCC_CHROME_DEVTOOLS_ENABLED') vars[key] = !!el.checked;
+    if (key === 'CHATCCC_WEB_UI_OPEN_ON_START' || key === 'CHATCCC_CHROME_DEVTOOLS_ENABLED') vars[key] = !!el.checked;
     else vars[key] = el.value.trim();
   });
   if (editSectionType === 'chromeDevtools' && !vars.CHATCCC_CHROME_DEVTOOLS_PORT) {
@@ -1960,9 +2038,10 @@ init();
 // Router
 // ---------------------------------------------------------------------------
 
-async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
-  const url = req.url ?? "/";
-  const method = req.method ?? "GET";
+async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const url = req.url ?? "/";
+  const method = req.method ?? "GET";
+  const pathname = url.split("?", 1)[0];
 
   if (extraApiHandler && await extraApiHandler(req, res)) return;
 
@@ -1975,7 +2054,13 @@ async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise
   if (url === "/api/stop" && method === "POST") return handleStopService(req, res);
   if (url === "/api/restart" && method === "POST") return handleRestartService(req, res);
   if (url === "/api/validate" && method === "POST") return handleValidate(req, res);
-  if (url === "/api/ilink/forget" && method === "POST") return handleForgetIlink(req, res);
+  if (url === "/api/ilink/forget" && method === "POST") return handleForgetIlink(req, res);
+
+  if (method === "GET" && (pathname === "/agent-team" || pathname === "/agent-team/")) {
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(AGENT_TEAM_PAGE_HTML);
+    return;
+  }
 
   // Serve HTML page for all other GET requests
   if (method === "GET") {
@@ -2000,40 +2085,7 @@ export function createUiRouter(): (req: IncomingMessage, res: ServerResponse) =>
 // Setup mode entry point — called from index.ts when no credentials
 // ---------------------------------------------------------------------------
 
-/**
- * 跨平台调起本地浏览器。
- * - Windows：cmd /c start "" <url>。注意 start 把第一个被引号包裹的参数当成"窗口标题"，
- *   所以这里需要传一个空标题占位，否则当 url 被引号包住时它会被错误地当成标题。
- * - macOS：open <url>
- * - Linux：xdg-open <url>
- *
- * 任何失败都不抛——主流程不依赖浏览器是否真的弹起来，console 已经打印了 url。
- */
-function openInBrowser(url: string): void {
-  try {
-    if (process.platform === "win32") {
-      const child = spawn("cmd.exe", ["/c", "start", "", url], {
-        detached: true,
-        stdio: "ignore",
-        windowsHide: true,
-      });
-      child.on("error", () => { /* 浏览器未弹起来不影响主流程 */ });
-      child.unref();
-    } else if (process.platform === "darwin") {
-      const child = spawn("open", [url], { detached: true, stdio: "ignore" });
-      child.on("error", () => {});
-      child.unref();
-    } else {
-      const child = spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
-      child.on("error", () => {});
-      child.unref();
-    }
-  } catch (err) {
-    console.error(`[WEB-UI] 自动打开浏览器失败: ${(err as Error).message}`);
-  }
-}
-
-/**
+/**
  * setup → service「在线切换」回调签名：
  *   - 入参 httpServer：setup 模式当前监听的 HTTP server，会被复用为 service 的
  *     relay server（避免 close + recreate 的端口竞态）。
@@ -2045,8 +2097,10 @@ export type SetupActivateHook = (
   httpServer: ReturnType<typeof createServer>,
 ) => Promise<{ ok: true } | { ok: false; error: string }>;
 
-export interface StartSetupModeOptions {
-  onActivate?: SetupActivateHook;
+export interface StartSetupModeOptions {
+  onActivate?: SetupActivateHook;
+  /** 内部重启进入 setup 模式时设为 false，避免重复弹出系统浏览器。 */
+  openBrowser?: boolean;
 }
 
 // setup HTTP server + onActivate 回调通过模块级变量暴露给 handleStartService。
@@ -2093,20 +2147,24 @@ export function startSetupMode(port: number, options: StartSetupModeOptions = {}
     process.exit(1);
   });
 
-  server.listen(port, "127.0.0.1", () => {
-    const url = `http://127.0.0.1:${port}`;
+  server.listen(port, "127.0.0.1", () => {
+    const url = buildWebUiUrl(port);
     console.log("");
     console.log("=".repeat(60));
     console.log("  ChatCCC — 首次配置向导");
     console.log("=".repeat(60));
     console.log("  未检测到已配置的飞书凭证，已启动配置界面。");
-    console.log(`  正在自动打开浏览器: ${url}`);
+    if (options.openBrowser !== false) {
+      console.log(`  已启用启动时自动打开浏览器: ${url}`);
+    } else {
+      console.log(`  内部重启不会自动打开浏览器，请按需访问: ${url}`);
+    }
     console.log("  若浏览器未自动弹出，请手动访问上面的地址。");
     console.log("");
     console.log("  在向导里填好 App ID / App Secret 后点「保存并启动」，");
     console.log("  服务会在当前进程内直接激活，不需要重新运行 chatccc。");
     console.log("=".repeat(60));
     console.log("");
-    openInBrowser(url);
-  });
-}
+    if (options.openBrowser !== false) openWebUiInDefaultBrowser(port);
+  });
+}