From ccf04beec622ce73fc8d9ce26d07636c9cd6c831 Mon Sep 17 00:00:00 2001 From: OpenClaw Local Date: Wed, 11 Mar 2026 17:59:09 +0100 Subject: [PATCH] Harden README setup prompt for different OpenClaw environments --- README.en.md | 44 +++++++++++++++++++++++++++++++++++--------- README.md | 44 +++++++++++++++++++++++++++++++++++--------- docs/PROGRESS.md | 18 ++++++++++++++++++ 3 files changed, 88 insertions(+), 18 deletions(-) diff --git a/README.en.md b/README.en.md index 97dda8b..98ad3fc 100644 --- a/README.en.md +++ b/README.en.md @@ -153,6 +153,13 @@ It should handle: - `build / test / smoke` - a final summary of what to run and what to open +This prompt should also cover the common differences across users: +- no GPT / Codex subscription, or no readable subscription snapshot +- non-default `~/.openclaw`, `~/.codex`, Gateway URL, or UI port +- 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 optional data sources where the control center should still come up safely in read-only mode + Give OpenClaw this full prompt: ```text @@ -166,6 +173,8 @@ Hard rules: 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. Follow this order: @@ -173,15 +182,23 @@ 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. If any required path, process, or file is missing, stop and tell me exactly what is missing instead of guessing. +4. Confirm which prerequisites are truly present and which are missing-but-degradable. At minimum, evaluate: + - the OpenClaw Gateway + - `openclaw.json` + - OpenClaw session/runtime data + - `CODEX_HOME` + - the subscription/billing snapshot +5. If a path, process, or file is missing in a way that makes the control center impossible to start at all, stop and tell me exactly what is missing instead of guessing. +6. If the missing item only affects richer dashboards, such as subscription snapshots, Codex telemetry, or part of the runtime data, continue the install and mark those areas as "install can continue, but this surface will be partial". +7. 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 -5. Confirm that the current directory is the control-center repo root. -6. Install dependencies. -7. If `.env` does not exist, create it from `.env.example`. If it already exists, update it while preserving safe first-run defaults. +8. Confirm that the current directory is the control-center repo root. +9. Install dependencies. +10. If `.env` does not exist, create it from `.env.example`. If it already exists, update it while preserving safe first-run defaults. Phase 3: apply safe first-run settings -8. Keep these values: +11. Keep these values: - READONLY_MODE=true - LOCAL_TOKEN_AUTH_REQUIRED=true - APPROVAL_ACTIONS_ENABLED=false @@ -189,33 +206,42 @@ Phase 3: apply safe first-run settings - IMPORT_MUTATION_ENABLED=false - IMPORT_MUTATION_DRY_RUN=false - UI_MODE=false -9. Only change these when the machine actually requires it: +12. Only change these when the machine actually requires it: - GATEWAY_URL - OPENCLAW_HOME - CODEX_HOME - OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH - UI_PORT +13. 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. +14. 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. +15. If `4310` is already in use, choose a free local port, write it to `UI_PORT`, and report the new address clearly. +16. 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 -10. Run: +17. Run: - npm run build - npm test - npm run smoke:ui -11. If any step fails, stop and tell me: +18. If any step fails, stop and tell me: - which step failed - why it failed - what I should do next +19. 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". Phase 5: hand off a ready-to-run result -12. If verification passes, print: +20. 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 Format your final answer as: - Environment check +- Differences and degradation assessment - Actual changes - Verification result - Next command diff --git a/README.md b/README.md index 9113afd..c391d9d 100644 --- a/README.md +++ b/README.md @@ -139,6 +139,13 @@ cp .env.example .env - 跑 `build / test / smoke` - 告诉你最后该执行什么命令、该看哪些页面 +这段 prompt 应该覆盖这些常见差异： +- 用户没有 GPT / Codex 订阅，或者没有可读的订阅快照 +- `~/.openclaw`、`~/.codex`、Gateway 地址、端口都不是默认值 +- 机器上的活跃 agent 名单和本仓库示例完全不同 +- 机器当前只能本地构建，暂时还接不上 live Gateway +- 某些数据源缺失，但控制中心仍然应该先以“安全只读”方式跑起来 + 把下面整段原样交给 OpenClaw： ```text @@ -152,6 +159,8 @@ cp .env.example .env 3. 不要修改 OpenClaw 自己的配置文件。 4. 不要开启 live import，不要开启 approval mutation。 5. 所有高风险写操作保持关闭。 +6. 不要假设这台机器使用默认 agent 名称、默认路径、默认订阅方式，必须以实际探测结果为准。 +7. 不要把“缺少订阅数据 / 缺少 Codex 数据 / 缺少账单快照”当成安装失败；只要 UI 能安全跑起来，就应当继续并明确哪些面板会降级。 请按这个顺序执行： @@ -159,15 +168,23 @@ cp .env.example .env 1. 检查 OpenClaw Gateway 是否可达，并确认正确的 `GATEWAY_URL`。 2. 确认这台机器上正确的 `OPENCLAW_HOME` 和 `CODEX_HOME`。 3. 如果订阅或账单快照文件不在默认位置，找到正确的 `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`。 -4. 如果缺少必要路径、进程或文件，不要猜，直接停止并明确告诉我缺什么。 +4. 确认这台机器上有哪些前提是真正存在的，哪些是缺失但允许降级的。至少分别判断： + - OpenClaw Gateway + - `openclaw.json` + - OpenClaw 会话 / 运行时数据 + - `CODEX_HOME` + - 订阅 / 账单快照 +5. 如果缺少会导致“完全无法启动控制中心”的必要路径、进程或文件，不要猜，直接停止并明确告诉我缺什么。 +6. 如果缺少的只是增强型数据源，例如订阅快照、Codex telemetry 或部分运行时文件，不要停止安装；继续并把这些项标记为“安装可继续，但相关页面会部分缺失”。 +7. 不要假设任何固定 agent 名称。若 `openclaw.json` 可读，就以它为准；若不可读，再回退到运行时可见 agent，并明确说明可信度下降。 第二阶段：安装项目 -5. 确认当前目录是 control-center 仓库根目录。 -6. 运行依赖安装。 -7. 如果 `.env` 不存在，就从 `.env.example` 创建；如果存在，就在保留安全默认值的前提下修正它。 +8. 确认当前目录是 control-center 仓库根目录。 +9. 运行依赖安装。 +10. 如果 `.env` 不存在，就从 `.env.example` 创建；如果存在，就在保留安全默认值的前提下修正它。 第三阶段：配置安全首次接入 -8. 保持这些值： +11. 保持这些值： - READONLY_MODE=true - LOCAL_TOKEN_AUTH_REQUIRED=true - APPROVAL_ACTIONS_ENABLED=false @@ -175,33 +192,42 @@ cp .env.example .env - IMPORT_MUTATION_ENABLED=false - IMPORT_MUTATION_DRY_RUN=false - UI_MODE=false -9. 只有在本机环境确实不同的时候，才修改： +12. 只有在本机环境确实不同的时候，才修改： - GATEWAY_URL - OPENCLAW_HOME - CODEX_HOME - OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH - UI_PORT +13. 如果 `CODEX_HOME` 不存在，或者这台机器根本没有 Codex / GPT 订阅数据，不要强行填假路径；保留为空，并在结果里明确说明“Usage / Subscription 将部分可见或不可见”。 +14. 如果订阅快照不存在，不要伪造 `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`；继续安装，并明确说明订阅额度相关卡片会显示未连接或估算状态。 +15. 如果 `4310` 被占用，选择一个空闲本地端口并写入 `UI_PORT`，然后把新地址明确告诉我。 +16. 不要因为我的 agent roster 和示例仓库不同就改应用逻辑；控制中心应该根据我机器自己的 OpenClaw 配置和运行时数据来显示 agent。 第四阶段：验证安装 -10. 运行： +17. 运行： - npm run build - npm test - npm run smoke:ui -11. 如果有任何一步失败，停止并告诉我： +18. 如果有任何一步失败，停止并告诉我： - 哪一步失败了 - 原因是什么 - 我下一步该怎么修 +19. 如果 build / test / smoke 通过，但 live Gateway 仍不可达，也不要把这次接入判定为失败；要把结果归类为“本地 UI 已可用，但 live 观测尚未接通”。 第五阶段：交付可启动结果 -12. 如果验证通过，输出： +20. 如果验证通过，输出： - 你实际修改了哪些 env 值 - 最终 `.env` 中哪些值沿用了默认值 - 我下一步启动 UI 的准确命令 - 我应该先打开的 3 个页面 - 哪些信号如果为空，属于“正常但未接线完全” + - 哪些能力现在已经可用 + - 哪些能力因为当前机器没有相关数据源而处于降级状态 + - 如果我以后补上订阅 / Codex / Gateway，只需要补哪几个 env 或前置条件 最后请用这个格式给我结果： - 环境检查 +- 差异与降级判断 - 实际修改 - 验证结果 - 下一步命令 diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index 32e9d5f..5aa4ba2 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -1,5 +1,23 @@ # Progress +## Phase 141 (README install prompt now handles heterogeneous OpenClaw environments) — Completed +- Scope: + - Make the OpenClaw setup mega prompt robust for users whose machine, subscription state, agent roster, or data sources differ from the maintainer's environment. + - Explicitly distinguish hard blockers from acceptable degraded states. +- Changed files: + - `README.md` + - `README.en.md` + - `docs/PROGRESS.md` +- Implementation: + - Expanded the Chinese and English installation prompts so they no longer assume default agent names, default paths, Codex presence, or subscription snapshots. + - Added explicit guidance for no-subscription / no-Codex / no-billing-snapshot users and for machines that can run locally before live Gateway observability is connected. + - Required the installing OpenClaw to classify missing pieces as either startup blockers or degradations and to report which surfaces will remain partial. +- Verification: + - `npm run build` + - `npm test` + - `npm run smoke:ui` + - `npm run release:audit` + ## Phase 140 (README onboarding now defaults to OpenClaw-driven setup) — Completed - Scope: - Make the README recommend OpenClaw-assisted install as the primary onboarding path instead of an optional extra.