Add localized runtime launcher and CLI entrypoint

Author: Hyper66666

README.md

@@ -11,7 +11,7 @@ The codebase is feature-rich and the repository gate is now green locally. As of
 Latest local evidence on March 12, 2026 (Windows, Node `v20.11.0` with engine warning):
 
 - `pnpm run build`: pass
-- `pnpm run test`: pass (`33` test files, `217` tests)
+- `pnpm run test`: pass (`36` test files, `225` tests)
 - `pnpm run test:integration`: pass (`6` test files, `20` tests)
 - `pnpm run verify`: pass
 
@@ -94,6 +94,42 @@ Notes:
 - The gateway API runs on `http://localhost:4100` by default.
 - The standalone scheduler health endpoint runs on `http://localhost:4500/health` by default.
 
+## One-Click Local Runtime
+
+For a local all-in-one SenClaw session, use the launcher scripts:
+
+```bash
+# Windows
+scripts\\start-senclaw.cmd
+scripts\\stop-senclaw.cmd
+
+# Linux
+./scripts/start-senclaw.sh
+./scripts/stop-senclaw.sh
+```
+
+The launcher bootstraps the local runtime under `.tmp/live-run`, starts the gateway and web console, reuses a persistent bootstrap admin key, and prints a startup banner with:
+
+- current model ID
+- admin key
+- web console URL
+- gateway URL
+- runtime log directory
+
+The web console header includes an `EN / 中文` locale toggle. The selected language is persisted and applied in two places:
+
+- immediately for web console copy via browser storage
+- on the next launcher start via `.tmp/live-run/runtime-settings.json`
+
+If you are already in the repository root on Windows `cmd`, you can use the shorter wrapper command directly:
+
+```bat
+senclaw start
+senclaw stop
+```
+
+This wrapper forwards to the local CLI in `packages/cli` and behaves like the launcher scripts.
+
 ## Authentication
 
 Gateway API routes under `/api/v1/*` require a bearer API key by default.

README.zh-CN.md

@@ -4,14 +4,14 @@
 
 Senclaw 是一个 AI Agent 编排平台，具备持久化存储、API Key 鉴权、Web Console、连接器接入、任务调度以及沙箱化工具执行能力。
 
-当前代码库功能已经比较完整，本地仓库门禁也已经恢复为绿色。截至 2026 年 3 月 12 日，最新一次 Windows 本地验证中，`build`、`test`、`test:integration` 和 `verify` 都已通过。RabbitMQ 与 Redis Streams 队列驱动已经在仓库内实现，并带有单元测试覆盖及默认的 gateway 接线，但基于真实 broker 的发布级验证证据仍未补齐。同时，项目也已经记录了真实 OpenAI-compatible provider 的 smoke 结果，因此当前剩余的基础上线工作主要收敛为：在 Node 22 环境复验，以及补齐受保护 Web Console 的验收记录。
+当前代码库功能已经比较完整，仓库门禁也已在本地恢复为绿色。截止 2026 年 3 月 12 日，最新一次 Windows 本地验证中，`build`、`test`、`test:integration` 和 `verify` 均已通过。RabbitMQ 与 Redis Streams 队列驱动已经在仓库内实现，并带有单元测试覆盖和默认 gateway 接线，但基于真实 broker 的发布级验证证据仍待补齐。与此同时，项目也已经记录了真实 OpenAI-compatible provider 的 smoke 结果，因此当前剩余的基础上线工作主要收敛为：在 Node 22 环境复验，以及补齐受保护 Web Console 的验收记录。
 
 ## 就绪度快照
 
 截至 2026 年 3 月 12 日的最新本地证据（Windows，Node `v20.11.0`，因此会出现 engine warning）：
 
 - `pnpm run build`：通过
-- `pnpm run test`：通过（`33` 个测试文件，`217` 个测试）
+- `pnpm run test`：通过（`36` 个测试文件，`225` 个测试）
 - `pnpm run test:integration`：通过（`6` 个测试文件，`20` 个测试）
 - `pnpm run verify`：通过
 
