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

Prepare English-first README for official outreach

Browse Source
This commit is contained in:
OpenClaw Local
2026-03-17 15:18:29 +01:00
parent e5fffed439
commit 0d850918bb
5 changed files with 631 additions and 1092 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.en.md
+4 -663
View File
@@ -1,666 +1,7 @@
> 中文用户可在这里切换：[打开中文 README](README.md)
> English is now the default README: [Open README.md](README.md)
>
> 中文用户可在这里切换：[打开中文 README](README.zh-CN.md)
# 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
- `Collaboration`: parent-child relays and cross-session messages between existing agent sessions
- `Tasks`: current work, approvals, execution chains, and runtime evidence
- `Documents` and `Memory`: source-backed workbenches scoped to active OpenClaw agents
## What this release adds
- `Collaboration`: a new standalone collaboration page so you can see both parent-child handoffs and verified cross-session agent communication such as `Main ⇄ Pandas`, instead of inferring everything from execution chains.
- `Settings`: a new `Connection health` card that tells you what is already wired, what is still partial, and where to finish setup.
- `Settings`: a new `Security risk summary` that translates current risk, impact, and next-step guidance into plain operator-facing language.
- `Settings`: a new `Update status` card for current version, latest version, update channel, and install method.
- `Usage`: a new `Context pressure` card so you can see which sessions are closer to context limits and where things may get slower or more expensive.
- `Memory`: a new `Memory status` card so you can see whether each visible agent's memory is usable, searchable, or worth checking.
## 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:
<table>
<tr>
<td width="56%">
<img src="docs/assets/token-share-en.png" alt="OpenClaw Control Center token attribution screenshot" width="100%" />
</td>
<td width="44%">
<img src="docs/assets/staff-en.png" alt="OpenClaw Control Center staff page screenshot" width="100%" />
</td>
</tr>
<tr>
<td><strong>Token attribution</strong><br />See which timed jobs are actually consuming tokens and how the share splits across them.</td>
<td><strong>Staff page</strong><br />See who is working now, who is on standby, recent output, and schedule state.</td>
</tr>
</table>
<table>
<tr>
<td width="56%">
<img src="docs/assets/collaboration-en.png" alt="OpenClaw Control Center collaboration screenshot" width="100%" />
</td>
<td width="44%">
<img src="docs/assets/settings-insights-en.png" alt="OpenClaw Control Center security and update status screenshot" width="100%" />
</td>
</tr>
<tr>
<td><strong>Collaboration page</strong><br />See parent-child relays and verified cross-session communication such as <code>Main ⇄ Pandas</code> in one place.</td>
<td><strong>Security and update status</strong><br />See current risk, impact, next-step guidance, and the gap between your current and latest version.</td>
</tr>
</table>
## 5-minute start
```bash
npm install
cp .env.example .env
npm run build
npm test
npm run smoke:ui
npm run dev:ui
```
Then open:
- `http://127.0.0.1:4310/?section=overview&lang=en`
- `http://127.0.0.1:4310/?section=overview&lang=zh`
Notes:
- Prefer `npm run dev:ui`; it is the more reliable cross-platform entry, especially on Windows shells.
- `npm run dev` only performs one monitor pass and does not start the HTTP UI.
## 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, context pressure, 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.
### Collaboration
- Shows how work moves between agents: who accepted it first, who handed it off, and which session is holding the next move.
- Covers both parent-child session relays and verified cross-session communication such as `sessions_send` / `inter-session message`.
- Best when you want to understand “who passed this to whom, and where is the collaboration waiting now?”
### 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.
- Now also shows whether each visible agent's memory is healthy, searchable, or needs attention.
- 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.
- Now includes `Connection health`, `Security risk summary`, and `Update status` as dedicated operator cards.
- 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. `npm run dev:ui`
## 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 https://github.com/TianyiDataScience/openclaw-control-center.git
cd control-center
npm install
cp .env.example .env
```
If OpenClaw claims the repo is missing `src/runtime` or other core source files, do not start patching code. The canonical repo layout already includes:
- `package.json`
- `src/runtime`
- `src/ui`
- `.env.example`
That error usually means:
- the current directory is not the `openclaw-control-center` repo root
- the wrong repo was cloned
- the checkout/download is incomplete
- the agent is running in the wrong workspace
### 3. Recommended default: let your own OpenClaw do the install and setup
The best first-run path is not manual setup. The best path is to give your own OpenClaw one install instruction block and let it do the safe wiring for you.
If you want a copy-ready standalone file, use:
- [INSTALL_PROMPT.en.md](INSTALL_PROMPT.en.md)
- [INSTALL_PROMPT.md](INSTALL_PROMPT.md)
It should handle:
- environment checks
- dependency install
- `.env` creation or correction
- safe first-run defaults
- `build / test / smoke`
- a final summary of what to run and what to open
This install instruction already accounts for common real-world differences such as:
- no GPT / Codex subscription, or no readable subscription snapshot
- OpenClaw running on API keys or non-Codex providers (for example OpenAI API, Anthropic, OpenRouter, or another provider backend)
- non-default `~/.openclaw`, `~/.codex`, Gateway URL, or UI port
- more than one plausible OpenClaw home, more than one Gateway candidate, or a non-default workspace on the same machine
- a completely different active agent roster from the examples in this repo
- a machine that can build locally but is not yet connected to a live Gateway
- missing `node` / `npm`, no npm-registry connectivity, or insufficient write permissions in the repo
- missing optional data sources where the control center should still come up safely in read-only mode
Copy the full block below into OpenClaw:
```text
You are installing and connecting OpenClaw Control Center to this machine's OpenClaw environment.
Your goal is not to explain theory. Your goal is to complete a safe first-run setup end to end.
Hard rules:
1. Work only inside the control-center repository.
2. Do not modify application source code unless I explicitly ask.
3. Do not modify OpenClaw's own config files.
4. Do not enable live import or approval mutations.
5. Keep all high-risk write paths disabled.
6. Do not assume default agent names, default paths, or a default subscription model. Use real inspection results from this machine.
7. Do not treat missing subscription data, missing Codex data, or a missing billing snapshot as an install failure. If the UI can run safely, continue and clearly mark which panels will be degraded.
8. Do not fabricate, generate, or overwrite any provider API key, token, cookie, or external credential. If OpenClaw itself is missing those prerequisites, report the gap instead of guessing.
Follow this order:
Phase 1: inspect the environment
1. Check whether the OpenClaw Gateway is reachable and confirm the correct `GATEWAY_URL`.
2. Confirm the correct `OPENCLAW_HOME` and `CODEX_HOME` on this machine.
3. If the subscription or billing snapshot is stored outside the default path, find the correct `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`.
4. Confirm which prerequisites are truly present and which are missing-but-degradable. At minimum, evaluate:
- `node`
- `npm`
- write access to the repo directory
- npm-registry reachability if dependencies are not installed yet
- the OpenClaw Gateway
- `openclaw.json`
- OpenClaw session/runtime data
- `CODEX_HOME`
- the subscription/billing snapshot
- whether the provider/backend prerequisites used by OpenClaw are already present (check presence only; never print secrets)
5. If more than one plausible `OPENCLAW_HOME`, Gateway, or workspace exists, do not guess. Prefer the combination backed by a live Gateway, a readable `openclaw.json`, and the strongest evidence that it belongs to the current project. If it is still ambiguous, stop and list the candidates.
6. If a path, process, or file is missing in a way that makes the control center impossible to start at all, such as missing `node` / `npm`, no ability to download dependencies, a non-writable repo, or an unreadable OpenClaw root, stop and tell me exactly what is missing instead of guessing.
7. If the missing item only affects richer dashboards, such as subscription snapshots, Codex telemetry, part of the runtime data, or Codex-specific telemetry on a machine that actually uses API-key/provider mode, continue the install and mark those areas as "install can continue, but this surface will be partial".
8. Do not assume any fixed agent names. If `openclaw.json` is readable, treat it as the source of truth. If not, fall back to runtime-visible agents and explicitly say that roster confidence is lower.
Phase 2: install the project
9. Confirm that the current directory is the control-center repo root.
10. First verify the repo is complete. At minimum, confirm these paths exist:
- `package.json`
- `src/runtime`
- `src/ui`
- `.env.example`
11. If `src/runtime`, `src/ui`, or `package.json` is missing, do not continue and do not guess where the code should come from. Classify it as "wrong repo / incomplete checkout / wrong working directory", then:
- leave the incorrect directory
- re-clone `https://github.com/TianyiDataScience/openclaw-control-center.git`
- continue only after entering the new repo root
12. Install dependencies.
13. If `.env` does not exist, create it from `.env.example`. If it already exists, update it while preserving safe first-run defaults. Do not delete unrelated user settings; only change the keys required for this connection.
Phase 3: apply safe first-run settings
14. Keep these values:
- READONLY_MODE=true
- LOCAL_TOKEN_AUTH_REQUIRED=true
- APPROVAL_ACTIONS_ENABLED=false
- APPROVAL_ACTIONS_DRY_RUN=true
- IMPORT_MUTATION_ENABLED=false
- IMPORT_MUTATION_DRY_RUN=false
- UI_MODE=false
15. Only change these when the machine actually requires it:
- GATEWAY_URL
- OPENCLAW_HOME
- CODEX_HOME
- OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH
- UI_PORT
16. If this machine runs OpenClaw on provider API keys or a non-Codex backend instead of a Codex / GPT subscription, do not treat that as an error. Continue the install as long as OpenClaw itself can run, and say clearly that subscription/quota surfaces may be partially visible or unavailable.
17. If `CODEX_HOME` does not exist, or this machine simply does not have Codex / GPT subscription data, do not invent a path. Leave it unset and say clearly that Usage / Subscription will be partially visible or unavailable.
18. If no subscription snapshot exists, do not fabricate `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`. Continue the install and say that quota/subscription cards will show disconnected or estimated states.
19. If `4310` is already in use, choose a free local port, write it to `UI_PORT`, and report the new address clearly.
20. Do not change application logic just because my agent roster differs from the examples in this repo. The control center should reflect the agents configured or visible on my own machine.
Phase 4: verify the install
21. Run:
- npm run build
- npm test
- npm run smoke:ui
22. If any step fails, stop and tell me:
- which step failed
- why it failed
- what I should do next
23. If build / test / smoke pass but the live Gateway is still unreachable, do not classify the install as failed. Classify it as "local UI ready, live observability not connected yet".
24. If OpenClaw itself cannot produce live data because external provider credentials are missing, do not call that a control-center install failure. Classify it separately as "control center installed, upstream OpenClaw prerequisite missing".
Phase 5: hand off a ready-to-run result
25. If verification passes, print:
- which env values you changed
- which env values stayed on the defaults
- the exact command I should run next to launch the UI
- the first 3 dashboard pages I should open
- which missing signals are normal for a partially connected environment
- which capabilities are working now
- which capabilities are degraded because this machine lacks those data sources
- which env values or prerequisites I would need later if I want to connect subscription / Codex / live Gateway data
- which missing provider credentials, external auth, or upstream OpenClaw services are outside the control-center repo and still need operator action
Format your final answer as:
- Environment check
- Differences and degradation assessment
- Actual changes
- Verification result
- Next command
- First pages to open
```
### 4. If you want to configure `.env` manually
Only use this path if you do not want OpenClaw to handle setup for you.
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 a reverse proxy, container, or another machine must reach the UI:
# UI_BIND_ADDRESS=0.0.0.0
# Optional only when your paths differ from the defaults:
# OPENCLAW_HOME=/path/to/.openclaw
# OPENCLAW_CONFIG_PATH=/path/to/openclaw.json
# OPENCLAW_WORKSPACE_ROOT=/path/to/workspace
# OPENCLAW_AGENT_ROOT=/path/to/one/agent/workspace
# 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`
- `OPENCLAW_CONFIG_PATH`: when `openclaw.json` lives somewhere custom
- `OPENCLAW_WORKSPACE_ROOT`: when control-center is installed outside the OpenClaw workspace tree and you want to pin the true workspace root
- `OPENCLAW_AGENT_ROOT`: when control-center is not inside an agent workspace but you still want legacy agent-local memory/mission reads to point at one specific agent workspace
- `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
- `UI_BIND_ADDRESS`: when your reverse proxy, container, or browser is not on the same loopback network and cannot reach the default `127.0.0.1` bind
### 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
npm run dev:ui
```
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.
If a reverse proxy, container, or another machine must reach the UI, also set `UI_BIND_ADDRESS=0.0.0.0`.
### 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`, `OPENCLAW_CONFIG_PATH`, or `OPENCLAW_WORKSPACE_ROOT` points to the wrong place, or `openclaw.json` is missing.
- Missing usage/subscription data usually means `CODEX_HOME` or `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH` needs to be set.
- If the address does not open or a reverse proxy cannot reach the app, first confirm you started `npm run dev:ui`; if the proxy is outside the same machine/container, set `UI_BIND_ADDRESS=0.0.0.0`.
- 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`.
Also:
- `npm run dev`: runs one monitor pass without starting the UI
- `npm run dev:ui`: starts the local UI server
## Maintainer publishing notes
If you are publishing the repository itself, not just installing it, use this section. Normal operators can skip it.
- Run `npm run release:audit` before public pushes
- See [`docs/PUBLISHING.md`](docs/PUBLISHING.md) for the 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`
English now lives in [README.md](README.md). This file is kept as a compatibility entry so older links do not break.
README.md
+200 -429
View File
@@ -1,76 +1,76 @@
> Looking for English? Start here: [Open the English README](README.en.md)
> Chinese reader? Start here: [打开中文 README](README.zh-CN.md)
# OpenClaw Control Center
<img src="docs/assets/overview-hero-zh.png" alt="OpenClaw Control Center 总览横幅截图" width="1200" />
<img src="docs/assets/overview-hero-en.png" alt="OpenClaw Control Center overview hero screenshot" width="1200" />
OpenClaw 的安全优先、本地优先控制中心。
Turn OpenClaw from a black box into a local control center you can see, trust, and control.
语言： [English](README.en.md) | **中文**
Language: **English** | [中文](README.zh-CN.md)
## 这个项目是做什么的
- 给 OpenClaw 提供一个本地控制中心，集中看系统是否稳定、谁在工作、哪些任务卡住了、今天花了多少。
- 面向非技术用户，重点是“看得懂、看得准”，不是暴露原始后端 payload。
- 首次接入默认安全：
- 默认只读
- 默认本地 token 鉴权
- 默认关闭高风险写操作
## 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 agent 范围展示的源文件工作台
## 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
- `Collaboration`: parent-child relays and cross-session messages between existing agent sessions
- `Tasks`: current work, approvals, execution chains, and runtime evidence
- `Documents` and `Memory`: source-backed workbenches scoped to active OpenClaw agents
## 这个版本新增了什么
- `协作`：新增独立 `协作` 页面，直接看父子会话接力和 `Main ⇄ Pandas` 这种已验证跨会话通信，不再只看执行链猜关系。
- `设置`：新增 `接线状态`，直接告诉你哪些数据已经接好、哪些还差一步，以及该去哪里补。
- `设置`：新增 `安全风险摘要`，把当前风险、影响和下一步建议翻译成人话。
- `设置`：新增 `更新状态`，直接看当前版本、最新版本、更新通道和安装方式。
- `用量`：新增 `上下文压力`，直接看哪些会话更接近上下文上限，哪里可能变慢或变贵。
- `记忆`：新增 `记忆状态`，直接看每个智能体的记忆是否可用、可搜索、需不需要检查。
## What this release adds
- `Collaboration`: a new standalone collaboration page so you can see both parent-child handoffs and verified cross-session agent communication such as `Main ⇄ Pandas`, instead of inferring everything from execution chains.
- `Settings`: a new `Connection health` card that tells you what is already wired, what is still partial, and where to finish setup.
- `Settings`: a new `Security risk summary` that translates current risk, impact, and next-step guidance into plain operator-facing language.
- `Settings`: a new `Update status` card for current version, latest version, update channel, and install method.
- `Usage`: a new `Context pressure` card so you can see which sessions are closer to context limits and where things may get slower or more expensive.
- `Memory`: a new `Memory status` card so you can see whether each visible agent's memory is usable, searchable, or worth checking.
## 适合谁
- 已经在用 OpenClaw、想要一个统一控制中心的团队或个人
- 在同一台机器或可达本地环境里运行 OpenClaw 的使用者
- 想公开发布一个安全优先的 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 环境：
## Screenshots
Example UI from a local OpenClaw environment:
<table>
<tr>
<td width="56%">
<img src="docs/assets/token-share-zh.png" alt="OpenClaw Control Center 中文 token 消耗归因截图" width="100%" />
<img src="docs/assets/token-share-en.png" alt="OpenClaw Control Center token attribution screenshot" width="100%" />
</td>
<td width="44%">
<img src="docs/assets/staff-zh.png" alt="OpenClaw Control Center 中文员工页截图" width="100%" />
<img src="docs/assets/staff-en.png" alt="OpenClaw Control Center staff page screenshot" width="100%" />
</td>
</tr>
<tr>
<td><strong>Token 消耗归因</strong><br />直接看定时任务 token 是被哪些任务吃掉的，占比一眼可见。</td>
<td><strong>员工页</strong><br />直接看谁在工作、谁待命、最近产出和排班状态。</td>
<td><strong>Token attribution</strong><br />See which timed jobs are actually consuming tokens and how the share splits across them.</td>
<td><strong>Staff page</strong><br />See who is working now, who is on standby, recent output, and schedule state.</td>
</tr>
</table>
<table>
<tr>
<td width="56%">
<img src="docs/assets/collaboration-zh.png" alt="OpenClaw Control Center 中文协作页截图" width="100%" />
<img src="docs/assets/collaboration-en.png" alt="OpenClaw Control Center collaboration screenshot" width="100%" />
</td>
<td width="44%">
<img src="docs/assets/settings-insights-zh.png" alt="OpenClaw Control Center 中文安全与更新状态截图" width="100%" />
<img src="docs/assets/settings-insights-en.png" alt="OpenClaw Control Center security and update status screenshot" width="100%" />
</td>
</tr>
<tr>
<td><strong>协作页</strong><br />直接看父子会话接力，以及像 <code>Main ⇄ Pandas</code> 这样的已验证跨会话通信。</td>
<td><strong>安全与更新状态</strong><br />直接看当前风险、影响、下一步建议，以及当前版本和最新版本。</td>
<td><strong>Collaboration page</strong><br />See parent-child relays and verified cross-session communication such as <code>Main ⇄ Pandas</code> in one place.</td>
<td><strong>Security and update status</strong><br />See current risk, impact, next-step guidance, and the gap between your current and latest version.</td>
</tr>
</table>
## 5 分钟启动
## 5-minute start
```bash
npm install
cp .env.example .env
@@ -80,183 +80,180 @@ npm run smoke:ui
npm run dev:ui
```
然后打开：
- `http://127.0.0.1:4310/?section=overview&lang=zh`
Then open:
- `http://127.0.0.1:4310/?section=overview&lang=en`
- `http://127.0.0.1:4310/?section=overview&lang=zh`
说明：
- 推荐用 `npm run dev:ui` 启动界面；它比 `UI_MODE=true npm run dev` 更稳，尤其是 Windows shell。
- `npm run dev` 只会执行一次 monitor，不会启动 HTTP UI。
Notes:
- Prefer `npm run dev:ui`; it is the more reliable cross-platform entry, especially on Windows shells.
- `npm run dev` only performs one monitor pass and does not start the HTTP UI.
## 分区功能说明
## Section-by-section tour
### 总览
- 给非技术用户看的主操作页。
- 集中展示当前总控态势、待处理事项、运行异常、停滞执行、预算风险、谁在忙、哪些地方需要优先关注。
- 最适合快速回答一句话：`OpenClaw 现在整体正常吗？`
### 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?”
### 用量
- 展示今日、7 天、30 天的用量和花费趋势。
- 包含订阅窗口、配额消耗、用量结构、上下文压力和数据连接状态。
- 最适合判断花费或额度是否开始有风险。
### Usage
- Shows today, 7-day, and 30-day usage and spend trends.
- Includes subscription windows, quota consumption, usage mix, context pressure, and connector status.
- Best when you want to know whether spend or quota is becoming risky.
### 员工
- 展示谁现在真的在工作，谁只是有排队中的任务。
- 明确区分“正在执行”和“下一项”，避免把 backlog 误认为正在跑。
- 最适合判断谁忙、谁闲、谁卡住、谁在等待。
### 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.
### 协作
- 独立展示智能体之间怎么交接、谁先接单、谁派给了谁、回复从哪条会话回来。
- 既能看父会话与子会话的接力，也能看 `sessions_send` / `inter-session message` 这类已验证跨会话通信。
- 最适合理解“这件事到底是谁转给了谁、现在卡在谁这里”。
### Collaboration
- Shows how work moves between agents: who accepted it first, who handed it off, and which session is holding the next move.
- Covers both parent-child session relays and verified cross-session communication such as `sessions_send` / `inter-session message`.
- Best when you want to understand “who passed this to whom, and where is the collaboration waiting now?”
### 记忆
- 一个直接基于源文件的记忆工作台，用来查看和编辑每日记忆与长期记忆。
- 范围跟随 `openclaw.json` 里的活跃 agent，不会把已删除 agent 继续显示出来。
- 现在还会直接告诉你每个智能体的记忆是否正常、可搜索、是否需要检查。
- 最适合查看或维护当前 OpenClaw 团队真实在用的记忆内容。
### 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.
- Also shows whether each visible agent's memory is healthy, searchable, or needs attention.
- Best when you want to inspect or edit memory that the current OpenClaw team is actually using.
### 文档
- 一个直接基于源文件的文档工作台，用来查看和编辑共享文档与 agent 核心文档。
- 打开的是实际源文件，保存后也直接写回同一个源文件。
- 最适合维护系统背后真正生效的工作文档。
### 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.
- Includes `Connection health`, `Security risk summary`, and `Update status` as dedicated operator cards.
- Best when you want to verify environment setup or explain why a signal is missing.
## 核心约束
- 只修改 `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`
## What this is not
- Not a replacement for OpenClaw itself
- Not a generic dashboard for non-OpenClaw agent stacks
- Not a hosted SaaS control plane
## 安装与上手
## 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`.
### 1. 开始前准备
你最好已经有：
- 一个可用的 OpenClaw 安装
- 一个可连接的 OpenClaw Gateway
- 当前机器上的 `node` 和 `npm`
- 对 OpenClaw 主目录的读取权限
## 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. `npm run dev:ui`
如果你希望 `用量 / 订阅` 信息更完整，当前机器最好还能读到：
## 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`
- OpenClaw 订阅快照文件，尤其是它不在默认位置时
- a readable OpenClaw subscription snapshot, if your setup stores one outside the default locations
### 2. 安装项目
### 2. Install the project
```bash
git clone https://github.com/TianyiDataScience/openclaw-control-center.git
cd control-center
cd openclaw-control-center
npm install
cp .env.example .env
```
如果你的 OpenClaw 说“仓库缺少 `src/runtime`”或“缺少核心源码”，先不要改代码。这个仓库的标准结构本来就包含：
If OpenClaw claims the repo is missing `src/runtime` or other core source files, do not start patching code. The canonical repo layout already includes:
- `package.json`
- `src/runtime`
- `src/ui`
- `.env.example`
这类报错通常意味着：
- 当前目录不是 `openclaw-control-center` 仓库根目录
- clone 到了错误仓库
- checkout / 下载不完整
- agent 在错误 workspace 里执行
That error usually means:
- the current directory is not the `openclaw-control-center` repo root
- the wrong repo was cloned
- the checkout/download is incomplete
- the agent is running in the wrong workspace
### 3. 默认推荐：让你自己的 OpenClaw 直接完成安装与接线
最推荐的接入方式，不是你手动一项项配，而是直接把下面这段安装指令交给你自己的 OpenClaw。
### 3. Recommended default: let your own OpenClaw do the install and setup
The best first-run path is not manual setup. The best path is to give your own OpenClaw one install instruction block and let it do the safe wiring for you.
如果你想直接复制独立文件，用这个：
- [INSTALL_PROMPT.md](INSTALL_PROMPT.md)
If you want a copy-ready standalone file, use:
- [INSTALL_PROMPT.en.md](INSTALL_PROMPT.en.md)
- [INSTALL_PROMPT.md](INSTALL_PROMPT.md)
它应该一次性帮你做完这些事：
- 检查本机 OpenClaw / Gateway / 路径
- 安装依赖
- 创建或修正 `.env`
- 保持安全默认值
- 跑 `build / test / smoke`
- 告诉你最后该执行什么命令、该看哪些页面
It should handle:
- environment checks
- dependency install
- `.env` creation or correction
- safe first-run defaults
- `build / test / smoke`
- a final summary of what to run and what to open
这段安装指令已经考虑了这些常见情况：
- 用户没有 GPT / Codex 订阅，或者没有可读的订阅快照
- 用户的 OpenClaw 底层不是订阅，而是 API key / 其他 provider（例如 OpenAI API、Anthropic、OpenRouter 等）
- `~/.openclaw`、`~/.codex`、Gateway 地址、端口都不是默认值
- 一台机器上存在多套 OpenClaw home、多个可能的 Gateway，或者当前项目不是默认 workspace
- 机器上的活跃 agent 名单和本仓库示例完全不同
- 机器当前只能本地构建，暂时还接不上 live Gateway
- 机器缺少 `node` / `npm`、没有 npm registry 网络、或者仓库目录没有写权限
- 某些数据源缺失，但控制中心仍然应该先以“安全只读”方式跑起来
This install instruction already accounts for common real-world differences such as:
- no GPT / Codex subscription, or no readable subscription snapshot
- OpenClaw running on API keys or non-Codex providers (for example OpenAI API, Anthropic, OpenRouter, or another provider backend)
- non-default `~/.openclaw`, `~/.codex`, Gateway URL, or UI port
- more than one plausible OpenClaw home, more than one Gateway candidate, or a non-default workspace on the same machine
- a completely different active agent roster from the examples in this repo
- a machine that can build locally but is not yet connected to a live Gateway
- missing `node` / `npm`, no npm-registry connectivity, or insufficient write permissions in the repo
- missing optional data sources where the control center should still come up safely in read-only mode
直接把下面整段原样交给 OpenClaw：
Copy the full block below into OpenClaw:
```text
你现在要帮我把 OpenClaw Control Center 安装并接到这台机器自己的 OpenClaw 环境上。
You are installing and connecting OpenClaw Control Center to this machine's OpenClaw environment.
你的目标不是解释原理，而是直接完成一次安全的首次接入。
Your goal is not to explain theory. Your goal is to complete a safe first-run setup end to end.
严格约束：
1. 只允许在 control-center 仓库里工作。
2. 除非我明确要求，否则不要修改应用源码。
3. 不要修改 OpenClaw 自己的配置文件。
4. 不要开启 live import，不要开启 approval mutation。
5. 所有高风险写操作保持关闭。
6. 不要假设这台机器使用默认 agent 名称、默认路径、默认订阅方式，必须以实际探测结果为准。
7. 不要把“缺少订阅数据 / 缺少 Codex 数据 / 缺少账单快照”当成安装失败；只要 UI 能安全跑起来，就应当继续并明确哪些面板会降级。
8. 不要伪造、生成、改写任何 provider API key、token、cookie 或外部凭证；如果 OpenClaw 本身缺少这些前置条件，只能报告，不要替用户猜。
Hard rules:
1. Work only inside the control-center repository.
2. Do not modify application source code unless I explicitly ask.
3. Do not modify OpenClaw's own config files.
4. Do not enable live import or approval mutations.
5. Keep all high-risk write paths disabled.
6. Do not assume default agent names, default paths, or a default subscription model. Use real inspection results from this machine.
7. Do not treat missing subscription data, missing Codex data, or a missing billing snapshot as an install failure. If the UI can run safely, continue and clearly mark which panels will be degraded.
8. Do not fabricate, generate, or overwrite any provider API key, token, cookie, or external credential. If OpenClaw itself is missing those prerequisites, report the gap instead of guessing.
请按这个顺序执行：
Follow this order:
第一阶段：确认环境
1. 检查 OpenClaw Gateway 是否可达，并确认正确的 `GATEWAY_URL`。
2. 确认这台机器上正确的 `OPENCLAW_HOME` 和 `CODEX_HOME`。
3. 如果订阅或账单快照文件不在默认位置，找到正确的 `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`。
4. 确认这台机器上有哪些前提是真正存在的，哪些是缺失但允许降级的。至少分别判断：
- `node`
- `npm`
- 仓库目录写权限
- npm registry 网络连通性（如果本机还没安装依赖）
- OpenClaw Gateway
- `openclaw.json`
- OpenClaw 会话 / 运行时数据
- `CODEX_HOME`
- 订阅 / 账单快照
- OpenClaw 当前依赖的 provider / 凭证是否已经由 OpenClaw 自己配置妥当（只检查是否存在，不要打印 secret）
5. 如果机器上存在多个候选 `OPENCLAW_HOME`、多个可能的 Gateway，或多个 workspace，不要猜。优先选择“当前正在运行的 Gateway + 可读 `openclaw.json` + 与当前项目最匹配”的组合；如果仍然无法确定，就停止并把候选项列出来。
6. 如果缺少会导致“完全无法启动控制中心”的必要路径、进程或文件，例如 `node` / `npm` 缺失、npm 无法下载依赖、仓库不可写、OpenClaw 根目录不可读，不要猜，直接停止并明确告诉我缺什么。
7. 如果缺少的只是增强型数据源，例如订阅快照、Codex telemetry、部分运行时文件，或者机器根本不是用订阅而是 API key/provider 方式运行，不要停止安装；继续并把这些项标记为“安装可继续，但相关页面会部分缺失”。
8. 不要假设任何固定 agent 名称。若 `openclaw.json` 可读，就以它为准；若不可读，再回退到运行时可见 agent，并明确说明可信度下降。
Phase 1: inspect the environment
1. Check whether the OpenClaw Gateway is reachable and confirm the correct `GATEWAY_URL`.
2. Confirm the correct `OPENCLAW_HOME` and `CODEX_HOME` on this machine.
3. If the subscription or billing snapshot is stored outside the default path, find the correct `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`.
4. Confirm which prerequisites are truly present and which are missing-but-degradable.
5. If more than one plausible `OPENCLAW_HOME`, Gateway, or workspace exists, do not guess.
6. If a path, process, or file is missing in a way that makes the control center impossible to start at all, stop and explain the missing prerequisite clearly.
7. If the missing item only affects richer dashboards, continue and mark those surfaces as partial.
8. Do not assume any fixed agent names. If `openclaw.json` is readable, treat it as the source of truth.
第二阶段：安装项目
9. 确认当前目录是 control-center 仓库根目录。
10. 先确认仓库本体完整。至少检查这些路径真实存在：
- `package.json`
- `src/runtime`
- `src/ui`
- `.env.example`
11. 如果缺少 `src/runtime`、`src/ui` 或 `package.json`，不要继续安装，也不要猜源码去哪了。直接把它判定为“错误仓库 / 不完整 checkout / 错误工作目录”，并执行：
- 退出当前错误目录
- 重新 clone：`https://github.com/TianyiDataScience/openclaw-control-center.git`
- 进入新 clone 的仓库根目录后再继续
12. 运行依赖安装。
13. 如果 `.env` 不存在，就从 `.env.example` 创建；如果存在，就在保留安全默认值的前提下修正它。不要删除用户已有的无关安全配置，只改这次接线真正需要的项。
Phase 2: install the project
9. Confirm that the current directory is the control-center repo root.
10. Verify the repo is complete before editing anything.
11. If core paths are missing, stop and re-clone the official repo.
12. Run dependency install.
13. If `.env` does not exist, create it from `.env.example`; otherwise correct it while preserving safe defaults.
第三阶段：配置安全首次接入
14. 保持这些值：
Phase 3: safe first-run configuration
14. Keep these values:
- READONLY_MODE=true
- LOCAL_TOKEN_AUTH_REQUIRED=true
- APPROVAL_ACTIONS_ENABLED=false
@@ -264,267 +261,41 @@ cp .env.example .env
- IMPORT_MUTATION_ENABLED=false
- IMPORT_MUTATION_DRY_RUN=false
- UI_MODE=false
15. 只有在本机环境确实不同的时候，才修改：
- GATEWAY_URL
- OPENCLAW_HOME
- CODEX_HOME
- OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH
- UI_PORT
16. 如果这台机器是通过 provider API key / 自定义 LLM 提供商运行 OpenClaw，而不是通过 Codex / GPT 订阅运行，不要把这当成错误；只要 OpenClaw 自己能工作，就继续安装，并明确说明订阅额度与部分 provider-specific 卡片可能不可见。
17. 如果 `CODEX_HOME` 不存在，或者这台机器根本没有 Codex / GPT 订阅数据，不要强行填假路径；保留为空，并在结果里明确说明“Usage / Subscription 将部分可见或不可见”。
18. 如果订阅快照不存在，不要伪造 `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`；继续安装，并明确说明订阅额度相关卡片会显示未连接或估算状态。
19. 如果 `4310` 被占用，选择一个空闲本地端口并写入 `UI_PORT`，然后把新地址明确告诉我。
20. 不要因为我的 agent roster 和示例仓库不同就改应用逻辑；控制中心应该根据我机器自己的 OpenClaw 配置和运行时数据来显示 agent。
15. Only change `GATEWAY_URL`, `OPENCLAW_HOME`, `CODEX_HOME`, `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`, or `UI_PORT` when this machine really requires it.
16. If `CODEX_HOME` or subscription data is missing, do not invent paths; continue and explain that Usage / Subscription will be partial.
第四阶段：验证安装
21. 运行：
Phase 4: validation
17. Run:
- npm run build
- npm test
- npm run smoke:ui
22. 如果有任何一步失败，停止并告诉我：
- 哪一步失败了
- 原因是什么
- 我下一步该怎么修
23. 如果 build / test / smoke 通过，但 live Gateway 仍不可达，也不要把这次接入判定为失败；要把结果归类为“本地 UI 已可用，但 live 观测尚未接通”。
24. 如果 OpenClaw 自己因为外部 provider 凭证缺失而无法产出实时数据，也不要误判为 control-center 安装失败；要单独归类为“控制中心已装好，但上游 OpenClaw 前置条件未满足”。
18. If any step fails, stop and tell me exactly which step failed, why, and what I should fix next.
19. If build / test / smoke succeed but the live Gateway is still unreachable, classify the result as: local UI works, but live observability is not fully connected yet.
第五阶段：交付可启动结果
25. 如果验证通过，输出：
- 你实际修改了哪些 env 值
- 最终 `.env` 中哪些值沿用了默认值
- 我下一步启动 UI 的准确命令
- 我应该先打开的 3 个页面
- 哪些信号如果为空，属于“正常但未接线完全”
- 哪些能力现在已经可用
- 哪些能力因为当前机器没有相关数据源而处于降级状态
- 如果我以后补上订阅 / Codex / Gateway，只需要补哪几个 env 或前置条件
- 如果当前缺的是 provider API key / 外部凭证 / 上游 OpenClaw 进程，请把它们列为“控制中心外部前置条件”
最后请用这个格式给我结果：
- 环境检查
- 差异与降级判断
- 实际修改
- 验证结果
- 下一步命令
- 首次打开页面
Phase 5: handoff
20. Output:
- which env values you changed
- which values stayed at defaults
- the exact command I should run next
- the first 3 pages I should open
- which empty signals are normal because this environment is only partially wired
- which capabilities are fully available right now
- which capabilities are degraded because of missing data sources
- what to add later if I want richer subscription / Codex / Gateway visibility
```
### 4. 如果你要手动配置 `.env`
如果你不想让 OpenClaw 代劳，再手动配。
## Best-practice install notes
- If the dashboard is mostly for operators, keep the first rollout read-only.
- If you are contacting the OpenClaw community or maintainers, keep the root README in English and keep the Chinese README one click away.
- Treat richer usage, subscription, and collaboration signals as optional enhancements, not first-run blockers.
第一次接入建议保持安全默认值，不要急着打开写操作。
## Showcase and outreach
- Ready-to-post X and Discord showcase copy lives in [docs/SHOWCASE.md](docs/SHOWCASE.md).
- If you are sharing this with the OpenClaw team, lead with the operator value: observability, certainty, collaboration, usage, memory, and security.
基线配置如下：
```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
# 只有在反向代理、Docker 或另一台机器需要访问 UI 时才设置：
# UI_BIND_ADDRESS=0.0.0.0
# 只有路径不是默认值时才需要设置：
# OPENCLAW_HOME=/path/to/.openclaw
# OPENCLAW_CONFIG_PATH=/path/to/openclaw.json
# OPENCLAW_WORKSPACE_ROOT=/path/to/workspace
# OPENCLAW_AGENT_ROOT=/path/to/one/agent/workspace
# CODEX_HOME=/path/to/.codex
# OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH=/path/to/subscription.json
```
一般只需要在这些情况下修改：
- `GATEWAY_URL`：你的 Gateway 不在默认本地地址
- `OPENCLAW_HOME`：OpenClaw 不在 `~/.openclaw`
- `OPENCLAW_CONFIG_PATH`：`openclaw.json` 不在默认位置
- `OPENCLAW_WORKSPACE_ROOT`：control-center 装在工作区树外，需要显式指定工作区根目录
- `OPENCLAW_AGENT_ROOT`：control-center 不在某个 agent 工作区内，但你仍希望旧版记忆/说明读取链指向指定 agent
- `CODEX_HOME`：Codex 数据不在 `~/.codex`
- `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`：订阅或账单快照文件在自定义位置
- `UI_PORT`：`4310` 已被占用
- `UI_BIND_ADDRESS`：反向代理、Docker、远程浏览器不在同一回环网络里，默认 `127.0.0.1` 无法被它们访问
### 5. 验证安装
执行：
```bash
npm run build
npm test
npm run smoke:ui
```
预期结果：
- build 通过
- test 通过
- UI smoke 输出本地地址，例如 `http://127.0.0.1:<port>`
### 6. 启动界面
```bash
npm run dev:ui
```
然后打开：
- 中文界面：`http://127.0.0.1:4310/?section=overview&lang=zh`
- 英文界面：`http://127.0.0.1:4310/?section=overview&lang=en`
如果你改了 `UI_PORT`，把 `4310` 替换成你的端口。
如果你需要让反向代理、Docker 或另一台机器访问这个 UI，再额外设置 `UI_BIND_ADDRESS=0.0.0.0`。
### 7. 首次检查顺序
1. `总览`：页面能正常打开，并且能看到当前系统状态
2. `用量`：能看到真实数字，或者明确的“数据源未连接”
3. `员工`：实时工作状态与真实 active session 基本一致
4. `任务`：当前工作、审批、执行链能正常加载，不会吐原始 payload
5. `文档` 与 `记忆`：显示的 agent 标签和 `openclaw.json` 中的活跃 agent 一致
### 8. 如果看起来不对
- 实时活动全空，通常是 `GATEWAY_URL` 错了，或者 OpenClaw Gateway 没启动
- `文档 / 记忆` 范围不对，通常是 `OPENCLAW_HOME` / `OPENCLAW_CONFIG_PATH` / `OPENCLAW_WORKSPACE_ROOT` 指错了，或者 `openclaw.json` 不可读
- `用量 / 订阅` 没数据，通常是 `CODEX_HOME` 或 `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH` 没配对
- 地址打不开或代理转发后不通，先确认你运行的是 `npm run dev:ui`；如果代理不在同一台机器/容器内，再设置 `UI_BIND_ADDRESS=0.0.0.0`
- 如果你只是想先安全观察，不要改默认的只读和 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>`。
另外：
- `npm run dev`：只执行一次 monitor，不启动 UI
- `npm run dev:ui`：启动本地 UI 服务
## 维护者发布说明
如果你是仓库维护者、准备公开发布，再看这部分；普通安装用户可以跳过。
- 公开推送前运行 `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`
## Release hygiene
- `.gitignore`, `LICENSE`, package metadata, and release audit checks are included.
- `GATEWAY_URL` is configurable; the project is not tied to one hardcoded local socket.
- Public docs use generic `~/.openclaw/...` style paths instead of personal machine paths.
- Run `npm run release:audit` before any public push.
- See [docs/PUBLISHING.md](docs/PUBLISHING.md) for standalone repo release flow.
README.zh-CN.md
+309
View File
@@ -0,0 +1,309 @@
> Looking for English? Start here: [Open the English README](README.md)
# 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 范围展示的源文件工作台
## 这个版本新增了什么
- `协作`：新增独立 `协作` 页面，直接看父子会话接力和 `Main ⇄ Pandas` 这种已验证跨会话通信，不再只看执行链猜关系。
- `设置`：新增 `接线状态`，直接告诉你哪些数据已经接好、哪些还差一步，以及该去哪里补。
- `设置`：新增 `安全风险摘要`，把当前风险、影响和下一步建议翻译成人话。
- `设置`：新增 `更新状态`，直接看当前版本、最新版本、更新通道和安装方式。
- `用量`：新增 `上下文压力`，直接看哪些会话更接近上下文上限，哪里可能变慢或变贵。
- `记忆`：新增 `记忆状态`，直接看每个智能体的记忆是否可用、可搜索、需不需要检查。
## 适合谁
- 已经在用 OpenClaw、想要一个统一控制中心的团队或个人
- 在同一台机器或可达本地环境里运行 OpenClaw 的使用者
- 想公开发布一个安全优先的 OpenClaw 控制台，而不是做通用 agent 平台的人
## 截图
以下截图来自一个本地 OpenClaw 环境：
<table>
<tr>
<td width="56%">
<img src="docs/assets/token-share-zh.png" alt="OpenClaw Control Center 中文 token 消耗归因截图" width="100%" />
</td>
<td width="44%">
<img src="docs/assets/staff-zh.png" alt="OpenClaw Control Center 中文员工页截图" width="100%" />
</td>
</tr>
<tr>
<td><strong>Token 消耗归因</strong><br />直接看定时任务 token 是被哪些任务吃掉的，占比一眼可见。</td>
<td><strong>员工页</strong><br />直接看谁在工作、谁待命、最近产出和排班状态。</td>
</tr>
</table>
<table>
<tr>
<td width="56%">
<img src="docs/assets/collaboration-zh.png" alt="OpenClaw Control Center 中文协作页截图" width="100%" />
</td>
<td width="44%">
<img src="docs/assets/settings-insights-zh.png" alt="OpenClaw Control Center 中文安全与更新状态截图" width="100%" />
</td>
</tr>
<tr>
<td><strong>协作页</strong><br />直接看父子会话接力，以及像 <code>Main ⇄ Pandas</code> 这样的已验证跨会话通信。</td>
<td><strong>安全与更新状态</strong><br />直接看当前风险、影响、下一步建议，以及当前版本和最新版本。</td>
</tr>
</table>
## 5 分钟启动
```bash
npm install
cp .env.example .env
npm run build
npm test
npm run smoke:ui
npm run dev:ui
```
然后打开：
- `http://127.0.0.1:4310/?section=overview&lang=zh`
- `http://127.0.0.1:4310/?section=overview&lang=en`
说明：
- 推荐用 `npm run dev:ui` 启动界面；它比 `UI_MODE=true npm run dev` 更稳，尤其是 Windows shell。
- `npm run dev` 只会执行一次 monitor，不会启动 HTTP UI。
## 分区功能说明
### 总览
- 给非技术用户看的主操作页。
- 集中展示当前总控态势、待处理事项、运行异常、停滞执行、预算风险、谁在忙、哪些地方需要优先关注。
- 最适合快速回答一句话：`OpenClaw 现在整体正常吗？`
### 用量
- 展示今日、7 天、30 天的用量和花费趋势。
- 包含订阅窗口、配额消耗、用量结构、上下文压力和数据连接状态。
- 最适合判断花费或额度是否开始有风险。
### 员工
- 展示谁现在真的在工作，谁只是有排队中的任务。
- 明确区分“正在执行”和“下一项”，避免把 backlog 误认为正在跑。
- 最适合判断谁忙、谁闲、谁卡住、谁在等待。
### 协作
- 独立展示智能体之间怎么交接、谁先接单、谁派给了谁、回复从哪条会话回来。
- 既能看父会话与子会话的接力，也能看 `sessions_send` / `inter-session message` 这类已验证跨会话通信。
- 最适合理解“这件事到底是谁转给了谁、现在卡在谁这里”。
### 记忆
- 一个直接基于源文件的记忆工作台，用来查看和编辑每日记忆与长期记忆。
- 范围跟随 `openclaw.json` 里的活跃 agent，不会把已删除 agent 继续显示出来。
- 现在还会直接告诉你每个智能体的记忆是否正常、可搜索、是否需要检查。
- 最适合查看或维护当前 OpenClaw 团队真实在用的记忆内容。
### 文档
- 一个直接基于源文件的文档工作台，用来查看和编辑共享文档与 agent 核心文档。
- 打开的是实际源文件，保存后也直接写回同一个源文件。
- 最适合维护系统背后真正生效的工作文档。
### 任务
- 把任务板、排期、审批、执行链和运行证据放在同一个分区里。
- 能帮助区分哪些只是看板映射，哪些已经有真实执行证据，哪些任务卡住了、需要跟进或待审。
- 最适合理解“现在到底在做什么、只是计划了什么、哪些需要你介入”。
### 设置
- 展示安全模式、连接器状态和数据链路预期。
- 会明确告诉你哪些数据已经接上，哪些还只是部分可见，哪些高风险动作是故意关闭的。
- 现在还包含 `接线状态`、`安全风险摘要` 和 `更新状态` 三张关键卡片。
- 最适合排查环境配置、解释为什么某些信号缺失。
## 这不是什么
- 不是 OpenClaw 本体的替代品
- 不是面向所有 agent 技术栈的通用平台
- 不是托管式 SaaS 控制台
## 核心约束
- 只修改 `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. `npm install`
2. `cp .env.example .env`
3. 第一次接入尽量保持安全默认值；只有在你的 OpenClaw 环境不是默认路径时，再改 `GATEWAY_URL` 或路径覆盖项
4. `npm run build`
5. `npm test`
6. `npm run smoke:ui`
7. `npm run dev:ui`
## 安装与上手
### 1. 开始前准备
你最好已经有：
- 一个可用的 OpenClaw 安装
- 一个可连接的 OpenClaw Gateway
- 当前机器上的 `node` 和 `npm`
- 对 OpenClaw 主目录的读取权限
如果你希望 `用量 / 订阅` 信息更完整，当前机器最好还能读到：
- `~/.openclaw`
- `~/.codex`
- OpenClaw 订阅快照文件，尤其是它不在默认位置时
### 2. 安装项目
```bash
git clone https://github.com/TianyiDataScience/openclaw-control-center.git
cd openclaw-control-center
npm install
cp .env.example .env
```
如果 OpenClaw 说“仓库缺少 `src/runtime`”或“缺少核心源码”，先不要改代码。这个仓库的标准结构本来就包含：
- `package.json`
- `src/runtime`
- `src/ui`
- `.env.example`
这类报错通常意味着：
- 当前目录不是 `openclaw-control-center` 仓库根目录
- clone 到了错误仓库
- checkout / 下载不完整
- agent 在错误 workspace 里执行
### 3. 默认推荐：让你自己的 OpenClaw 直接完成安装与接线
最推荐的接入方式，不是你手动一项项配，而是直接把下面这段安装指令交给你自己的 OpenClaw。
如果你想直接复制独立文件，用这个：
- [INSTALL_PROMPT.md](INSTALL_PROMPT.md)
- [INSTALL_PROMPT.en.md](INSTALL_PROMPT.en.md)
它应该一次性帮你做完这些事：
- 检查本机 OpenClaw / Gateway / 路径
- 安装依赖
- 创建或修正 `.env`
- 保持安全默认值
- 跑 `build / test / smoke`
- 告诉你最后该执行什么命令、该看哪些页面
这段安装指令已经考虑了这些常见情况：
- 用户没有 GPT / Codex 订阅，或者没有可读的订阅快照
- 用户的 OpenClaw 底层不是订阅，而是 API key / 其他 provider（例如 OpenAI API、Anthropic、OpenRouter 等）
- `~/.openclaw`、`~/.codex`、Gateway 地址、端口都不是默认值
- 一台机器上存在多套 OpenClaw home、多个可能的 Gateway，或者当前项目不是默认 workspace
- 机器上的活跃 agent 名单和本仓库示例完全不同
- 机器当前只能本地构建，暂时还接不上 live Gateway
- 机器缺少 `node` / `npm`、没有 npm registry 网络、或者仓库目录没有写权限
- 某些数据源缺失，但控制中心仍然应该先以“安全只读”方式跑起来
直接把下面整段原样交给 OpenClaw：
```text
你现在要帮我把 OpenClaw Control Center 安装并接到这台机器自己的 OpenClaw 环境上。
你的目标不是解释原理，而是直接完成一次安全的首次接入。
严格约束：
1. 只允许在 control-center 仓库里工作。
2. 除非我明确要求，否则不要修改应用源码。
3. 不要修改 OpenClaw 自己的配置文件。
4. 不要开启 live import，不要开启 approval mutation。
5. 所有高风险写操作保持关闭。
6. 不要假设这台机器使用默认 agent 名称、默认路径、默认订阅方式，必须以实际探测结果为准。
7. 不要把“缺少订阅数据 / 缺少 Codex 数据 / 缺少账单快照”当成安装失败；只要 UI 能安全跑起来，就应当继续并明确哪些面板会降级。
8. 不要伪造、生成、改写任何 provider API key、token、cookie 或外部凭证；如果 OpenClaw 本身缺少这些前置条件，只能报告，不要替用户猜。
请按这个顺序执行：
第一阶段：确认环境
1. 检查 OpenClaw Gateway 是否可达，并确认正确的 `GATEWAY_URL`。
2. 确认这台机器上正确的 `OPENCLAW_HOME` 和 `CODEX_HOME`。
3. 如果订阅或账单快照文件不在默认位置，找到正确的 `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`。
4. 确认这台机器上有哪些前提是真正存在的，哪些是缺失但允许降级的。
5. 如果机器上存在多个候选 `OPENCLAW_HOME`、多个可能的 Gateway，或多个 workspace，不要猜。
6. 如果缺少会导致“完全无法启动控制中心”的必要条件，直接停止并明确告诉我缺什么。
7. 如果缺少的只是增强型数据源，不要停止安装；继续并把这些项标记为“安装可继续，但相关页面会部分缺失”。
8. 不要假设任何固定 agent 名称。若 `openclaw.json` 可读，就以它为准。
第二阶段：安装项目
9. 确认当前目录是 control-center 仓库根目录。
10. 先确认仓库本体完整。
11. 如果缺少 `src/runtime`、`src/ui` 或 `package.json`，不要继续安装，直接重新 clone 官方仓库。
12. 运行依赖安装。
13. 如果 `.env` 不存在，就从 `.env.example` 创建；如果存在，就在保留安全默认值的前提下修正它。
第三阶段：配置安全首次接入
14. 保持这些值：
- READONLY_MODE=true
- LOCAL_TOKEN_AUTH_REQUIRED=true
- APPROVAL_ACTIONS_ENABLED=false
- APPROVAL_ACTIONS_DRY_RUN=true
- IMPORT_MUTATION_ENABLED=false
- IMPORT_MUTATION_DRY_RUN=false
- UI_MODE=false
15. 只有在本机环境确实不同的时候，才修改：
- GATEWAY_URL
- OPENCLAW_HOME
- CODEX_HOME
- OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH
- UI_PORT
16. 如果 `CODEX_HOME` 不存在，或者这台机器根本没有 Codex / GPT 订阅数据，不要强行填假路径；保留为空，并在结果里明确说明“Usage / Subscription 将部分可见或不可见”。
第四阶段：验证安装
17. 运行：
- npm run build
- npm test
- npm run smoke:ui
18. 如果有任何一步失败，停止并告诉我：
- 哪一步失败了
- 原因是什么
- 我下一步该怎么修
19. 如果 build / test / smoke 通过，但 live Gateway 仍不可达，也不要把这次接入判定为失败；要把结果归类为“本地 UI 已可用，但 live 观测尚未接通”。
第五阶段：交付可启动结果
20. 如果验证通过，输出：
- 你实际修改了哪些 env 值
- 最终 `.env` 中哪些值沿用了默认值
- 我下一步启动 UI 的准确命令
- 我应该先打开的 3 个页面
- 哪些信号如果为空，属于“正常但未接线完全”
- 哪些能力现在已经可用
- 哪些能力因为当前机器没有相关数据源而处于降级状态
- 如果我以后补上订阅 / Codex / Gateway，只需要补哪几个 env 或前置条件
```
## 最佳实践
- 如果这个控制中心主要给运营或观察用，第一轮上线尽量保持只读。
- 如果你准备联系 OpenClaw 官方或国际社区，仓库首页默认英文更合适，但中文入口应该保持一眼可见。
- richer usage / subscription / collaboration 这些面板是增强层，不该成为第一次启动的阻塞项。
## 对外展示与联系官方
- 明天可以直接复制的 X / Discord showcase 文案在 [docs/SHOWCASE.md](docs/SHOWCASE.md)。
- 如果你要联系 OpenClaw 官方，重点讲 operator value：观测、确定性、协作、用量、记忆、安全。
## 开源与发布卫生
- 仓库已经包含 `.gitignore`、`LICENSE` 和可发布的 package 元数据。
- `GATEWAY_URL` 可配置，不再绑定单一本地 socket。
- 公开文档统一使用通用 `~/.openclaw/...` 路径，不包含机器私有 home 目录。
- 每次公开推送前，建议先运行 `npm run release:audit`。
- 独立仓库发布流程见 [docs/PUBLISHING.md](docs/PUBLISHING.md)。
docs/PROGRESS.md
+23
View File
@@ -1,5 +1,28 @@
# Progress
## Phase 156 (English-first README and official showcase prep) — Completed
- Scope:
- Make the repository easier for OpenClaw maintainers and international users to understand at first glance.
- Keep Chinese users one click away instead of hiding or downgrading the Chinese landing page.
- Prepare copy-paste-ready outreach text for X and Discord showcase posts.
- Changed files:
- `README.md`
- `README.zh-CN.md`
- `README.en.md`
- `docs/SHOWCASE.md`
- `docs/PROGRESS.md`
- Implementation:
- Switched the root `README.md` to the full English landing page so the default GitHub homepage now opens in English.
- Restored the Chinese landing page as `README.zh-CN.md` and kept the language switch at the very top so Chinese readers do not get lost.
- Kept `README.en.md` as a compatibility entry pointing to the new English default, so older links do not break.
- Added `docs/SHOWCASE.md` with ready-to-post outreach copy for X, Discord `#showcase`, and Chinese audience sharing.
- Tightened the install examples so the repo clone step now uses the actual directory name: `openclaw-control-center`.
- Verification:
- Manual README link/path review
- Manual showcase copy review
- Remaining gap:
- GitHub repository topics / social preview still need to be adjusted through repo settings rather than source control.
## Phase 155 (Standalone collaboration page for agent handoffs) — Completed
- Scope:
- Add a dedicated `Collaboration / 协作` page so users can inspect agent-to-agent handoffs without overloading `Staff` or `Tasks`.
docs/SHOWCASE.md
+95
View File
@@ -0,0 +1,95 @@
# Showcase Copy
Use this file when sharing OpenClaw Control Center with the OpenClaw community, especially on X or in Discord `#showcase`.
## Positioning
Use this framing:
- community project
- operator-focused control center for OpenClaw
- focused on observability, certainty, collaboration, usage, memory, and security
Avoid this framing:
- replacement for the official OpenClaw Control UI
- official UI successor
- universal dashboard for every agent stack
## X post
```text
We built OpenClaw Control Center: a local, operator-focused control center for OpenClaw.
It helps teams see:
- usage and token attribution
- agent/staff activity
- verified agent collaboration
- memory and docs
- security risks and update status
Repo:
https://github.com/TianyiDataScience/openclaw-control-center
Would love to share this with the OpenClaw community @openclaw
```
## Short X post
```text
OpenClaw Control Center:
a local operator layer for OpenClaw focused on observability, usage, collaboration, memory, and security.
https://github.com/TianyiDataScience/openclaw-control-center
@openclaw
```
## Discord showcase post
```text
Built a community control center for OpenClaw.
OpenClaw Control Center is a local, operator-focused UI for:
- usage and token attribution
- agent/staff activity
- verified agent collaboration and inter-session communication
- docs and memory workbenches
- security risk summary and update status
Repo:
https://github.com/TianyiDataScience/openclaw-control-center
Happy to share screenshots or a short demo if useful.
```
## Chinese post for your own audience
```text
我们做了一个 OpenClaw Control Center。
它不是替代 OpenClaw 本体，而是把 OpenClaw 变得更透明、更可控：
- 看用量和 token 消耗归因
- 看员工 / agent 当前状态
- 看 agent 之间的协作与通信
- 看记忆、文档、安全风险和更新状态
仓库：
https://github.com/TianyiDataScience/openclaw-control-center
想分享给 OpenClaw 社区，也欢迎大家体验和反馈。@openclaw
```
## Attachments
For the first outreach post, attach:
- repo link
- 30 to 60 second demo
- token attribution screenshot
- staff screenshot
- collaboration screenshot
- security/update screenshot
## One-line description
```text
Turn OpenClaw from a black box into a local control center you can see, trust, and control.
```