@ww-ai-lab/openclaw-office 2026.3.6 → 2026.3.8

package/README.md

@@ -33,7 +33,19 @@
 
 #### Demo Video
 
-https://github.com/WW-AI-Lab/openclaw-office/raw/main/assets/iShot_2026-03-02_21.33.38.mp4
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=ACXSFTSlVLY">
+    <img src="https://img.youtube.com/vi/ACXSFTSlVLY/maxresdefault.jpg" alt="OpenClaw Office Demo Video" width="100%" />
+  </a>
+</p>
+
+<p align="center">
+  ▶ Click the preview image above to play on YouTube
+</p>
+
+> GitHub sanitizes repository README content and does not allow embedded YouTube/iframe players, so the most reliable “preview + click-to-play” pattern is a linked video thumbnail.
+
+[Watch on YouTube](https://www.youtube.com/watch?v=ACXSFTSlVLY)
 
 ### Console
 
@@ -124,6 +136,15 @@ OPENCLAW_GATEWAY_TOKEN=<token> openclaw-office
 | `--host <host>`       | Bind address          | `0.0.0.0`              |
 | `-h, --help`          | Show help             | —                      |
 
+The production server exposes Office publicly and proxies browser WebSocket traffic through the same origin path `/gateway-ws`. Its upstream Gateway address is resolved in this order:
+
+1. `--gateway`
+2. `OPENCLAW_GATEWAY_URL`
+3. persisted Office config at `~/.openclaw/openclaw-office.json`
+4. default `ws://localhost:18789`
+
+When `--gateway` or `OPENCLAW_GATEWAY_URL` is provided, Office automatically persists the value to `~/.openclaw/openclaw-office.json` for future restarts.
+
 > **Note:** This serves the pre-built production bundle. For development with hot reload, see [Development](#development) below.
 
 ---
@@ -138,11 +159,10 @@ pnpm install
 
 ### 2. Configure Gateway Connection
 
-Create a `.env.local` file (gitignored) with your Gateway connection details:
+Create a `.env.local` file (gitignored) with your Gateway token. `VITE_GATEWAY_URL` is optional and only needed if you want dev mode to proxy to a Gateway address other than the default `ws://localhost:18789`.
 
 ```bash
 cat > .env.local << 'EOF'
-VITE_GATEWAY_URL=ws://localhost:18789
 VITE_GATEWAY_TOKEN=<your-gateway-token>
 EOF
 ```
@@ -179,13 +199,13 @@ Ensure the OpenClaw Gateway is running on the configured address (default `local
 pnpm dev
 ```
 
-Open `http://localhost:5180` in your browser.
+Open `http://localhost:5180` in your browser. In dev mode, the frontend always connects to the same-origin path `/gateway-ws`, and Vite proxies that path to the configured Gateway upstream (default `ws://localhost:18789`). `VITE_GATEWAY_URL` configures the proxy upstream and is not used as a browser-direct websocket URL.
 
 ### Environment Variables
 
 | Variable             | Required                              | Default                | Description                          |
 | -------------------- | ------------------------------------- | ---------------------- | ------------------------------------ |
-| `VITE_GATEWAY_URL`   | No                                    | `ws://localhost:18789` | Gateway WebSocket address            |
+| `VITE_GATEWAY_URL`   | No                                    | `ws://localhost:18789` | Optional override for the dev proxy upstream Gateway address |
 | `VITE_GATEWAY_TOKEN` | Yes (when connecting to real Gateway) | —                      | Gateway auth token                   |
 | `VITE_MOCK`          | No                                    | `false`                | Enable mock mode (no Gateway needed) |
 

package/README.zh.md

@@ -33,7 +33,19 @@
 
 #### 演示视频
 
-https://github.com/WW-AI-Lab/openclaw-office/raw/main/assets/iShot_2026-03-02_21.33.38.mp4
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=ACXSFTSlVLY">
+    <img src="https://img.youtube.com/vi/ACXSFTSlVLY/maxresdefault.jpg" alt="OpenClaw Office 演示视频" width="100%" />
+  </a>
+</p>
+
+<p align="center">
+  ▶ 点击上方预览图即可跳转播放
+</p>
+
+> GitHub 会清洗仓库 README 内容，不允许真正内嵌 YouTube / iframe 播放器，所以最稳妥的实现方式就是“预览图 + 点击播放跳转”。
+
+[在 YouTube 观看](https://www.youtube.com/watch?v=ACXSFTSlVLY)
 
 ### 控制台
 
@@ -124,6 +136,15 @@ OPENCLAW_GATEWAY_TOKEN=<token> openclaw-office
 | `--host <host>`       | 绑定地址               | `0.0.0.0`              |
 | `-h, --help`          | 显示帮助               | —                      |
 
+生产服务端会对外暴露 Office，并通过同源路径 `/gateway-ws` 代理浏览器的 WebSocket 流量。其上游 Gateway 地址按以下优先级解析：
+
+1. `--gateway`
+2. `OPENCLAW_GATEWAY_URL`
+3. Office 持久化配置 `~/.openclaw/openclaw-office.json`
+4. 默认值 `ws://localhost:18789`
+
+当提供 `--gateway` 或 `OPENCLAW_GATEWAY_URL` 时，Office 会自动将该值持久化到 `~/.openclaw/openclaw-office.json`，供后续重启复用。
+
 > **说明：** 此方式运行的是预构建的生产版本。如需热重载开发，请参见下方 [开发](#开发) 部分。
 
 ---
@@ -138,11 +159,10 @@ pnpm install
 
 ### 2. 配置 Gateway 连接
 
-创建 `.env.local` 文件（已在 `.gitignore` 中，不会被提交），填入 Gateway 连接信息：
+创建 `.env.local` 文件（已在 `.gitignore` 中，不会被提交），填入 Gateway token。`VITE_GATEWAY_URL` 是可选项，仅在你希望 dev 模式代理到非默认 `ws://localhost:18789` 地址时才需要填写：
 
 ```bash
 cat > .env.local << 'EOF'
-VITE_GATEWAY_URL=ws://localhost:18789
 VITE_GATEWAY_TOKEN=<你的 gateway token>
 EOF
 ```
@@ -179,13 +199,13 @@ openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true
 pnpm dev
 ```
 
-在浏览器中打开 `http://localhost:5180`。
+在浏览器中打开 `http://localhost:5180`。在 dev 模式下，前端始终连接同源路径 `/gateway-ws`，再由 Vite 将该路径代理到配置的 Gateway 上游地址（默认 `ws://localhost:18789`）。`VITE_GATEWAY_URL` 仅用于配置代理上游，不会作为浏览器直连 WebSocket 地址使用。
 
 ### 环境变量
 
 | 变量                 | 必须                      | 默认值                 | 说明                             |
 | -------------------- | ------------------------- | ---------------------- | -------------------------------- |
-| `VITE_GATEWAY_URL`   | 否                        | `ws://localhost:18789` | Gateway WebSocket 地址           |
+| `VITE_GATEWAY_URL`   | 否                        | `ws://localhost:18789` | 可选：覆盖 dev 代理的上游 Gateway 地址 |
 | `VITE_GATEWAY_TOKEN` | 是（连接真实 Gateway 时） | —                      | Gateway 认证 token               |
 | `VITE_MOCK`          | 否                        | `false`                | 启用 Mock 模式（不需要 Gateway） |
 

package/bin/openclaw-office-config.d.ts

@@ -0,0 +1,44 @@
+export const DEFAULT_GATEWAY_URL: string;
+export const DEFAULT_PORT: number;
+export const DEFAULT_HOST: string;
+export const DEFAULT_PROXY_PATH: string;
+
+export interface ParsedArgs {
+  token: string;
+  gatewayUrl: string;
+  port: number;
+  host: string;
+  help?: boolean;
+}
+
+export interface ResolvedConfig {
+  token: string;
+  tokenSource: string;
+  gatewayUrl: string;
+  gatewayUrlSource: string;
+  port: number;
+  host: string;
+  officeConfigPath: string;
+  browserGatewayUrl: string;
+  shouldPersistGatewayUrl: boolean;
+}
+
+export function getOfficeConfigPath(homeDir?: string): string;
+export function parseArgs(argv?: string[]): ParsedArgs;
+export function printHelp(): void;
+export function readTokenFromConfig(
+  homeDir?: string,
+): { token: string; source: string } | null;
+export function readPersistedOfficeConfig(
+  configPath?: string,
+): { gatewayUrl: string } | null;
+export function writePersistedOfficeConfig(gatewayUrl: string, configPath?: string): void;
+export function normalizeGatewayAccessUrl(rawGatewayUrl: string): {
+  gatewayUrl: string;
+  token: string;
+};
+export function resolveConfig(options?: {
+  argv?: string[];
+  env?: NodeJS.ProcessEnv | Record<string, string>;
+  homeDir?: string;
+}): ResolvedConfig;

package/bin/openclaw-office-config.js

@@ -0,0 +1,219 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_GATEWAY_URL = "ws://localhost:18789";
+export const DEFAULT_PORT = 5180;
+export const DEFAULT_HOST = "0.0.0.0";
+export const DEFAULT_PROXY_PATH = "/gateway-ws";
+const TOKEN_QUERY_PARAM = "token";
+
+export function getOfficeConfigPath(homeDir = homedir()) {
+  return join(homeDir, ".openclaw", "openclaw-office.json");
+}
+
+export function parseArgs(argv = process.argv.slice(2)) {
+  const result = { token: "", gatewayUrl: "", port: 0, host: "" };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+    if ((arg === "--token" || arg === "-t") && next) {
+      result.token = next;
+      i++;
+    } else if ((arg === "--gateway" || arg === "-g") && next) {
+      result.gatewayUrl = next;
+      i++;
+    } else if ((arg === "--port" || arg === "-p") && next) {
+      result.port = parseInt(next, 10);
+      i++;
+    } else if (arg === "--host" && next) {
+      result.host = next;
+      i++;
+    } else if (arg === "--help" || arg === "-h") {
+      result.help = true;
+    }
+  }
+  return result;
+}
+
+export function printHelp() {
+  console.log(`
+  \x1b[36mOpenClaw Office\x1b[0m — Visual monitoring frontend for OpenClaw
+
+  \x1b[1mUsage:\x1b[0m
+    openclaw-office [options]
+
+  \x1b[1mOptions:\x1b[0m
+    -t, --token <token>      Gateway auth token
+    -g, --gateway <url>      Gateway WebSocket URL (default: ws://localhost:18789)
+    -p, --port <port>        Server port (default: 5180, or PORT env)
+    --host <host>            Bind address (default: 0.0.0.0)
+    -h, --help               Show this help
+
+  \x1b[1mGateway URL persistence:\x1b[0m
+    The upstream Gateway URL is resolved in this order:
+    1. --gateway flag
+    2. OPENCLAW_GATEWAY_URL environment variable
+    3. Persisted Office config at ~/.openclaw/openclaw-office.json
+    4. Default ws://localhost:18789
+
+  \x1b[1mToken auto-detection:\x1b[0m
+    The token is resolved in this order:
+    1. --token flag
+    2. OPENCLAW_GATEWAY_TOKEN environment variable
+    3. Auto-read from ~/.openclaw/openclaw.json
+
+  \x1b[1mExamples:\x1b[0m
+    openclaw-office
+    openclaw-office --token my-secret-token
+    openclaw-office --gateway ws://192.168.1.100:18789
+    PORT=3000 openclaw-office
+`);
+}
+
+export function readTokenFromConfig(homeDir = homedir()) {
+  const candidates = [
+    join(homeDir, ".openclaw", "openclaw.json"),
+    join(homeDir, ".clawdbot", "clawdbot.json"),
+  ];
+
+  for (const filePath of candidates) {
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      const config = JSON.parse(raw);
+      const token = config?.gateway?.auth?.token;
+      if (token && typeof token === "string") {
+        return { token, source: filePath };
+      }
+    } catch {
+      // file not found or parse error
+    }
+  }
+
+  return null;
+}
+
+export function readPersistedOfficeConfig(configPath = getOfficeConfigPath()) {
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const gatewayUrl = parsed?.gatewayUrl;
+    if (typeof gatewayUrl !== "string" || gatewayUrl.length === 0) {
+      return null;
+    }
+    return { gatewayUrl };
+  } catch {
+    return null;
+  }
+}
+
+export function writePersistedOfficeConfig(
+  gatewayUrl,
+  configPath = getOfficeConfigPath(),
+) {
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify({ gatewayUrl }, null, 2)}\n`, "utf-8");
+}
+
+function formatParsedUrl(parsed, original) {
+  const serialized = parsed.toString();
+  if (/^[a-z]+:\/\/[^/?#]+(?:\?[^#]*)?(?:#.*)?$/i.test(original)) {
+    return serialized.replace(/\/$/, "");
+  }
+  return serialized;
+}
+
+export function normalizeGatewayAccessUrl(rawGatewayUrl) {
+  if (!rawGatewayUrl) {
+    return { gatewayUrl: rawGatewayUrl, token: "" };
+  }
+
+  try {
+    const parsed = new URL(rawGatewayUrl);
+    const token = parsed.searchParams.get(TOKEN_QUERY_PARAM) ?? "";
+    parsed.searchParams.delete(TOKEN_QUERY_PARAM);
+
+    if (parsed.protocol === "http:") {
+      parsed.protocol = "ws:";
+    } else if (parsed.protocol === "https:") {
+      parsed.protocol = "wss:";
+    }
+
+    return { gatewayUrl: formatParsedUrl(parsed, rawGatewayUrl), token };
+  } catch {
+    return { gatewayUrl: rawGatewayUrl, token: "" };
+  }
+}
+
+export function resolveConfig({
+  argv = process.argv.slice(2),
+  env = process.env,
+  homeDir = homedir(),
+} = {}) {
+  const args = parseArgs(argv);
+  const officeConfigPath = getOfficeConfigPath(homeDir);
+  const persisted = readPersistedOfficeConfig(officeConfigPath);
+
+  let token = "";
+  let tokenSource = "";
+
+  if (args.token) {
+    token = args.token;
+    tokenSource = "command line --token";
+  } else if (env.OPENCLAW_GATEWAY_TOKEN) {
+    token = env.OPENCLAW_GATEWAY_TOKEN;
+    tokenSource = "OPENCLAW_GATEWAY_TOKEN env";
+  } else {
+    const fromFile = readTokenFromConfig(homeDir);
+    if (fromFile) {
+      token = fromFile.token;
+      tokenSource = fromFile.source;
+    }
+  }
+
+  let gatewayUrl = DEFAULT_GATEWAY_URL;
+  let gatewayUrlSource = "default";
+  if (persisted?.gatewayUrl) {
+    gatewayUrl = persisted.gatewayUrl;
+    gatewayUrlSource = officeConfigPath;
+  }
+  if (env.OPENCLAW_GATEWAY_URL) {
+    gatewayUrl = env.OPENCLAW_GATEWAY_URL;
+    gatewayUrlSource = "OPENCLAW_GATEWAY_URL env";
+  }
+  if (args.gatewayUrl) {
+    gatewayUrl = args.gatewayUrl;
+    gatewayUrlSource = "command line --gateway";
+  }
+
+  const normalizedGateway = normalizeGatewayAccessUrl(gatewayUrl);
+  gatewayUrl = normalizedGateway.gatewayUrl || gatewayUrl;
+
+  if (!token && normalizedGateway.token) {
+    token = normalizedGateway.token;
+    tokenSource = `${gatewayUrlSource} token query`;
+  }
+
+  const port = args.port || parseInt(env.PORT || `${DEFAULT_PORT}`, 10);
+  const host = args.host || env.HOST || DEFAULT_HOST;
+  const shouldPersistGatewayUrl =
+    !!gatewayUrl &&
+    (gatewayUrlSource === "command line --gateway" || gatewayUrlSource === "OPENCLAW_GATEWAY_URL env") &&
+    gatewayUrl !== persisted?.gatewayUrl;
+
+  return {
+    token,
+    tokenSource,
+    gatewayUrl,
+    gatewayUrlSource,
+    port,
+    host,
+    officeConfigPath,
+    browserGatewayUrl: DEFAULT_PROXY_PATH,
+    shouldPersistGatewayUrl,
+  };
+}

package/bin/openclaw-office-server.d.ts

@@ -0,0 +1,34 @@
+import type { Server as HttpServer, IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+
+export const MIME_TYPES: Record<string, string>;
+
+export interface OfficeServerConfig {
+  gatewayUrl: string;
+  browserGatewayUrl: string;
+  token: string;
+  port?: number;
+  host?: string;
+  gatewayUrlSource?: string;
+  tokenSource?: string;
+}
+
+export function createRuntimeConfigScript(config: {
+  browserGatewayUrl: string;
+  token: string;
+}): string;
+export function formatStartupSummary(config: OfficeServerConfig): string;
+export function proxyWebSocketUpgrade(
+  req: IncomingMessage,
+  downstreamSocket: Duplex,
+  downstreamHead: Buffer,
+  config: OfficeServerConfig,
+): void;
+export function createOfficeServer(options: {
+  config: OfficeServerConfig;
+  distDir: string;
+  createHttpServer?: typeof import("node:http").createServer;
+}): {
+  server: HttpServer;
+  getIndexHtml: () => Promise<string>;
+};