admin/openclaw-control-center
1
0
Fork 0
mirror of https://github.com/TianyiDataScience/openclaw-control-center.git synced 2026-08-14 08:52:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Default README to Chinese and tighten hero crops

Browse Source
This commit is contained in:
OpenClaw Local
2026-03-11 13:53:56 +01:00
parent a06a40576d
commit b88893bf21
7 changed files with 745 additions and 706 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -21,6 +21,7 @@ mission.worklist.json
docs/mission.runbook.md
docs/mission.sop.md
init.sh
docs/assets/*-tight.png
1440m
180m
720m
README.en.md
+485
View File
@@ -0,0 +1,485 @@
# OpenClaw Control Center
<img src="docs/assets/overview-hero-en.png" alt="OpenClaw Control Center overview hero screenshot" width="1200" />
Safety-first local control center for OpenClaw.
Language: **English** | [中文](README.md)
## Why this exists
- One local place to see whether OpenClaw is healthy, busy, blocked, or drifting.
- Built for non-technical operators who need observability and certainty, not raw backend payloads.
- Safe first-run defaults:
- read-only by default
- local token auth by default
- mutation routes disabled by default
## What you get
- `Overview`: health, current state, decisions waiting, and operator-facing summaries
- `Usage`: usage, spend, subscription windows, and connector status
- `Staff`: who is really working now versus only queued
- `Tasks`: current work, approvals, execution chains, and runtime evidence
- `Documents` and `Memory`: source-backed workbenches scoped to active OpenClaw agents
## Who it is for
- OpenClaw users who want one local control center for observability, usage, tasks, approvals, replay, documents, and memory
- teams running OpenClaw on one machine or a reachable local environment
- maintainers who want a public-ready, safety-first OpenClaw dashboard instead of a generic agent platform
## Screenshots
Example UI from a local OpenClaw environment:
<img src="docs/assets/usage-en.png" alt="OpenClaw Control Center usage screenshot" width="900" />
## 5-minute start
```bash
npm install
cp .env.example .env
npm run build
npm test
npm run smoke:ui
UI_MODE=true npm run dev
```
Then open:
- `http://127.0.0.1:4310/?section=overview&lang=en`
- `http://127.0.0.1:4310/?section=overview&lang=zh`
## Section-by-section tour
### Overview
- The main operating screen for non-technical users.
- Shows the current control posture, key action items, runtime issues, stalled runs, budget risk, who is active, and what needs attention first.
- Best when you want one fast answer to: “Is OpenClaw okay right now?”
### Usage
- Shows today, 7-day, and 30-day usage and spend trends.
- Includes subscription windows, quota consumption, usage mix, and connector status.
- Best when you want to know whether spend or quota is becoming risky.
### Staff
- Shows who is truly active now versus who only has queued work.
- Separates live work from “next up” so backlog is not confused with active execution.
- Best when you want to know who is busy, idle, blocked, or waiting.
### Memory
- A source-backed workbench for daily and long-term memory files.
- Scoped to active OpenClaw agents from `openclaw.json`, so deleted agents do not keep showing up.
- Best when you want to inspect or edit memory that the current OpenClaw team is actually using.
### Documents
- A source-backed workbench for shared and agent-specific core markdown docs.
- Reads the real source files and writes back to the same files.
- Best when you want to maintain the actual working documents behind the system.
### Tasks
- Combines task board, schedule, approvals, execution chains, and runtime evidence.
- Helps distinguish mapped work from real execution evidence, and shows what is blocked or needs review.
- Best when you want to understand what is being carried, what is only planned, and what needs intervention.
### Settings
- Shows safety mode, connector status, and data-link expectations.
- Makes it clear what is connected, what is still partial, and which high-risk actions are intentionally disabled.
- Best when you want to verify environment setup or explain why a signal is missing.
For:
- Existing OpenClaw users who want a local control center for observability, usage, staff activity, tasks, approvals, replay, and documents.
- Teams running OpenClaw on the same machine or a reachable local environment.
- Not a generic dashboard for non-OpenClaw agent stacks.
## Core constraints
- Only touches files in `control-center/`.
- `READONLY_MODE=true` by default.
- `LOCAL_TOKEN_AUTH_REQUIRED=true` by default.
- `IMPORT_MUTATION_ENABLED=false` by default.
- `IMPORT_MUTATION_DRY_RUN=false` by default.
- Import/export and all state-changing endpoints require a local token when auth is enabled.
- Approval actions are hard-gated (`APPROVAL_ACTIONS_ENABLED=false` default).
- Approval actions are dry-run by default (`APPROVAL_ACTIONS_DRY_RUN=true`).
- No mutation of `~/.openclaw/openclaw.json`.
## Quick start
1. `npm install`
2. `cp .env.example .env`
3. Keep safe defaults for the first run; only change `GATEWAY_URL` or path overrides if your OpenClaw setup is non-standard.
4. `npm run build`
5. `npm test`
6. `npm run smoke:ui`
7. `UI_MODE=true npm run dev`
## Installation and onboarding
### 1. Before you start
You should already have:
- a working OpenClaw installation
- a reachable OpenClaw Gateway
- shell access with `node` and `npm`
- read access to your OpenClaw home directory
For the richest dashboard data, it also helps if this machine has:
- `~/.openclaw`
- `~/.codex`
- a readable OpenClaw subscription snapshot, if your setup stores one outside the default locations
### 2. Install the project
```bash
git clone <your-repo-url>
cd control-center
npm install
cp .env.example .env
```
### 3. Configure `.env`
For a safe first run, keep the mutation guards in place.
Use this baseline:
```dotenv
GATEWAY_URL=ws://127.0.0.1:18789
READONLY_MODE=true
APPROVAL_ACTIONS_ENABLED=false
APPROVAL_ACTIONS_DRY_RUN=true
IMPORT_MUTATION_ENABLED=false
IMPORT_MUTATION_DRY_RUN=false
LOCAL_TOKEN_AUTH_REQUIRED=true
UI_MODE=false
UI_PORT=4310
# Optional only when your paths differ from the defaults:
# OPENCLAW_HOME=/path/to/.openclaw
# CODEX_HOME=/path/to/.codex
# OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH=/path/to/subscription.json
```
Change only these values if your environment needs it:
- `GATEWAY_URL`: when your OpenClaw Gateway is not on the default local socket
- `OPENCLAW_HOME`: when OpenClaw is not stored in `~/.openclaw`
- `CODEX_HOME`: when Codex data is not stored in `~/.codex`
- `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`: when your billing/subscription snapshot lives somewhere custom
- `UI_PORT`: when `4310` is already in use
### 4. Optional: ask your own OpenClaw to prepare the setup
If you want OpenClaw to help configure the environment, give it this prompt:
```text
You are helping me connect OpenClaw Control Center to this machine's OpenClaw installation.
Work only inside the control-center repository.
Do not modify application source code unless I explicitly ask.
Goal: prepare a safe first-run setup.
Please do the following:
1. Check whether the OpenClaw Gateway is reachable and tell me the correct gateway URL.
2. Confirm the correct OpenClaw home path and Codex home path on this machine.
3. Compare those paths with .env.example and create or update .env.
4. Keep these values safe for first run:
- READONLY_MODE=true
- LOCAL_TOKEN_AUTH_REQUIRED=true
- APPROVAL_ACTIONS_ENABLED=false
- IMPORT_MUTATION_ENABLED=false
5. Do not enable live import or approval mutations.
6. Do not change OpenClaw's own config.
7. At the end, print:
- the final env values you changed
- the exact commands I should run next
- the first dashboard pages I should open to confirm everything works
8. If any required path, process, or file is missing, stop and tell me exactly what is missing instead of guessing.
```
### 5. Verify the install
Run:
```bash
npm run build
npm test
npm run smoke:ui
```
Expected result:
- build passes
- tests pass
- UI smoke reports a local URL such as `http://127.0.0.1:<port>`
### 6. Start the UI
```bash
UI_MODE=true npm run dev
```
Then open:
- English UI: `http://127.0.0.1:4310/?section=overview&lang=en`
- Chinese UI: `http://127.0.0.1:4310/?section=overview&lang=zh`
If you changed `UI_PORT`, replace `4310` with your chosen port.
### 7. First-use checklist
On your first launch, check these pages in order:
1. `Overview`: the app opens and shows current system state.
2. `Usage`: usage and subscription panels either show real numbers or a clear missing-connector state.
3. `Staff`: live work status matches real active sessions.
4. `Tasks`: current work, approvals, and execution-chain cards load without raw payload noise.
5. `Documents` and `Memory`: the visible agent tabs match your active agents from `openclaw.json`.
### 8. If something looks wrong
- Empty live activity usually means `GATEWAY_URL` is wrong or the OpenClaw Gateway is not running.
- Missing `Documents / Memory` agents usually means `OPENCLAW_HOME` points to the wrong OpenClaw root or `openclaw.json` is missing.
- Missing usage/subscription data usually means `CODEX_HOME` or `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH` needs to be set.
- If you only want a safe read-only dashboard, do not change the mutation defaults.
## Local commands
- `npm run build`
- `npm run dev`
- `npm run dev:continuous`
- `npm run dev:ui`
- `npm run smoke:ui`
- `npm run command:backup-export`
- `npm run command:import-validate -- runtime/exports/<file>.json`
- `npm run command:acks-prune`
- `npm test`
- `npm run validate`
For protected command modes (`command:backup-export`, `command:import-validate`, `command:acks-prune`), set `LOCAL_API_TOKEN=<token>` unless `LOCAL_TOKEN_AUTH_REQUIRED=false`.
## Repository hygiene (Phase 113, Open-source release readiness)
- Repo now ships with `.gitignore`, `LICENSE`, and publishable package metadata.
- Gateway connectivity is configurable via `GATEWAY_URL` instead of being hard-wired to one local socket.
- PM2, mission harness, workflow, and verifier examples now use repo-relative paths and environment-injected secrets only.
- Public docs now refer to generic `~/.openclaw/...` locations instead of machine-specific home directories.
- Run `npm run release:audit` before every public push.
- See [`docs/PUBLISHING.md`](docs/PUBLISHING.md) for the recommended standalone-repo release flow.
## Local HTTP endpoints
- `GET /snapshot`: raw snapshot JSON
- `GET /projects`: list projects with optional query filters `status`, `owner`
- `GET /api/projects`: same as `/projects` for compatibility
- `POST /api/projects`: create project (`projectId`, `title`, optional `status`, `owner`)
- `PATCH /api/projects/:projectId`: update project title/status/owner
- `GET /tasks`: flattened task list with optional query filters `status`, `owner`, `project`
- `GET /api/tasks`: same as `/tasks` for compatibility
- `POST /api/tasks`: create task with schema validation
- `PATCH /api/tasks/:taskId/status`: update task status with schema validation
- `GET /sessions`: paginated session visibility list with optional filters `state`, `agentId`, `q`, and pagination params `page`, `pageSize`, `historyLimit`
- `GET /sessions/:id`: per-session JSON detail with latest history entries (`historyLimit` query supported)
- `GET /api/sessions/:id`: explicit API alias for per-session JSON detail
- `GET /session/:id`: localized session drill-down UI page (`lang=en|zh`) with latest messages, execution-chain evidence, and safe truncation
- `GET /api/sessions`: compatibility endpoint for `/sessions`
- `GET /api/commander/exceptions`: exceptions-only summary (blocked/errors/pending approvals/over-budget/tasks-due)
- `GET /exceptions`: routed exceptions feed with levels (`info`, `warn`, `action-required`), sorted by severity then newest event
- `GET /done-checklist`: final integration checklist + readiness scoring (`observability/governance/collaboration/security`)
- `GET /api/done-checklist`: API alias for done checklist
- `GET /api/action-queue`: notification center queue derived from exceptions feed + ack state + relevant session/task/project links
- `GET /api/action-queue/acks/prune-preview`: token-gated dry-run preview of stale ack prune counts (`before/removed/after`, no state mutation)
- `POST /api/action-queue/:itemId/ack`: acknowledge an action-required queue item (persisted), optional `ttlMinutes` or `snoozeUntil` to auto-expire ack state
- `GET /graph`: project-task-session linkage graph JSON (for future Gameboy view)
- `GET /view/pixel-state.json`: pixel-ready adapter state (`rooms`, `entities`, `links`) for future Gameboy canvas
- `GET /usage-cost`: product route alias that redirects to `/?section=usage-cost`
- `GET /api/usage-cost`: usage/billing observability snapshot (period totals, context windows, breakdowns, burn-rate, subscription consumed/remaining/cycle, connector TODOs)
- `GET /export/state.json`: bundled export with sessions/tasks/projects/budgets/exceptions + persisted debug snapshot + backup bundle in `runtime/exports/` (requires local token auth)
- `POST /api/import/dry-run`: dry-run validator for export bundles (`fileName` or inline `bundle`) with zero state mutation (requires local token auth)
- `POST /api/import/live`: optional live import mutation endpoint (high-risk, local-only); requires local token + `IMPORT_MUTATION_ENABLED=true`, blocked in readonly unless `dryRun=true`, and now returns validation errors instead of `500` for bad `fileName` paths
- `GET /notifications/preview`: notification policy preview with quiet-hours + severity routing
- `GET /cron`: cron overview with next run and health summary
- `GET /healthz`: system health payload (build info + snapshot freshness + monitor lag)
- `GET /digest/latest`: rendered HTML page from latest markdown digest file
- `GET /api/ui/preferences`: persisted dashboard UI preferences (`runtime/ui-preferences.json`)
- `PATCH /api/ui/preferences`: update dashboard UI preferences (`compactStatusStrip`, `quickFilter`, `taskFilters`)
- `GET /api/search/tasks`: safe substring search over tasks (`q`, `limit`), with `count` = total matches and `returned` = current response size
- `GET /api/search/projects`: safe substring search over projects (`q`, `limit`), with `count` = total matches and `returned` = current response size
- `GET /api/search/sessions`: safe substring search over sessions (`q`, `limit`), with `count` = total matches, `returned` = current response size, and live-session merge parity with `/sessions`
- `GET /api/search/exceptions`: safe substring search over exception feed (`q`, `limit`), with `count` = total matches and `returned` = current response size
- `GET /api/replay/index`: replay/debug index from timeline + digests + export snapshots + export bundles, optional `from`/`to` ISO time window filters, plus per-source `stats` (`total`, `returned`, `filteredOut`, window-vs-limit breakdown, `latencyMs`, `latencyBucketsMs` with `p50/p95`, `totalSizeBytes`, `returnedSizeBytes`)
- `GET /api/docs`: route + schema summary endpoint
- `GET /docs`: localized docs index page (read-only) with direct return path to the `Documents` section
- `GET /docs/readme|runbook|architecture|progress`: local markdown docs views (read-only, `lang` accepted for index/back-link flow)
- `POST /api/approvals/:approvalId/approve`: approval action service (gate + dry-run + audit)
- `POST /api/approvals/:approvalId/reject`: rejection action service (gate + dry-run + audit)
- `GET /audit`: local audit timeline page (newest-first, severity filter)
- `GET /api/audit`: audit timeline JSON (`severity=all|info|warn|action-required|error`)
## Dashboard highlights (Phase 14)
- Home page includes inline scoped search UI wired to `/api/search/*`.
- Home page replay/export visibility card now shows returned/filtered counts and latency/size indicators from `/api/replay/index`.
- Guard table shows explicit disabled/enabled badges and linked local docs references.
## Dashboard highlights (Phase 107, Approvals/replay/tool-activity correctness sweep)
- Approval counts now use the full live approval set:
- sidebar and task-hub decision counts no longer under-report when approval previews are truncated
- approval preview lists stay short but now make it explicit when only the latest subset is shown
- Replay visibility chips now show total available history:
- timeline events
- daily digests
- export snapshots
- backup bundles
- Overview tool activity detail now loads actual session evidence:
- it no longer claims there are no tool-call sessions while the same page shows active tool-call counts
- User-facing parity routes no longer advertise deprecated dashboard sections:
- approvals route points to the task hub decision lane
- replay route points to `/audit`
## Dashboard highlights (Phase 110, Docs/memory active-agent scope alignment)
- `Documents` and `Memory` now follow active OpenClaw agent config instead of stale workspace folders:
- facets are resolved from `~/.openclaw/openclaw.json` first
- removed agents no longer appear just because an old folder still exists under `workspace/agents/`
- root OpenClaw files are now shown as `Main` instead of `共享`
- Editable file content remains source-of-truth current:
- file lists still read live filesystem metadata (`updatedAt`, size, path)
- opening a file reads the current source file
- saving a file writes directly back to that same source file
## Dashboard highlights (Phase 111, Execution-chain readability cleanup)
- `Execution chain` cards no longer surface raw JSON payloads as the visible headline or summary.
- Unmapped isolated-run cards now use stable labels such as `Main · Cron 隔离执行`.
- JSON-like payloads are summarized into short readable lines:
- `成功 · 查询 30 · 成功 30`
- `失败 · 错误 locked`
- `成功 · 扫描 120 · 入选 2 · 发送 2`
- Long titles and session keys now wrap/clamp inside the card instead of pushing badges out of place.
## Dashboard highlights (Phase 112, Staff status freshness semantics)
- Staff `Working / 工作中` now means live execution, not just “still owns unfinished tasks”.
- Agents with backlog but no live session now stay in standby semantics instead of looking falsely active.
- Staff work labels now separate:
- live work: `Working on / 正在处理什么`
- queued next task: `Next up / 下一项`
- Staff/recent-activity cache remains short-lived at about `3s`; live-session polling baseline remains `5s`.
## Dashboard highlights (Phase 114, Execution-chain card hardening)
- Execution-chain cards no longer allow raw JSON-like payloads to become visible titles.
- Structured payload-shaped titles are converted into short human summaries or stable fallback labels instead.
- Long titles, meta rows, and badge rails are now overflow-safe inside the card grid.
## Dashboard highlights (Phase 115, Apple-native card elevation tune)
- Page canvas is slightly cooler and quieter so foreground cards stand out more cleanly.
- Core cards now use brighter layered fills, crisper borders, and deeper but still restrained elevation.
- The hierarchy is unchanged; this is a visual polish pass, not a layout rewrite.
## Dashboard highlights (Phase 116, Config-truthful document and memory scopes)
- `Documents / Memory` no longer revive deleted agents just because stale folders still remain on disk.
- Valid active-agent config remains the only truth source for those facet buttons.
- If config becomes unreadable, the workbench now falls back conservatively to `Main` only instead of showing stale agent folders.
## Dashboard highlights (Phase 106, Cold-path cache coalescing)
- Correctness stays unified across Overview / Settings / Usage:
- no return to split summary/full quota logic
- repeat navigations keep the same usage/quota truth when the underlying execution state is unchanged
- Heavy evidence scans are now reused instead of recomputed per page:
- runtime usage logs
- Codex subscription/quota telemetry
- digest history
- OpenClaw cron name catalog
- UI startup now primes dashboard caches, and concurrent page opens share the same heavy build work.
- In local smoke:
- back-to-back `Overview` renders dropped to about `0.41s`
- back-to-back `Usage` renders dropped to about `0.41s`
- after one priming hit, concurrent `Overview / Settings / Usage` completed in about `1.13s`
## Dashboard highlights (Phase 105, Observability correctness alignment)
- Overview / Tasks / Settings / Usage now share one usage/quota truth source:
- the same today-usage number
- the same Codex quota windows
- the same subscription-status judgement
- Active-session counts are aligned across:
- overview KPI
- certainty card
- sidebar / summary strips
- Task certainty no longer depends on only the first recent-session page:
- linked session evidence is loaded for the visible task set
- task detail pages no longer stop at the first 6 linked sessions
- Detail links now keep the current UI language when opening task / cron drill-down pages.
## Dashboard highlights (Phase 15, UX v2)
- Home dashboard is now organized into six operator tabs with persistent left navigation:
- `Overview`
- `Office Space`
- `Projects/Tasks`
- `Alerts`
- `Replay/Audit`
- `Settings`
- UI moved to a colorful pixel-arcade visual style with dual sidebars (navigation + context rail).
- New `Office Space` view shows who is busy on what, grouped by office zones.
- Agent cards now include automatic animal identities derived from agent name semantics, with deterministic fallback mapping.
- Empty/zero-heavy blocks are softened:
- non-actionable zero states are minimized
- user-facing empty states now say `Not activated yet`.
- Home copy was rewritten from debug-heavy wording to operator-focused language while preserving all existing routes and backend behavior.
## Dashboard highlights (Phase 22, Usage/Cost parity surfaces)
- Added `Usage & Cost` section in the primary sidebar IA.
- Added Overview card-level usage/cost pulse:
- period totals (`today`, `7d`, `30d`)
- request-count source state
- burn-rate headline
- Added dedicated Usage & Cost dashboard section:
- context window visibility per active session/agent (absolute tokens + % when context catalog is available)
- pace/trend labels + warning thresholds
- usage/cost breakdown by agent, project, model, provider
- budget burn-rate status and alert messaging
- Added graceful unavailable-state behavior:
- explicit `Data source not connected` labels for disconnected metrics (instead of fake zeros)
- connector TODO list surfaced in Settings
- Added usage adapter endpoint:
- `GET /api/usage-cost`
## Dashboard highlights (Phase 25, Mission Control v3)
- UI visual reset to polished pixel-office style:
- design-token based palette/spacing/radius/shadow system
- layered office background grid + glow depth
- responsive desktop/mobile hierarchy with subtle card/status motion
- Navigation and copy reset for operator clarity:
- `Command Deck`, `Usage & Billing`, `Pixel Office`, `Work Board`, `Decisions`, `Timeline`, `Control Room`
- reduced technical wording on primary surfaces
- advanced links preserved under explicit disclosure
- Mac parity surfaces panel added with status + route entry for:
- conversations, approvals/decision queue, cron, projects/tasks, usage/cost, replay/audit, health/digest, export/import dry-run safety, pixel adapter
- Full roster office model:
- best-effort OpenClaw roster read from `~/.openclaw/openclaw.json` via `src/runtime/agent-roster.ts`
- office floor now renders desk/zone occupancy and includes known agents beyond active sessions
- Subscription usage/remaining best-effort integration:
- adapter support in `src/runtime/usage-cost.ts` for connected/partial/not_connected states
- UI now shows consumed/remaining/limit/cycle/source and explicit connection targets when unavailable
## Dashboard highlights (Phase 68, Plain-language certainty)
- Added `Information certainty` card to Overview and Settings:
- tells non-technical operators which parts of the picture are trustworthy now
- calls out remaining blind spots in plain language
- Added `Execution certainty` board to Tasks:
- scores whether each in-flight task is backed by real execution evidence
- separates `evidence is strong` from `needs follow-up` and `evidence is weak`
- Task detail pages now act as evidence pages:
- certainty judgement
- linked session evidence and recent activity summaries
## API validation/error envelope
- API mutating routes require `Content-Type: application/json`.
- Import/export and mutating routes require local token auth by default:
- header: `x-local-token: <LOCAL_API_TOKEN>`
- or `Authorization: Bearer <LOCAL_API_TOKEN>`
- Strict API query validation rejects unknown query keys.
- JSON errors use a consistent envelope:
- `{"ok":false,"requestId":"...","error":{"code":"...","status":<http>,"message":"...","issues":[],"requestId":"..."}}`
- JSON responses include `requestId` and all responses include `x-request-id` header for correlation.
## Live import warning
- `POST /api/import/live` is intentionally disabled by default.
- Do not enable it unless you are doing a controlled local restore test.
- Live mode mutates local runtime stores (`runtime/projects.json`, `runtime/tasks.json`, `runtime/budgets.json`).
- Keep `READONLY_MODE=true` and `IMPORT_MUTATION_ENABLED=false` in normal operation.
## Runtime files
- `runtime/last-snapshot.json`
- `runtime/timeline.log`
- `runtime/projects.json`
- `runtime/tasks.json`
- `runtime/budgets.json`
- `runtime/notification-policy.json`
- `runtime/model-context-catalog.json`
- `runtime/ui-preferences.json`
- `runtime/acks.json`
- `runtime/approval-actions.log`
- `runtime/operation-audit.log`
- `runtime/digests/YYYY-MM-DD.json`
- `runtime/digests/YYYY-MM-DD.md`
- `runtime/export-snapshots/*.json`
- `runtime/exports/*.json`
## Docs
- `docs/ARCHITECTURE.md`
- `docs/RUNBOOK.md`
- `docs/PROGRESS.md`
README.md
+221 -357
View File
@@ -1,37 +1,37 @@
# OpenClaw Control Center
<img src="docs/assets/overview-hero-en.png" alt="OpenClaw Control Center overview hero screenshot" width="1200" />
<img src="docs/assets/overview-hero-zh.png" alt="OpenClaw Control Center 总览横幅截图" width="1200" />
Safety-first local control center for OpenClaw.
OpenClaw 的安全优先、本地优先控制中心。
Language: **English** | [中文](README.zh-CN.md)
语言： [English](README.en.md) | **中文**
## Why this exists
- One local place to see whether OpenClaw is healthy, busy, blocked, or drifting.
- Built for non-technical operators who need observability and certainty, not raw backend payloads.
- Safe first-run defaults:
- read-only by default
- local token auth by default
- mutation routes disabled by default
## 这个项目是做什么的
- 给 OpenClaw 提供一个本地控制中心，集中看系统是否稳定、谁在工作、哪些任务卡住了、今天花了多少。
- 面向非技术用户，重点是“看得懂、看得准”，不是暴露原始后端 payload。
- 首次接入默认安全：
- 默认只读
- 默认本地 token 鉴权
- 默认关闭高风险写操作
## What you get
- `Overview`: health, current state, decisions waiting, and operator-facing summaries
- `Usage`: usage, spend, subscription windows, and connector status
- `Staff`: who is really working now versus only queued
- `Tasks`: current work, approvals, execution chains, and runtime evidence
- `Documents` and `Memory`: source-backed workbenches scoped to active OpenClaw agents
## 你能得到什么
- `总览`：系统状态、待处理事项、关键风险和运营摘要
- `用量`：用量、花费、订阅窗口和连接状态
- `员工`：谁真的在工作，谁只是排队待命
- `任务`：当前任务、审批、执行链和运行证据
- `文档` 与 `记忆`：按活跃 OpenClaw agent 范围展示的源文件工作台
## Who it is for
- OpenClaw users who want one local control center for observability, usage, tasks, approvals, replay, documents, and memory
- teams running OpenClaw on one machine or a reachable local environment
- maintainers who want a public-ready, safety-first OpenClaw dashboard instead of a generic agent platform
## 适合谁
- 已经在用 OpenClaw、想要一个统一控制中心的团队或个人
- 在同一台机器或可达本地环境里运行 OpenClaw 的使用者
- 想公开发布一个安全优先的 OpenClaw 控制台，而不是做通用 agent 平台的人
## Screenshots
Example UI from a local OpenClaw environment:
## 截图
以下截图来自一个本地 OpenClaw 环境：
<img src="docs/assets/usage-en.png" alt="OpenClaw Control Center usage screenshot" width="900" />
<img src="docs/assets/usage-en.png" alt="OpenClaw Control Center 用量截图" width="900" />
## 5-minute start
## 5 分钟启动
```bash
npm install
cp .env.example .env
@@ -41,98 +41,84 @@ npm run smoke:ui
UI_MODE=true npm run dev
```
Then open:
- `http://127.0.0.1:4310/?section=overview&lang=en`
然后打开：
- `http://127.0.0.1:4310/?section=overview&lang=zh`
- `http://127.0.0.1:4310/?section=overview&lang=en`
## Section-by-section tour
## 分区功能说明
### Overview
- The main operating screen for non-technical users.
- Shows the current control posture, key action items, runtime issues, stalled runs, budget risk, who is active, and what needs attention first.
- Best when you want one fast answer to: “Is OpenClaw okay right now?”
### 总览
- 给非技术用户看的主操作页。
- 集中展示当前总控态势、待处理事项、运行异常、停滞执行、预算风险、谁在忙、哪些地方需要优先关注。
- 最适合快速回答一句话：`OpenClaw 现在整体正常吗？`
### Usage
- Shows today, 7-day, and 30-day usage and spend trends.
- Includes subscription windows, quota consumption, usage mix, and connector status.
- Best when you want to know whether spend or quota is becoming risky.
### 用量
- 展示今日、7 天、30 天的用量和花费趋势。
- 包含订阅窗口、配额消耗、用量结构和数据连接状态。
- 最适合判断花费或额度是否开始有风险。
### Staff
- Shows who is truly active now versus who only has queued work.
- Separates live work from “next up” so backlog is not confused with active execution.
- Best when you want to know who is busy, idle, blocked, or waiting.
### 员工
- 展示谁现在真的在工作，谁只是有排队中的任务。
- 明确区分“正在执行”和“下一项”，避免把 backlog 误认为正在跑。
- 最适合判断谁忙、谁闲、谁卡住、谁在等待。
### Memory
- A source-backed workbench for daily and long-term memory files.
- Scoped to active OpenClaw agents from `openclaw.json`, so deleted agents do not keep showing up.
- Best when you want to inspect or edit memory that the current OpenClaw team is actually using.
### 记忆
- 一个直接基于源文件的记忆工作台，用来查看和编辑每日记忆与长期记忆。
- 范围跟随 `openclaw.json` 里的活跃 agent，不会把已删除 agent 继续显示出来。
- 最适合查看或维护当前 OpenClaw 团队真实在用的记忆内容。
### Documents
- A source-backed workbench for shared and agent-specific core markdown docs.
- Reads the real source files and writes back to the same files.
- Best when you want to maintain the actual working documents behind the system.
### 文档
- 一个直接基于源文件的文档工作台，用来查看和编辑共享文档与 agent 核心文档。
- 打开的是实际源文件，保存后也直接写回同一个源文件。
- 最适合维护系统背后真正生效的工作文档。
### Tasks
- Combines task board, schedule, approvals, execution chains, and runtime evidence.
- Helps distinguish mapped work from real execution evidence, and shows what is blocked or needs review.
- Best when you want to understand what is being carried, what is only planned, and what needs intervention.
### 任务
- 把任务板、排期、审批、执行链和运行证据放在同一个分区里。
- 能帮助区分哪些只是看板映射，哪些已经有真实执行证据，哪些任务卡住了、需要跟进或待审。
- 最适合理解“现在到底在做什么、只是计划了什么、哪些需要你介入”。
### Settings
- Shows safety mode, connector status, and data-link expectations.
- Makes it clear what is connected, what is still partial, and which high-risk actions are intentionally disabled.
- Best when you want to verify environment setup or explain why a signal is missing.
### 设置
- 展示安全模式、连接器状态和数据链路预期。
- 会明确告诉你哪些数据已经接上，哪些还只是部分可见，哪些高风险动作是故意关闭的。
- 最适合排查环境配置、解释为什么某些信号缺失。
For:
- Existing OpenClaw users who want a local control center for observability, usage, staff activity, tasks, approvals, replay, and documents.
- Teams running OpenClaw on the same machine or a reachable local environment.
- Not a generic dashboard for non-OpenClaw agent stacks.
## 核心约束
- 只修改 `control-center/` 目录内的文件
- 默认 `READONLY_MODE=true`
- 默认 `LOCAL_TOKEN_AUTH_REQUIRED=true`
- 默认 `IMPORT_MUTATION_ENABLED=false`
- 默认 `IMPORT_MUTATION_DRY_RUN=false`
- 开启鉴权时，导入/导出和所有改状态接口都需要本地 token
- 审批动作有硬开关，默认关闭：`APPROVAL_ACTIONS_ENABLED=false`
- 审批动作默认 dry-run：`APPROVAL_ACTIONS_DRY_RUN=true`
- 不会改写 `~/.openclaw/openclaw.json`
## Core constraints
- Only touches files in `control-center/`.
- `READONLY_MODE=true` by default.
- `LOCAL_TOKEN_AUTH_REQUIRED=true` by default.
- `IMPORT_MUTATION_ENABLED=false` by default.
- `IMPORT_MUTATION_DRY_RUN=false` by default.
- Import/export and all state-changing endpoints require a local token when auth is enabled.
- Approval actions are hard-gated (`APPROVAL_ACTIONS_ENABLED=false` default).
- Approval actions are dry-run by default (`APPROVAL_ACTIONS_DRY_RUN=true`).
- No mutation of `~/.openclaw/openclaw.json`.
## 安装与上手
## Quick start
1. `npm install`
2. `cp .env.example .env`
3. Keep safe defaults for the first run; only change `GATEWAY_URL` or path overrides if your OpenClaw setup is non-standard.
4. `npm run build`
5. `npm test`
6. `npm run smoke:ui`
7. `UI_MODE=true npm run dev`
### 1. 开始前准备
你最好已经有：
- 一个可用的 OpenClaw 安装
- 一个可连接的 OpenClaw Gateway
- 当前机器上的 `node` 和 `npm`
- 对 OpenClaw 主目录的读取权限
## Installation and onboarding
### 1. Before you start
You should already have:
- a working OpenClaw installation
- a reachable OpenClaw Gateway
- shell access with `node` and `npm`
- read access to your OpenClaw home directory
For the richest dashboard data, it also helps if this machine has:
如果你希望 `用量 / 订阅` 信息更完整，当前机器最好还能读到：
- `~/.openclaw`
- `~/.codex`
- a readable OpenClaw subscription snapshot, if your setup stores one outside the default locations
- OpenClaw 订阅快照文件，尤其是它不在默认位置时
### 2. Install the project
### 2. 安装项目
```bash
git clone <your-repo-url>
git clone <你的仓库地址>
cd control-center
npm install
cp .env.example .env
```
### 3. Configure `.env`
For a safe first run, keep the mutation guards in place.
### 3. 配置 `.env`
第一次接入建议保持安全默认值，不要急着打开写操作。
Use this baseline:
基线配置如下：
```dotenv
GATEWAY_URL=ws://127.0.0.1:18789
READONLY_MODE=true
@@ -144,325 +130,203 @@ LOCAL_TOKEN_AUTH_REQUIRED=true
UI_MODE=false
UI_PORT=4310
# Optional only when your paths differ from the defaults:
# 只有路径不是默认值时才需要设置：
# OPENCLAW_HOME=/path/to/.openclaw
# CODEX_HOME=/path/to/.codex
# OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH=/path/to/subscription.json
```
Change only these values if your environment needs it:
- `GATEWAY_URL`: when your OpenClaw Gateway is not on the default local socket
- `OPENCLAW_HOME`: when OpenClaw is not stored in `~/.openclaw`
- `CODEX_HOME`: when Codex data is not stored in `~/.codex`
- `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`: when your billing/subscription snapshot lives somewhere custom
- `UI_PORT`: when `4310` is already in use
一般只需要在这些情况下修改：
- `GATEWAY_URL`：你的 Gateway 不在默认本地地址
- `OPENCLAW_HOME`：OpenClaw 不在 `~/.openclaw`
- `CODEX_HOME`：Codex 数据不在 `~/.codex`
- `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`：订阅或账单快照文件在自定义位置
- `UI_PORT`：`4310` 已被占用
### 4. Optional: ask your own OpenClaw to prepare the setup
If you want OpenClaw to help configure the environment, give it this prompt:
### 4. 可选：让你自己的 OpenClaw 帮你配置
你可以把下面这段提示词直接交给自己的 OpenClaw：
```text
You are helping me connect OpenClaw Control Center to this machine's OpenClaw installation.
你现在要帮我把 OpenClaw Control Center 接到这台机器自己的 OpenClaw 环境上。
Work only inside the control-center repository.
Do not modify application source code unless I explicitly ask.
Goal: prepare a safe first-run setup.
只允许在 control-center 仓库里工作。
除非我明确要求，否则不要修改应用源码。
目标是完成一次安全的首次接入配置。
Please do the following:
1. Check whether the OpenClaw Gateway is reachable and tell me the correct gateway URL.
2. Confirm the correct OpenClaw home path and Codex home path on this machine.
3. Compare those paths with .env.example and create or update .env.
4. Keep these values safe for first run:
请按下面步骤执行：
1. 检查 OpenClaw Gateway 是否可达，并告诉我正确的 gateway URL。
2. 确认这台机器上正确的 OpenClaw 主目录和 Codex 主目录。
3. 对照 .env.example，创建或更新 .env。
4. 第一次接入时必须保持这些值：
- READONLY_MODE=true
- LOCAL_TOKEN_AUTH_REQUIRED=true
- APPROVAL_ACTIONS_ENABLED=false
- IMPORT_MUTATION_ENABLED=false
5. Do not enable live import or approval mutations.
6. Do not change OpenClaw's own config.
7. At the end, print:
- the final env values you changed
- the exact commands I should run next
- the first dashboard pages I should open to confirm everything works
8. If any required path, process, or file is missing, stop and tell me exactly what is missing instead of guessing.
5. 不要开启 live import，也不要开启 approval mutation。
6. 不要改 OpenClaw 自己的配置文件。
7. 完成后输出：
- 你实际修改了哪些 env 值
- 我下一步应该执行的准确命令
- 我应该先打开哪些页面来确认接入成功
8. 如果缺少必要的路径、进程或文件，不要猜，直接明确告诉我缺什么。
```
### 5. Verify the install
Run:
### 5. 验证安装
执行：
```bash
npm run build
npm test
npm run smoke:ui
```
Expected result:
- build passes
- tests pass
- UI smoke reports a local URL such as `http://127.0.0.1:<port>`
预期结果：
- build 通过
- test 通过
- UI smoke 输出本地地址，例如 `http://127.0.0.1:<port>`
### 6. Start the UI
### 6. 启动界面
```bash
UI_MODE=true npm run dev
```
Then open:
- English UI: `http://127.0.0.1:4310/?section=overview&lang=en`
- Chinese UI: `http://127.0.0.1:4310/?section=overview&lang=zh`
然后打开：
- 中文界面：`http://127.0.0.1:4310/?section=overview&lang=zh`
- 英文界面：`http://127.0.0.1:4310/?section=overview&lang=en`
If you changed `UI_PORT`, replace `4310` with your chosen port.
如果你改了 `UI_PORT`，把 `4310` 替换成你的端口。
### 7. First-use checklist
On your first launch, check these pages in order:
1. `Overview`: the app opens and shows current system state.
2. `Usage`: usage and subscription panels either show real numbers or a clear missing-connector state.
3. `Staff`: live work status matches real active sessions.
4. `Tasks`: current work, approvals, and execution-chain cards load without raw payload noise.
5. `Documents` and `Memory`: the visible agent tabs match your active agents from `openclaw.json`.
### 7. 首次检查顺序
1. `总览`：页面能正常打开，并且能看到当前系统状态
2. `用量`：能看到真实数字，或者明确的“数据源未连接”
3. `员工`：实时工作状态与真实 active session 基本一致
4. `任务`：当前工作、审批、执行链能正常加载，不会吐原始 payload
5. `文档` 与 `记忆`：显示的 agent 标签和 `openclaw.json` 中的活跃 agent 一致
### 8. If something looks wrong
- Empty live activity usually means `GATEWAY_URL` is wrong or the OpenClaw Gateway is not running.
- Missing `Documents / Memory` agents usually means `OPENCLAW_HOME` points to the wrong OpenClaw root or `openclaw.json` is missing.
- Missing usage/subscription data usually means `CODEX_HOME` or `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH` needs to be set.
- If you only want a safe read-only dashboard, do not change the mutation defaults.
### 8. 如果看起来不对
- 实时活动全空，通常是 `GATEWAY_URL` 错了，或者 OpenClaw Gateway 没启动
- `文档 / 记忆` 范围不对，通常是 `OPENCLAW_HOME` 指错了，或者 `openclaw.json` 不可读
- `用量 / 订阅` 没数据，通常是 `CODEX_HOME` 或 `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH` 没配对
- 如果你只是想先安全观察，不要改默认的只读和 mutation 开关
## Local commands
## 本地命令
- `npm run build`
- `npm run dev`
- `npm run dev:continuous`
- `npm run dev:ui`
- `npm run smoke:ui`
- `npm run release:audit`
- `npm run command:backup-export`
- `npm run command:import-validate -- runtime/exports/<file>.json`
- `npm run command:acks-prune`
- `npm test`
- `npm run validate`
For protected command modes (`command:backup-export`, `command:import-validate`, `command:acks-prune`), set `LOCAL_API_TOKEN=<token>` unless `LOCAL_TOKEN_AUTH_REQUIRED=false`.
对于受保护的命令模式（如 `command:backup-export`、`command:import-validate`、`command:acks-prune`），如果 `LOCAL_TOKEN_AUTH_REQUIRED=true`，请先设置 `LOCAL_API_TOKEN=<token>`。
## Repository hygiene (Phase 113, Open-source release readiness)
- Repo now ships with `.gitignore`, `LICENSE`, and publishable package metadata.
- Gateway connectivity is configurable via `GATEWAY_URL` instead of being hard-wired to one local socket.
- PM2, mission harness, workflow, and verifier examples now use repo-relative paths and environment-injected secrets only.
- Public docs now refer to generic `~/.openclaw/...` locations instead of machine-specific home directories.
- Run `npm run release:audit` before every public push.
- See [`docs/PUBLISHING.md`](docs/PUBLISHING.md) for the recommended standalone-repo release flow.
## 开源与发布卫生
- 仓库已经包含 `.gitignore`、`LICENSE` 和可发布的 package 元数据
- Gateway 地址可通过 `GATEWAY_URL` 配置，不再绑定单一本地 socket
- PM2、mission harness、workflow 和 verifier 示例都只用仓库相对路径和环境注入 secrets
- 公开文档统一使用通用 `~/.openclaw/...` 路径，不包含机器私有 home 目录
- 每次公开推送前，建议先运行 `npm run release:audit`
- 独立仓库发布流程见 [docs/PUBLISHING.md](docs/PUBLISHING.md)
## Local HTTP endpoints
- `GET /snapshot`: raw snapshot JSON
- `GET /projects`: list projects with optional query filters `status`, `owner`
- `GET /api/projects`: same as `/projects` for compatibility
- `POST /api/projects`: create project (`projectId`, `title`, optional `status`, `owner`)
- `PATCH /api/projects/:projectId`: update project title/status/owner
- `GET /tasks`: flattened task list with optional query filters `status`, `owner`, `project`
- `GET /api/tasks`: same as `/tasks` for compatibility
- `POST /api/tasks`: create task with schema validation
- `PATCH /api/tasks/:taskId/status`: update task status with schema validation
- `GET /sessions`: paginated session visibility list with optional filters `state`, `agentId`, `q`, and pagination params `page`, `pageSize`, `historyLimit`
- `GET /sessions/:id`: per-session JSON detail with latest history entries (`historyLimit` query supported)
- `GET /api/sessions/:id`: explicit API alias for per-session JSON detail
- `GET /session/:id`: localized session drill-down UI page (`lang=en|zh`) with latest messages, execution-chain evidence, and safe truncation
- `GET /api/sessions`: compatibility endpoint for `/sessions`
- `GET /api/commander/exceptions`: exceptions-only summary (blocked/errors/pending approvals/over-budget/tasks-due)
- `GET /exceptions`: routed exceptions feed with levels (`info`, `warn`, `action-required`), sorted by severity then newest event
- `GET /done-checklist`: final integration checklist + readiness scoring (`observability/governance/collaboration/security`)
- `GET /api/done-checklist`: API alias for done checklist
- `GET /api/action-queue`: notification center queue derived from exceptions feed + ack state + relevant session/task/project links
- `GET /api/action-queue/acks/prune-preview`: token-gated dry-run preview of stale ack prune counts (`before/removed/after`, no state mutation)
- `POST /api/action-queue/:itemId/ack`: acknowledge an action-required queue item (persisted), optional `ttlMinutes` or `snoozeUntil` to auto-expire ack state
- `GET /graph`: project-task-session linkage graph JSON (for future Gameboy view)
- `GET /view/pixel-state.json`: pixel-ready adapter state (`rooms`, `entities`, `links`) for future Gameboy canvas
- `GET /usage-cost`: product route alias that redirects to `/?section=usage-cost`
- `GET /api/usage-cost`: usage/billing observability snapshot (period totals, context windows, breakdowns, burn-rate, subscription consumed/remaining/cycle, connector TODOs)
- `GET /export/state.json`: bundled export with sessions/tasks/projects/budgets/exceptions + persisted debug snapshot + backup bundle in `runtime/exports/` (requires local token auth)
- `POST /api/import/dry-run`: dry-run validator for export bundles (`fileName` or inline `bundle`) with zero state mutation (requires local token auth)
- `POST /api/import/live`: optional live import mutation endpoint (high-risk, local-only); requires local token + `IMPORT_MUTATION_ENABLED=true`, blocked in readonly unless `dryRun=true`, and now returns validation errors instead of `500` for bad `fileName` paths
- `GET /notifications/preview`: notification policy preview with quiet-hours + severity routing
- `GET /cron`: cron overview with next run and health summary
- `GET /healthz`: system health payload (build info + snapshot freshness + monitor lag)
- `GET /digest/latest`: rendered HTML page from latest markdown digest file
- `GET /api/ui/preferences`: persisted dashboard UI preferences (`runtime/ui-preferences.json`)
- `PATCH /api/ui/preferences`: update dashboard UI preferences (`compactStatusStrip`, `quickFilter`, `taskFilters`)
- `GET /api/search/tasks`: safe substring search over tasks (`q`, `limit`), with `count` = total matches and `returned` = current response size
- `GET /api/search/projects`: safe substring search over projects (`q`, `limit`), with `count` = total matches and `returned` = current response size
- `GET /api/search/sessions`: safe substring search over sessions (`q`, `limit`), with `count` = total matches, `returned` = current response size, and live-session merge parity with `/sessions`
- `GET /api/search/exceptions`: safe substring search over exception feed (`q`, `limit`), with `count` = total matches and `returned` = current response size
- `GET /api/replay/index`: replay/debug index from timeline + digests + export snapshots + export bundles, optional `from`/`to` ISO time window filters, plus per-source `stats` (`total`, `returned`, `filteredOut`, window-vs-limit breakdown, `latencyMs`, `latencyBucketsMs` with `p50/p95`, `totalSizeBytes`, `returnedSizeBytes`)
- `GET /api/docs`: route + schema summary endpoint
- `GET /docs`: localized docs index page (read-only) with direct return path to the `Documents` section
- `GET /docs/readme|runbook|architecture|progress`: local markdown docs views (read-only, `lang` accepted for index/back-link flow)
- `POST /api/approvals/:approvalId/approve`: approval action service (gate + dry-run + audit)
- `POST /api/approvals/:approvalId/reject`: rejection action service (gate + dry-run + audit)
- `GET /audit`: local audit timeline page (newest-first, severity filter)
- `GET /api/audit`: audit timeline JSON (`severity=all|info|warn|action-required|error`)
## 本地 HTTP 接口
- `GET /snapshot`：原始快照 JSON
- `GET /projects`：项目列表，支持 `status`、`owner` 等查询过滤
- `GET /api/projects`：`/projects` 的兼容别名
- `POST /api/projects`：创建项目（`projectId`、`title`，可选 `status`、`owner`）
- `PATCH /api/projects/:projectId`：更新项目标题、状态或 owner
- `GET /tasks`：任务列表，支持 `status`、`owner`、`project` 过滤
- `GET /api/tasks`：`/tasks` 的兼容别名
- `POST /api/tasks`：按 schema 校验创建任务
- `PATCH /api/tasks/:taskId/status`：按 schema 校验更新任务状态
- `GET /sessions`：分页会话列表，支持 `state`、`agentId`、`q`、`page`、`pageSize`、`historyLimit`
- `GET /sessions/:id`：单会话 JSON 详情，支持 `historyLimit`
- `GET /api/sessions/:id`：单会话详情的 API 别名
- `GET /session/:id`：本地化会话详情页面，支持 `lang=en|zh`
- `GET /api/commander/exceptions`：仅异常视图的汇总
- `GET /exceptions`：按严重级别排序的异常流
- `GET /done-checklist`：最终集成检查清单与 readiness 评分
- `GET /api/action-queue`：基于异常流和 ack 状态生成的待处理队列
- `GET /graph`：项目-任务-会话关联图 JSON
- `GET /usage-cost`：跳转到 `/?section=usage-cost`
- `GET /api/usage-cost`：用量、花费、订阅窗口、拆分和 burn-rate 快照
- `POST /api/import/dry-run`：导入包 dry-run 校验，不写状态
- `POST /api/import/live`：可选 live import，高风险、本地专用，默认关闭
- `GET /cron`：定时任务与健康状态
- `GET /healthz`：系统健康载荷
- `GET /digest/latest`：最新 digest 的 HTML 页面
- `GET /api/search/tasks|projects|sessions|exceptions`：安全子串搜索接口
- `GET /api/replay/index`：timeline、digest、export、bundle 的 replay/debug 索引
- `GET /docs`：本地化 docs 索引
- `GET /docs/readme|runbook|architecture|progress`：本地 markdown 文档视图
- `POST /api/approvals/:approvalId/approve|reject`：审批动作服务（受 gate 和 dry-run 控制）
- `GET /audit`：本地审计时间线页面
- `GET /api/audit`：审计时间线 JSON
## Dashboard highlights (Phase 14)
- Home page includes inline scoped search UI wired to `/api/search/*`.
- Home page replay/export visibility card now shows returned/filtered counts and latency/size indicators from `/api/replay/index`.
- Guard table shows explicit disabled/enabled badges and linked local docs references.
## 看板亮点
## Dashboard highlights (Phase 107, Approvals/replay/tool-activity correctness sweep)
- Approval counts now use the full live approval set:
- sidebar and task-hub decision counts no longer under-report when approval previews are truncated
- approval preview lists stay short but now make it explicit when only the latest subset is shown
- Replay visibility chips now show total available history:
- timeline events
- daily digests
- export snapshots
- backup bundles
- Overview tool activity detail now loads actual session evidence:
- it no longer claims there are no tool-call sessions while the same page shows active tool-call counts
- User-facing parity routes no longer advertise deprecated dashboard sections:
- approvals route points to the task hub decision lane
- replay route points to `/audit`
### 总览、审批、回放与工具活动
- 首页支持内联搜索，直接接 `/api/search/*`
- 回放和导出卡片会展示返回数量、过滤数量、延迟和体积指标
- 审批数量使用完整 live 审批集，不再因为 preview 截断而少算
- 工具活动详情会加载真实 session 证据，不再出现“上面有统计、下面却说没有工具会话”的冲突
## Dashboard highlights (Phase 110, Docs/memory active-agent scope alignment)
- `Documents` and `Memory` now follow active OpenClaw agent config instead of stale workspace folders:
- facets are resolved from `~/.openclaw/openclaw.json` first
- removed agents no longer appear just because an old folder still exists under `workspace/agents/`
- root OpenClaw files are now shown as `Main` instead of `共享`
- Editable file content remains source-of-truth current:
- file lists still read live filesystem metadata (`updatedAt`, size, path)
- opening a file reads the current source file
- saving a file writes directly back to that same source file
### 文档、记忆与 agent 范围
- `文档` 和 `记忆` 现在优先跟随 `~/.openclaw/openclaw.json` 中的活跃 agent
- 已删除 agent 不会因为旧目录残留而重新出现在 facet 按钮中
- 根级 OpenClaw 文件会显示为 `Main`
- 打开和保存文件时都直接读写源文件，不走陈旧副本
## Dashboard highlights (Phase 111, Execution-chain readability cleanup)
- `Execution chain` cards no longer surface raw JSON payloads as the visible headline or summary.
- Unmapped isolated-run cards now use stable labels such as `Main · Cron 隔离执行`.
- JSON-like payloads are summarized into short readable lines:
- `成功 · 查询 30 · 成功 30`
- `失败 · 错误 locked`
- `成功 · 扫描 120 · 入选 2 · 发送 2`
- Long titles and session keys now wrap/clamp inside the card instead of pushing badges out of place.
### 执行链与任务可读性
- 执行链卡片不再直接显示原始 JSON payload
- 未映射的隔离执行会使用稳定标题，例如 `Main · Cron 隔离执行`
- 长标题、长 session key 和 badge 现在都会在卡片内安全换行
- 任务页会显示真实执行证据，而不是只看截断的最近几条会话
## Dashboard highlights (Phase 112, Staff status freshness semantics)
- Staff `Working / 工作中` now means live execution, not just “still owns unfinished tasks”.
- Agents with backlog but no live session now stay in standby semantics instead of looking falsely active.
- Staff work labels now separate:
- live work: `Working on / 正在处理什么`
- queued next task: `Next up / 下一项`
- Staff/recent-activity cache remains short-lived at about `3s`; live-session polling baseline remains `5s`.
### 员工状态与实时性
- `工作中 / Working` 只代表真实 live execution，不再把“还有 backlog”误判为正在工作
- 有 backlog 但没有 live session 的 agent 会显示为待命语义
- `正在处理什么` 与 `下一项` 被明确区分
## Dashboard highlights (Phase 114, Execution-chain card hardening)
- Execution-chain cards no longer allow raw JSON-like payloads to become visible titles.
- Structured payload-shaped titles are converted into short human summaries or stable fallback labels instead.
- Long titles, meta rows, and badge rails are now overflow-safe inside the card grid.
### 用量、订阅与正确性
- `总览 / 任务 / 设置 / 用量` 共享同一套 usage/quota 真相源
- 活跃会话统计在首页 KPI、侧栏、摘要条中保持一致
- Codex 配额窗口标签会自动归一成稳定标签，例如 `5h` 和 `Week`
- 对缺失数据会显示明确的未连接状态，而不是假零值
## Dashboard highlights (Phase 115, Apple-native card elevation tune)
- Page canvas is slightly cooler and quieter so foreground cards stand out more cleanly.
- Core cards now use brighter layered fills, crisper borders, and deeper but still restrained elevation.
- The hierarchy is unchanged; this is a visual polish pass, not a layout rewrite.
### 视觉与体验
- 整体 UI 已收敛到更接近 Apple 原生的层次和卡片风格
- 执行链卡片改成更宽的栅格，不再四张挤在一行里
- 侧边导航里 `用量` 已放在 `总览` 下方，信息架构更贴近日常运营使用顺序
## Dashboard highlights (Phase 116, Config-truthful document and memory scopes)
- `Documents / Memory` no longer revive deleted agents just because stale folders still remain on disk.
- Valid active-agent config remains the only truth source for those facet buttons.
- If config becomes unreadable, the workbench now falls back conservatively to `Main` only instead of showing stale agent folders.
### Mission Control v3 能力
- UI 已演进到 polished pixel-office 风格
- 覆盖会话、审批、cron、任务、用量、回放、健康、导入导出 dry-run 等关键控制面
- 全 roster office 模型会读取 `openclaw.json` 中已知 agent，而不只看当前活跃会话
- 支持 best-effort 的订阅用量/剩余额度展示
## Dashboard highlights (Phase 106, Cold-path cache coalescing)
- Correctness stays unified across Overview / Settings / Usage:
- no return to split summary/full quota logic
- repeat navigations keep the same usage/quota truth when the underlying execution state is unchanged
- Heavy evidence scans are now reused instead of recomputed per page:
- runtime usage logs
- Codex subscription/quota telemetry
- digest history
- OpenClaw cron name catalog
- UI startup now primes dashboard caches, and concurrent page opens share the same heavy build work.
- In local smoke:
- back-to-back `Overview` renders dropped to about `0.41s`
- back-to-back `Usage` renders dropped to about `0.41s`
- after one priming hit, concurrent `Overview / Settings / Usage` completed in about `1.13s`
## Dashboard highlights (Phase 105, Observability correctness alignment)
- Overview / Tasks / Settings / Usage now share one usage/quota truth source:
- the same today-usage number
- the same Codex quota windows
- the same subscription-status judgement
- Active-session counts are aligned across:
- overview KPI
- certainty card
- sidebar / summary strips
- Task certainty no longer depends on only the first recent-session page:
- linked session evidence is loaded for the visible task set
- task detail pages no longer stop at the first 6 linked sessions
- Detail links now keep the current UI language when opening task / cron drill-down pages.
## Dashboard highlights (Phase 15, UX v2)
- Home dashboard is now organized into six operator tabs with persistent left navigation:
- `Overview`
- `Office Space`
- `Projects/Tasks`
- `Alerts`
- `Replay/Audit`
- `Settings`
- UI moved to a colorful pixel-arcade visual style with dual sidebars (navigation + context rail).
- New `Office Space` view shows who is busy on what, grouped by office zones.
- Agent cards now include automatic animal identities derived from agent name semantics, with deterministic fallback mapping.
- Empty/zero-heavy blocks are softened:
- non-actionable zero states are minimized
- user-facing empty states now say `Not activated yet`.
- Home copy was rewritten from debug-heavy wording to operator-focused language while preserving all existing routes and backend behavior.
## Dashboard highlights (Phase 22, Usage/Cost parity surfaces)
- Added `Usage & Cost` section in the primary sidebar IA.
- Added Overview card-level usage/cost pulse:
- period totals (`today`, `7d`, `30d`)
- request-count source state
- burn-rate headline
- Added dedicated Usage & Cost dashboard section:
- context window visibility per active session/agent (absolute tokens + % when context catalog is available)
- pace/trend labels + warning thresholds
- usage/cost breakdown by agent, project, model, provider
- budget burn-rate status and alert messaging
- Added graceful unavailable-state behavior:
- explicit `Data source not connected` labels for disconnected metrics (instead of fake zeros)
- connector TODO list surfaced in Settings
- Added usage adapter endpoint:
- `GET /api/usage-cost`
## Dashboard highlights (Phase 25, Mission Control v3)
- UI visual reset to polished pixel-office style:
- design-token based palette/spacing/radius/shadow system
- layered office background grid + glow depth
- responsive desktop/mobile hierarchy with subtle card/status motion
- Navigation and copy reset for operator clarity:
- `Command Deck`, `Usage & Billing`, `Pixel Office`, `Work Board`, `Decisions`, `Timeline`, `Control Room`
- reduced technical wording on primary surfaces
- advanced links preserved under explicit disclosure
- Mac parity surfaces panel added with status + route entry for:
- conversations, approvals/decision queue, cron, projects/tasks, usage/cost, replay/audit, health/digest, export/import dry-run safety, pixel adapter
- Full roster office model:
- best-effort OpenClaw roster read from `~/.openclaw/openclaw.json` via `src/runtime/agent-roster.ts`
- office floor now renders desk/zone occupancy and includes known agents beyond active sessions
- Subscription usage/remaining best-effort integration:
- adapter support in `src/runtime/usage-cost.ts` for connected/partial/not_connected states
- UI now shows consumed/remaining/limit/cycle/source and explicit connection targets when unavailable
## Dashboard highlights (Phase 68, Plain-language certainty)
- Added `Information certainty` card to Overview and Settings:
- tells non-technical operators which parts of the picture are trustworthy now
- calls out remaining blind spots in plain language
- Added `Execution certainty` board to Tasks:
- scores whether each in-flight task is backed by real execution evidence
- separates `evidence is strong` from `needs follow-up` and `evidence is weak`
- Task detail pages now act as evidence pages:
- certainty judgement
- linked session evidence and recent activity summaries
## API validation/error envelope
- API mutating routes require `Content-Type: application/json`.
- Import/export and mutating routes require local token auth by default:
- header: `x-local-token: <LOCAL_API_TOKEN>`
- or `Authorization: Bearer <LOCAL_API_TOKEN>`
- Strict API query validation rejects unknown query keys.
- JSON errors use a consistent envelope:
## API 校验与错误包络
- 所有修改型 API 都要求 `Content-Type: application/json`
- 导入/导出和所有修改型接口默认需要本地 token：
- header：`x-local-token: <LOCAL_API_TOKEN>`
- 或 `Authorization: Bearer <LOCAL_API_TOKEN>`
- 严格 query 校验会拒绝未知参数
- JSON 错误统一格式：
- `{"ok":false,"requestId":"...","error":{"code":"...","status":<http>,"message":"...","issues":[],"requestId":"..."}}`
- JSON responses include `requestId` and all responses include `x-request-id` header for correlation.
- JSON 响应会带 `requestId`，所有响应头都会带 `x-request-id`
## Live import warning
- `POST /api/import/live` is intentionally disabled by default.
- Do not enable it unless you are doing a controlled local restore test.
- Live mode mutates local runtime stores (`runtime/projects.json`, `runtime/tasks.json`, `runtime/budgets.json`).
- Keep `READONLY_MODE=true` and `IMPORT_MUTATION_ENABLED=false` in normal operation.
## Live import 警告
- `POST /api/import/live` 默认关闭
- 除非你在做受控的本地恢复测试，否则不要开启
- Live mode 会修改本地 runtime 存储，例如：
- `runtime/projects.json`
- `runtime/tasks.json`
- `runtime/budgets.json`
- 正常使用时请保持 `READONLY_MODE=true` 和 `IMPORT_MUTATION_ENABLED=false`
## Runtime files
## Runtime 文件
- `runtime/last-snapshot.json`
- `runtime/timeline.log`
- `runtime/projects.json`
@@ -479,7 +343,7 @@ For protected command modes (`command:backup-export`, `command:import-validate`,
- `runtime/export-snapshots/*.json`
- `runtime/exports/*.json`
## Docs
## 文档
- `docs/ARCHITECTURE.md`
- `docs/RUNBOOK.md`
- `docs/PROGRESS.md`
README.zh-CN.md
-349
View File
@@ -1,349 +0,0 @@
# OpenClaw Control Center
<img src="docs/assets/overview-hero-zh.png" alt="OpenClaw Control Center 总览横幅截图" width="1200" />
OpenClaw 的安全优先、本地优先控制中心。
语言： [English](README.md) | **中文**
## 这个项目是做什么的
- 给 OpenClaw 提供一个本地控制中心，集中看系统是否稳定、谁在工作、哪些任务卡住了、今天花了多少。
- 面向非技术用户，重点是“看得懂、看得准”，不是暴露原始后端 payload。
- 首次接入默认安全：
- 默认只读
- 默认本地 token 鉴权
- 默认关闭高风险写操作
## 你能得到什么
- `总览`：系统状态、待处理事项、关键风险和运营摘要
- `用量`：用量、花费、订阅窗口和连接状态
- `员工`：谁真的在工作，谁只是排队待命
- `任务`：当前任务、审批、执行链和运行证据
- `文档` 与 `记忆`：按活跃 OpenClaw agent 范围展示的源文件工作台
## 适合谁
- 已经在用 OpenClaw、想要一个统一控制中心的团队或个人
- 在同一台机器或可达本地环境里运行 OpenClaw 的使用者
- 想公开发布一个安全优先的 OpenClaw 控制台，而不是做通用 agent 平台的人
## 截图
以下截图来自一个本地 OpenClaw 环境：
<img src="docs/assets/usage-en.png" alt="OpenClaw Control Center 用量截图" width="900" />
## 5 分钟启动
```bash
npm install
cp .env.example .env
npm run build
npm test
npm run smoke:ui
UI_MODE=true npm run dev
```
然后打开：
- `http://127.0.0.1:4310/?section=overview&lang=zh`
- `http://127.0.0.1:4310/?section=overview&lang=en`
## 分区功能说明
### 总览
- 给非技术用户看的主操作页。
- 集中展示当前总控态势、待处理事项、运行异常、停滞执行、预算风险、谁在忙、哪些地方需要优先关注。
- 最适合快速回答一句话：`OpenClaw 现在整体正常吗？`
### 用量
- 展示今日、7 天、30 天的用量和花费趋势。
- 包含订阅窗口、配额消耗、用量结构和数据连接状态。
- 最适合判断花费或额度是否开始有风险。
### 员工
- 展示谁现在真的在工作，谁只是有排队中的任务。
- 明确区分“正在执行”和“下一项”，避免把 backlog 误认为正在跑。
- 最适合判断谁忙、谁闲、谁卡住、谁在等待。
### 记忆
- 一个直接基于源文件的记忆工作台，用来查看和编辑每日记忆与长期记忆。
- 范围跟随 `openclaw.json` 里的活跃 agent，不会把已删除 agent 继续显示出来。
- 最适合查看或维护当前 OpenClaw 团队真实在用的记忆内容。
### 文档
- 一个直接基于源文件的文档工作台，用来查看和编辑共享文档与 agent 核心文档。
- 打开的是实际源文件，保存后也直接写回同一个源文件。
- 最适合维护系统背后真正生效的工作文档。
### 任务
- 把任务板、排期、审批、执行链和运行证据放在同一个分区里。
- 能帮助区分哪些只是看板映射，哪些已经有真实执行证据，哪些任务卡住了、需要跟进或待审。
- 最适合理解“现在到底在做什么、只是计划了什么、哪些需要你介入”。
### 设置
- 展示安全模式、连接器状态和数据链路预期。
- 会明确告诉你哪些数据已经接上，哪些还只是部分可见，哪些高风险动作是故意关闭的。
- 最适合排查环境配置、解释为什么某些信号缺失。
## 核心约束
- 只修改 `control-center/` 目录内的文件
- 默认 `READONLY_MODE=true`
- 默认 `LOCAL_TOKEN_AUTH_REQUIRED=true`
- 默认 `IMPORT_MUTATION_ENABLED=false`
- 默认 `IMPORT_MUTATION_DRY_RUN=false`
- 开启鉴权时，导入/导出和所有改状态接口都需要本地 token
- 审批动作有硬开关，默认关闭：`APPROVAL_ACTIONS_ENABLED=false`
- 审批动作默认 dry-run：`APPROVAL_ACTIONS_DRY_RUN=true`
- 不会改写 `~/.openclaw/openclaw.json`
## 安装与上手
### 1. 开始前准备
你最好已经有：
- 一个可用的 OpenClaw 安装
- 一个可连接的 OpenClaw Gateway
- 当前机器上的 `node` 和 `npm`
- 对 OpenClaw 主目录的读取权限
如果你希望 `用量 / 订阅` 信息更完整，当前机器最好还能读到：
- `~/.openclaw`
- `~/.codex`
- OpenClaw 订阅快照文件，尤其是它不在默认位置时
### 2. 安装项目
```bash
git clone <你的仓库地址>
cd control-center
npm install
cp .env.example .env
```
### 3. 配置 `.env`
第一次接入建议保持安全默认值，不要急着打开写操作。
基线配置如下：
```dotenv
GATEWAY_URL=ws://127.0.0.1:18789
READONLY_MODE=true
APPROVAL_ACTIONS_ENABLED=false
APPROVAL_ACTIONS_DRY_RUN=true
IMPORT_MUTATION_ENABLED=false
IMPORT_MUTATION_DRY_RUN=false
LOCAL_TOKEN_AUTH_REQUIRED=true
UI_MODE=false
UI_PORT=4310
# 只有路径不是默认值时才需要设置：
# OPENCLAW_HOME=/path/to/.openclaw
# CODEX_HOME=/path/to/.codex
# OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH=/path/to/subscription.json
```
一般只需要在这些情况下修改：
- `GATEWAY_URL`：你的 Gateway 不在默认本地地址
- `OPENCLAW_HOME`：OpenClaw 不在 `~/.openclaw`
- `CODEX_HOME`：Codex 数据不在 `~/.codex`
- `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`：订阅或账单快照文件在自定义位置
- `UI_PORT`：`4310` 已被占用
### 4. 可选：让你自己的 OpenClaw 帮你配置
你可以把下面这段提示词直接交给自己的 OpenClaw：
```text
你现在要帮我把 OpenClaw Control Center 接到这台机器自己的 OpenClaw 环境上。
只允许在 control-center 仓库里工作。
除非我明确要求，否则不要修改应用源码。
目标是完成一次安全的首次接入配置。
请按下面步骤执行：
1. 检查 OpenClaw Gateway 是否可达，并告诉我正确的 gateway URL。
2. 确认这台机器上正确的 OpenClaw 主目录和 Codex 主目录。
3. 对照 .env.example，创建或更新 .env。
4. 第一次接入时必须保持这些值：
- READONLY_MODE=true
- LOCAL_TOKEN_AUTH_REQUIRED=true
- APPROVAL_ACTIONS_ENABLED=false
- IMPORT_MUTATION_ENABLED=false
5. 不要开启 live import，也不要开启 approval mutation。
6. 不要改 OpenClaw 自己的配置文件。
7. 完成后输出：
- 你实际修改了哪些 env 值
- 我下一步应该执行的准确命令
- 我应该先打开哪些页面来确认接入成功
8. 如果缺少必要的路径、进程或文件，不要猜，直接明确告诉我缺什么。
```
### 5. 验证安装
执行：
```bash
npm run build
npm test
npm run smoke:ui
```
预期结果：
- build 通过
- test 通过
- UI smoke 输出本地地址，例如 `http://127.0.0.1:<port>`
### 6. 启动界面
```bash
UI_MODE=true npm run dev
```
然后打开：
- 中文界面：`http://127.0.0.1:4310/?section=overview&lang=zh`
- 英文界面：`http://127.0.0.1:4310/?section=overview&lang=en`
如果你改了 `UI_PORT`，把 `4310` 替换成你的端口。
### 7. 首次检查顺序
1. `总览`：页面能正常打开，并且能看到当前系统状态
2. `用量`：能看到真实数字，或者明确的“数据源未连接”
3. `员工`：实时工作状态与真实 active session 基本一致
4. `任务`：当前工作、审批、执行链能正常加载，不会吐原始 payload
5. `文档` 与 `记忆`：显示的 agent 标签和 `openclaw.json` 中的活跃 agent 一致
### 8. 如果看起来不对
- 实时活动全空，通常是 `GATEWAY_URL` 错了，或者 OpenClaw Gateway 没启动
- `文档 / 记忆` 范围不对，通常是 `OPENCLAW_HOME` 指错了，或者 `openclaw.json` 不可读
- `用量 / 订阅` 没数据，通常是 `CODEX_HOME` 或 `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH` 没配对
- 如果你只是想先安全观察，不要改默认的只读和 mutation 开关
## 本地命令
- `npm run build`
- `npm run dev`
- `npm run dev:continuous`
- `npm run dev:ui`
- `npm run smoke:ui`
- `npm run release:audit`
- `npm run command:backup-export`
- `npm run command:import-validate -- runtime/exports/<file>.json`
- `npm run command:acks-prune`
- `npm test`
- `npm run validate`
对于受保护的命令模式（如 `command:backup-export`、`command:import-validate`、`command:acks-prune`），如果 `LOCAL_TOKEN_AUTH_REQUIRED=true`，请先设置 `LOCAL_API_TOKEN=<token>`。
## 开源与发布卫生
- 仓库已经包含 `.gitignore`、`LICENSE` 和可发布的 package 元数据
- Gateway 地址可通过 `GATEWAY_URL` 配置，不再绑定单一本地 socket
- PM2、mission harness、workflow 和 verifier 示例都只用仓库相对路径和环境注入 secrets
- 公开文档统一使用通用 `~/.openclaw/...` 路径，不包含机器私有 home 目录
- 每次公开推送前，建议先运行 `npm run release:audit`
- 独立仓库发布流程见 [docs/PUBLISHING.md](docs/PUBLISHING.md)
## 本地 HTTP 接口
- `GET /snapshot`：原始快照 JSON
- `GET /projects`：项目列表，支持 `status`、`owner` 等查询过滤
- `GET /api/projects`：`/projects` 的兼容别名
- `POST /api/projects`：创建项目（`projectId`、`title`，可选 `status`、`owner`）
- `PATCH /api/projects/:projectId`：更新项目标题、状态或 owner
- `GET /tasks`：任务列表，支持 `status`、`owner`、`project` 过滤
- `GET /api/tasks`：`/tasks` 的兼容别名
- `POST /api/tasks`：按 schema 校验创建任务
- `PATCH /api/tasks/:taskId/status`：按 schema 校验更新任务状态
- `GET /sessions`：分页会话列表，支持 `state`、`agentId`、`q`、`page`、`pageSize`、`historyLimit`
- `GET /sessions/:id`：单会话 JSON 详情，支持 `historyLimit`
- `GET /api/sessions/:id`：单会话详情的 API 别名
- `GET /session/:id`：本地化会话详情页面，支持 `lang=en|zh`
- `GET /api/commander/exceptions`：仅异常视图的汇总
- `GET /exceptions`：按严重级别排序的异常流
- `GET /done-checklist`：最终集成检查清单与 readiness 评分
- `GET /api/action-queue`：基于异常流和 ack 状态生成的待处理队列
- `GET /graph`：项目-任务-会话关联图 JSON
- `GET /usage-cost`：跳转到 `/?section=usage-cost`
- `GET /api/usage-cost`：用量、花费、订阅窗口、拆分和 burn-rate 快照
- `POST /api/import/dry-run`：导入包 dry-run 校验，不写状态
- `POST /api/import/live`：可选 live import，高风险、本地专用，默认关闭
- `GET /cron`：定时任务与健康状态
- `GET /healthz`：系统健康载荷
- `GET /digest/latest`：最新 digest 的 HTML 页面
- `GET /api/search/tasks|projects|sessions|exceptions`：安全子串搜索接口
- `GET /api/replay/index`：timeline、digest、export、bundle 的 replay/debug 索引
- `GET /docs`：本地化 docs 索引
- `GET /docs/readme|runbook|architecture|progress`：本地 markdown 文档视图
- `POST /api/approvals/:approvalId/approve|reject`：审批动作服务（受 gate 和 dry-run 控制）
- `GET /audit`：本地审计时间线页面
- `GET /api/audit`：审计时间线 JSON
## 看板亮点
### 总览、审批、回放与工具活动
- 首页支持内联搜索，直接接 `/api/search/*`
- 回放和导出卡片会展示返回数量、过滤数量、延迟和体积指标
- 审批数量使用完整 live 审批集，不再因为 preview 截断而少算
- 工具活动详情会加载真实 session 证据，不再出现“上面有统计、下面却说没有工具会话”的冲突
### 文档、记忆与 agent 范围
- `文档` 和 `记忆` 现在优先跟随 `~/.openclaw/openclaw.json` 中的活跃 agent
- 已删除 agent 不会因为旧目录残留而重新出现在 facet 按钮中
- 根级 OpenClaw 文件会显示为 `Main`
- 打开和保存文件时都直接读写源文件，不走陈旧副本
### 执行链与任务可读性
- 执行链卡片不再直接显示原始 JSON payload
- 未映射的隔离执行会使用稳定标题，例如 `Main · Cron 隔离执行`
- 长标题、长 session key 和 badge 现在都会在卡片内安全换行
- 任务页会显示真实执行证据，而不是只看截断的最近几条会话
### 员工状态与实时性
- `工作中 / Working` 只代表真实 live execution，不再把“还有 backlog”误判为正在工作
- 有 backlog 但没有 live session 的 agent 会显示为待命语义
- `正在处理什么` 与 `下一项` 被明确区分
### 用量、订阅与正确性
- `总览 / 任务 / 设置 / 用量` 共享同一套 usage/quota 真相源
- 活跃会话统计在首页 KPI、侧栏、摘要条中保持一致
- Codex 配额窗口标签会自动归一成稳定标签，例如 `5h` 和 `Week`
- 对缺失数据会显示明确的未连接状态，而不是假零值
### 视觉与体验
- 整体 UI 已收敛到更接近 Apple 原生的层次和卡片风格
- 执行链卡片改成更宽的栅格，不再四张挤在一行里
- 侧边导航里 `用量` 已放在 `总览` 下方，信息架构更贴近日常运营使用顺序
### Mission Control v3 能力
- UI 已演进到 polished pixel-office 风格
- 覆盖会话、审批、cron、任务、用量、回放、健康、导入导出 dry-run 等关键控制面
- 全 roster office 模型会读取 `openclaw.json` 中已知 agent，而不只看当前活跃会话
- 支持 best-effort 的订阅用量/剩余额度展示
## API 校验与错误包络
- 所有修改型 API 都要求 `Content-Type: application/json`
- 导入/导出和所有修改型接口默认需要本地 token：
- header：`x-local-token: <LOCAL_API_TOKEN>`
- 或 `Authorization: Bearer <LOCAL_API_TOKEN>`
- 严格 query 校验会拒绝未知参数
- JSON 错误统一格式：
- `{"ok":false,"requestId":"...","error":{"code":"...","status":<http>,"message":"...","issues":[],"requestId":"..."}}`
- JSON 响应会带 `requestId`，所有响应头都会带 `x-request-id`
## Live import 警告
- `POST /api/import/live` 默认关闭
- 除非你在做受控的本地恢复测试，否则不要开启
- Live mode 会修改本地 runtime 存储，例如：
- `runtime/projects.json`
- `runtime/tasks.json`
- `runtime/budgets.json`
- 正常使用时请保持 `READONLY_MODE=true` 和 `IMPORT_MUTATION_ENABLED=false`
## Runtime 文件
- `runtime/last-snapshot.json`
- `runtime/timeline.log`
- `runtime/projects.json`
- `runtime/tasks.json`
- `runtime/budgets.json`
- `runtime/notification-policy.json`
- `runtime/model-context-catalog.json`
- `runtime/ui-preferences.json`
- `runtime/acks.json`
- `runtime/approval-actions.log`
- `runtime/operation-audit.log`
- `runtime/digests/YYYY-MM-DD.json`
- `runtime/digests/YYYY-MM-DD.md`
- `runtime/export-snapshots/*.json`
- `runtime/exports/*.json`
## 文档
- `docs/ARCHITECTURE.md`
- `docs/RUNBOOK.md`
- `docs/PROGRESS.md`
docs/PROGRESS.md
+38
View File
@@ -1,5 +1,43 @@
# Progress
## Phase 134 (GitHub README now defaults to Chinese, with English as an explicit switch) — Completed
- Scope:
- Make the public GitHub landing page default to Chinese instead of English.
- Keep English available as a first-class alternate README, not a page anchor trick.
- Changed files:
- `README.md`
- `README.en.md`
- `README.zh-CN.md`
- `docs/PROGRESS.md`
- Implementation:
- Promoted the Chinese README content into `README.md` so GitHub now lands on Chinese by default.
- Created `README.en.md` as the standalone English landing page.
- Updated the language links so Chinese opens the default README and English opens the dedicated English file.
- Verification:
- `npm run release:audit`
- `npm run build`
- `npm test`
- `npm run smoke:ui`
## Phase 133 (README hero screenshots tightened to remove floaty outer whitespace) — Completed
- Scope:
- Fix the public README hero screenshots that looked washed out and “floating” on GitHub because too much outer whitespace from the browser page was included.
- Keep the same overview-first hero concept, but crop it tighter to the actual product surface.
- Changed files:
- `docs/assets/overview-hero-en.png`
- `docs/assets/overview-hero-zh.png`
- `.gitignore`
- `docs/PROGRESS.md`
- Implementation:
- Replaced both README hero screenshots with tighter crops that remove the large outer page margins.
- Kept the wide landscape aspect ratio while making the control-center surface fill the frame more naturally.
- Ignored temporary `*-tight.png` local crop artifacts so they do not pollute repo status.
- Verification:
- `npm run release:audit` passed.
- `npm run build` passed.
- `npm test` passed.
- `npm run smoke:ui` passed.
## Phase 132 (README now explains every primary product section) — Completed
- Scope:
- Make the public README explain what each main control-center section actually does instead of only showing screenshots and setup steps.
docs/assets/overview-hero-en.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 494 KiB

After

Width:  |  Height:  |  Size: 498 KiB

docs/assets/overview-hero-zh.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 488 KiB

After

Width:  |  Height:  |  Size: 500 KiB