@@ -24,7 +24,7 @@ Senclaw 是一个 AI Agent 编排平台，具备持久化存储、API Key 鉴权
 
 ## 仓库结构
 
-应用：
+Applications：
 
 - `@senclaw/gateway`：Fastify API 与管理入口
 - `@senclaw/agent-runner`：Agent 执行运行时
@@ -94,11 +94,47 @@ corepack pnpm --filter @senclaw/web dev
 - Gateway API 默认运行在 `http://localhost:4100`
 - 独立 scheduler 健康检查默认运行在 `http://localhost:4500/health`
 
+## 一键本地运行
+
+如果你想快速启动一套本地可用的 Senclaw，可直接使用启动脚本：
+
+```bash
+# Windows
+scripts\start-senclaw.cmd
+scripts\stop-senclaw.cmd
+
+# Linux
+./scripts/start-senclaw.sh
+./scripts/stop-senclaw.sh
+```
+
+启动脚本会在 `.tmp/live-run` 下初始化本地运行目录，启动 gateway 和 web console，复用持久化 bootstrap admin key，并在终端打印启动摘要，包含：
+
+- 当前模型 ID
+- admin key
+- Web Console 地址
+- gateway 地址
+- 运行日志目录
+
+Web Console 头部右上角提供 `EN / 中文` 语言切换按钮。所选语言会持久化，并分别作用于：
+
+- 当前浏览器里的 Web Console 文案
+- 下一次启动脚本运行时的终端输出文案（通过 `.tmp/live-run/runtime-settings.json`）
+
+如果你已经在仓库根目录的 Windows `cmd` 里，也可以直接使用更短的命令：
+
+```bat
+senclaw start
+senclaw stop
+```
+
+这个包装器会转发到 `packages/cli` 里的本地 CLI，行为和启动脚本一致。
+
 ## 鉴权
 
-默认情况下，Gateway 下 `/api/v1/*` 路由都需要 Bearer API Key。
+默认情况下，Gateway 中 `/api/v1/*` 路由都需要 Bearer API Key。
 
-创建或引导一个 key：
+创建或引导一把 key：
 
 ```bash
 corepack pnpm run auth:bootstrap-admin
@@ -108,7 +144,7 @@ Web Console 当前支持轻量级 API Key session。使用 agents、runs 或 tas
 
 ## 真实 Provider Smoke 测试
 
-Senclaw 提供了一个不把密钥写入仓库的 OpenAI-compatible provider smoke 路径。在本地设置以下环境变量：
+Senclaw 提供了一条不把密钥写入仓库的 OpenAI-compatible provider smoke 路径。先在本地设置以下环境变量：
 
 ```bash
 SENCLAW_OPENAI_API_KEY=<你的 key>
@@ -150,7 +186,7 @@ corepack pnpm run verify
 
 项目从“本地全绿”到“可以正式宣称部署就绪”之间，还剩这些事项：
 
-- 在受支持的 Node 22 环境中重新跑一遍 readiness matrix
+- 在受支持的 Node 22 环境中重跑一遍 readiness matrix
 - 记录一次开启鉴权后的 Web Console 验收
 - 如果要对外宣称 broker-backed queue 已具备发布级支持，则需要补齐 RabbitMQ 和 Redis 的真实 broker 验证
 - 如果要对外宣称 level 4 native enforcement，则需要补齐 Windows 和 Linux 上基于证据的 Rust 沙箱验证

apps/gateway/src/plugins/auth.ts

@@ -9,7 +9,10 @@ import type { ApiKeyService } from "../auth/api-key-service.js";
 function isPublicRoute(url: string): boolean {
   const path = url.split("?")[0] ?? url;
   return (
-    path === "/health" || path === "/metrics" || path.startsWith("/webhooks/")
+    path === "/health" ||
+    path === "/metrics" ||
+    path === "/api/runtime/settings" ||
+    path.startsWith("/webhooks/")
   );
 }
 

apps/gateway/src/routes/runtime-settings.ts

@@ -0,0 +1,32 @@
+import { ConsoleLocaleSchema } from "@senclaw/config";
+import type { FastifyInstance } from "fastify";
+import type { RuntimeSettingsStore } from "../runtime-settings.js";
+
+export async function runtimeSettingsRoutes(
+  app: FastifyInstance,
+  opts: { store: RuntimeSettingsStore },
+): Promise<void> {
+  const { store } = opts;
+
+  app.get("/", async () => {
+    return store.get();
+  });
+
+  app.put("/", async (request, reply) => {
+    const body = request.body as Record<string, unknown> | undefined;
+    const parsed = ConsoleLocaleSchema.safeParse(body?.locale);
+    if (!parsed.success) {
+      reply.status(400).send({
+        error: "VALIDATION_ERROR",
+        message: "Invalid runtime settings",
+        details: parsed.error.issues.map((issue) => ({
+          path: issue.path.join("."),
+          message: issue.message,
+        })),
+      });
+      return;
+    }
+
+    return store.update({ locale: parsed.data });
+  });
+}

apps/gateway/src/runtime-settings.ts

@@ -0,0 +1,23 @@
+import {
+  readRuntimeSettings,
+  type RuntimeSettings,
+  writeRuntimeSettings,
+} from "@senclaw/config";
+
+export interface RuntimeSettingsStore {
+  get(): RuntimeSettings;
+  update(next: Partial<RuntimeSettings>): RuntimeSettings;
+}
+
+export function createRuntimeSettingsStore(
+  settingsFile: string,
+): RuntimeSettingsStore {
+  return {
+    get() {
+      return readRuntimeSettings(settingsFile);
+    },
+    update(next) {
+      return writeRuntimeSettings(settingsFile, next);
+    },
+  };
+}

apps/gateway/src/server.ts

@@ -4,7 +4,7 @@ import {
   InMemoryMessageRepository,
   InMemoryRunRepository,
 } from "@senclaw/agent-runner";
-import { loadConfig } from "@senclaw/config";
+import { loadConfig, resolveLocalRuntimeFiles } from "@senclaw/config";
 import {
   createChildLogger,
   createLogger,
@@ -45,12 +45,14 @@ import { healthRoutes } from "./routes/health.js";
 import { jobRoutes } from "./routes/jobs.js";
 import { keyRoutes } from "./routes/keys.js";
 import { runRoutes } from "./routes/runs.js";
+import { runtimeSettingsRoutes } from "./routes/runtime-settings.js";
 import { taskRoutes } from "./routes/tasks.js";
 import { webhookRoutes } from "./routes/webhooks.js";
 import {
   InMemoryExecutionRepository,
   InMemoryJobRepository,
 } from "./scheduler-repositories.js";
+import { createRuntimeSettingsStore } from "./runtime-settings.js";
 
 function resolveMetricPath(request: import("fastify").FastifyRequest): string {
   const routePath =
@@ -100,6 +102,7 @@ export interface CreateServerOptions {
   loggerDestination?: DestinationStream;
   queueDriver?: QueueDriverLike;
   pollingFetcher?: PollingFetcherLike;
+  runtimeSettingsPath?: string;
 }
 
 const HIGH_VOLUME_PATHS = new Set(["/health", "/metrics"]);
@@ -223,6 +226,10 @@ export async function createServer(options: CreateServerOptions = {}): Promise<{
   const app = Fastify({
     logger: false,
   });
+  const runtimeSettingsStore = createRuntimeSettingsStore(
+    options.runtimeSettingsPath ??
+      resolveLocalRuntimeFiles(process.cwd()).settingsFile,
+  );
 
   const requestSpans = new WeakMap<
     import("fastify").FastifyRequest,
@@ -580,6 +587,11 @@ export async function createServer(options: CreateServerOptions = {}): Promise<{
     webhookConnector,
   });
 
+  await app.register(runtimeSettingsRoutes, {
+    prefix: "/api/runtime/settings",
+    store: runtimeSettingsStore,
+  });
+
   await app.register(keyRoutes, {
     prefix: "/api/v1/keys",
     apiKeyService,

apps/gateway/tests/runtime-settings.test.ts

@@ -0,0 +1,64 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import type { FastifyInstance } from "fastify";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createServer } from "../src/server.js";
+
+describe("Gateway runtime settings", () => {
+  let app: FastifyInstance;
+  let runtimeSettingsPath: string;
+
+  beforeAll(async () => {
+    const tempDir = mkdtempSync(join(tmpdir(), "senclaw-runtime-settings-"));
+    runtimeSettingsPath = join(tempDir, "runtime-settings.json");
+
+    const server = await createServer({
+      runtimeSettingsPath,
+    });
+    app = server.app;
+    await app.ready();
+  });
+
+  afterAll(async () => {
+    await app.close();
+    rmSync(dirname(runtimeSettingsPath), { recursive: true, force: true });
+  });
+
+  it("returns the default locale when no runtime settings file exists", async () => {
+    const response = await app.inject({
+      method: "GET",
+      url: "/api/runtime/settings",
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({
+      locale: "en",
+    });
+  });
+
+  it("persists the selected locale for later startup scripts", async () => {
+    const putResponse = await app.inject({
+      method: "PUT",
+      url: "/api/runtime/settings",
+      payload: {
+        locale: "zh-CN",
+      },
+    });
+
+    expect(putResponse.statusCode).toBe(200);
+    expect(putResponse.json()).toEqual({
+      locale: "zh-CN",
+    });
+
+    const getResponse = await app.inject({
+      method: "GET",
+      url: "/api/runtime/settings",
+    });
+
+    expect(getResponse.statusCode).toBe(200);
+    expect(getResponse.json()).toEqual({
+      locale: "zh-CN",
+    });
+  });
+});

apps/web/src/App.tsx

@@ -1,5 +1,6 @@
 import { Routes, Route } from "react-router-dom";
 import { AppLayout } from "./components/AppLayout";
+import { LocaleProvider } from "./components/LocaleProvider";
 import { AgentsList } from "./pages/AgentsList";
 import { AgentDetail } from "./pages/AgentDetail";
 import { AgentCreate } from "./pages/AgentCreate";
@@ -10,17 +11,19 @@ import { HealthDashboard } from "./pages/HealthDashboard";
 
 export default function App() {
   return (
-    <AppLayout>
-      <Routes>
-        <Route path="/" element={<AgentsList />} />
-        <Route path="/agents" element={<AgentsList />} />
-        <Route path="/agents/new" element={<AgentCreate />} />
-        <Route path="/agents/:id" element={<AgentDetail />} />
-        <Route path="/runs" element={<RunsList />} />
-        <Route path="/runs/:id" element={<RunDetail />} />
-        <Route path="/tasks/new" element={<TaskSubmit />} />
-        <Route path="/health" element={<HealthDashboard />} />
-      </Routes>
-    </AppLayout>
+    <LocaleProvider>
+      <AppLayout>
+        <Routes>
+          <Route path="/" element={<AgentsList />} />
+          <Route path="/agents" element={<AgentsList />} />
+          <Route path="/agents/new" element={<AgentCreate />} />
+          <Route path="/agents/:id" element={<AgentDetail />} />
+          <Route path="/runs" element={<RunsList />} />
+          <Route path="/runs/:id" element={<RunDetail />} />
+          <Route path="/tasks/new" element={<TaskSubmit />} />
+          <Route path="/health" element={<HealthDashboard />} />
+        </Routes>
+      </AppLayout>
+    </LocaleProvider>
   );
 }