Harden README install prompt

README.en.md

@@ -155,9 +155,12 @@ It should handle:
 
 This prompt should also cover the common differences across users:
 - 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
 
 Give OpenClaw this full prompt:
@@ -175,6 +178,7 @@ Hard rules:
 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:
 
@@ -183,22 +187,28 @@ Phase 1: inspect the environment
 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
-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.
+   - 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
-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.
+9. Confirm that the current directory is the control-center repo root.
+10. Install dependencies.
+11. 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
-11. Keep these values:
+12. Keep these values:
    - READONLY_MODE=true
    - LOCAL_TOKEN_AUTH_REQUIRED=true
    - APPROVAL_ACTIONS_ENABLED=false
@@ -206,30 +216,32 @@ Phase 3: apply safe first-run settings
    - IMPORT_MUTATION_ENABLED=false
    - IMPORT_MUTATION_DRY_RUN=false
    - UI_MODE=false
-12. Only change these when the machine actually requires it:
+13. 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.
+14. 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.
+15. 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.
+16. 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.
+17. If `4310` is already in use, choose a free local port, write it to `UI_PORT`, and report the new address clearly.
+18. 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
-17. Run:
+19. Run:
    - npm run build
    - npm test
    - npm run smoke:ui
-18. If any step fails, stop and tell me:
+20. 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".
+21. 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".
+22. 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
-20. If verification passes, print:
+23. 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
@@ -238,6 +250,7 @@ Phase 5: hand off a ready-to-run result
    - 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

README.md

@@ -141,9 +141,12 @@ cp .env.example .env
 
 这段 prompt 应该覆盖这些常见差异：
 - 用户没有 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：
@@ -161,6 +164,7 @@ cp .env.example .env
 5. 所有高风险写操作保持关闭。
 6. 不要假设这台机器使用默认 agent 名称、默认路径、默认订阅方式，必须以实际探测结果为准。
 7. 不要把“缺少订阅数据 / 缺少 Codex 数据 / 缺少账单快照”当成安装失败；只要 UI 能安全跑起来，就应当继续并明确哪些面板会降级。
+8. 不要伪造、生成、改写任何 provider API key、token、cookie 或外部凭证；如果 OpenClaw 本身缺少这些前置条件，只能报告，不要替用户猜。
 
 请按这个顺序执行：
 
@@ -169,22 +173,28 @@ cp .env.example .env
 2. 确认这台机器上正确的 `OPENCLAW_HOME` 和 `CODEX_HOME`。
 3. 如果订阅或账单快照文件不在默认位置，找到正确的 `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`。
 4. 确认这台机器上有哪些前提是真正存在的，哪些是缺失但允许降级的。至少分别判断：
+   - `node`
+   - `npm`
+   - 仓库目录写权限
+   - npm registry 网络连通性（如果本机还没安装依赖）
    - OpenClaw Gateway
    - `openclaw.json`
    - OpenClaw 会话 / 运行时数据
    - `CODEX_HOME`
    - 订阅 / 账单快照
-5. 如果缺少会导致“完全无法启动控制中心”的必要路径、进程或文件，不要猜，直接停止并明确告诉我缺什么。
-6. 如果缺少的只是增强型数据源，例如订阅快照、Codex telemetry 或部分运行时文件，不要停止安装；继续并把这些项标记为“安装可继续，但相关页面会部分缺失”。
-7. 不要假设任何固定 agent 名称。若 `openclaw.json` 可读，就以它为准；若不可读，再回退到运行时可见 agent，并明确说明可信度下降。
+   - 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，并明确说明可信度下降。
 
 第二阶段：安装项目
-8. 确认当前目录是 control-center 仓库根目录。
-9. 运行依赖安装。
-10. 如果 `.env` 不存在，就从 `.env.example` 创建；如果存在，就在保留安全默认值的前提下修正它。
+9. 确认当前目录是 control-center 仓库根目录。
+10. 运行依赖安装。
+11. 如果 `.env` 不存在，就从 `.env.example` 创建；如果存在，就在保留安全默认值的前提下修正它。不要删除用户已有的无关安全配置，只改这次接线真正需要的项。
 
 第三阶段：配置安全首次接入
-11. 保持这些值：
+12. 保持这些值：
    - READONLY_MODE=true
    - LOCAL_TOKEN_AUTH_REQUIRED=true
    - APPROVAL_ACTIONS_ENABLED=false
@@ -192,30 +202,32 @@ cp .env.example .env
    - IMPORT_MUTATION_ENABLED=false
    - IMPORT_MUTATION_DRY_RUN=false
    - UI_MODE=false
-12. 只有在本机环境确实不同的时候，才修改：
+13. 只有在本机环境确实不同的时候，才修改：
    - 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。
+14. 如果这台机器是通过 provider API key / 自定义 LLM 提供商运行 OpenClaw，而不是通过 Codex / GPT 订阅运行，不要把这当成错误；只要 OpenClaw 自己能工作，就继续安装，并明确说明订阅额度与部分 provider-specific 卡片可能不可见。
+15. 如果 `CODEX_HOME` 不存在，或者这台机器根本没有 Codex / GPT 订阅数据，不要强行填假路径；保留为空，并在结果里明确说明“Usage / Subscription 将部分可见或不可见”。
+16. 如果订阅快照不存在，不要伪造 `OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH`；继续安装，并明确说明订阅额度相关卡片会显示未连接或估算状态。
+17. 如果 `4310` 被占用，选择一个空闲本地端口并写入 `UI_PORT`，然后把新地址明确告诉我。
+18. 不要因为我的 agent roster 和示例仓库不同就改应用逻辑；控制中心应该根据我机器自己的 OpenClaw 配置和运行时数据来显示 agent。
 
 第四阶段：验证安装
-17. 运行：
+19. 运行：
    - npm run build
    - npm test
    - npm run smoke:ui
-18. 如果有任何一步失败，停止并告诉我：
+20. 如果有任何一步失败，停止并告诉我：
    - 哪一步失败了
    - 原因是什么
    - 我下一步该怎么修
-19. 如果 build / test / smoke 通过，但 live Gateway 仍不可达，也不要把这次接入判定为失败；要把结果归类为“本地 UI 已可用，但 live 观测尚未接通”。
+21. 如果 build / test / smoke 通过，但 live Gateway 仍不可达，也不要把这次接入判定为失败；要把结果归类为“本地 UI 已可用，但 live 观测尚未接通”。
+22. 如果 OpenClaw 自己因为外部 provider 凭证缺失而无法产出实时数据，也不要误判为 control-center 安装失败；要单独归类为“控制中心已装好，但上游 OpenClaw 前置条件未满足”。
 
 第五阶段：交付可启动结果
-20. 如果验证通过，输出：
+23. 如果验证通过，输出：
    - 你实际修改了哪些 env 值
    - 最终 `.env` 中哪些值沿用了默认值
    - 我下一步启动 UI 的准确命令
@@ -224,6 +236,7 @@ cp .env.example .env
    - 哪些能力现在已经可用
    - 哪些能力因为当前机器没有相关数据源而处于降级状态
    - 如果我以后补上订阅 / Codex / Gateway，只需要补哪几个 env 或前置条件
+   - 如果当前缺的是 provider API key / 外部凭证 / 上游 OpenClaw 进程，请把它们列为“控制中心外部前置条件”
 
 最后请用这个格式给我结果：
 - 环境检查

docs/PROGRESS.md

@@ -1,5 +1,22 @@
 # Progress
 
+## Phase 146 (README install prompt hardened for mixed OpenClaw environments) — Completed
+- Scope:
+  - Make the public install mega prompt more robust across different OpenClaw environments, provider models, and machine setups.
+  - Keep the control-center setup path strict about safe defaults while distinguishing hard blockers from allowed degraded installs.
+- Changed files:
+  - `README.md`
+  - `README.en.md`
+  - `docs/PROGRESS.md`
+- Implementation:
+  - Expanded the README setup prompt to cover provider API-key/OpenRouter/Anthropic-style environments in addition to Codex/GPT subscription-backed ones.
+  - Added explicit checks for `node`, `npm`, repo write access, npm-registry reachability, multiple candidate OpenClaw homes, and multiple Gateway candidates.
+  - Made the prompt forbid fabricating provider secrets and require reporting upstream OpenClaw/provider prerequisites separately from control-center install success.
+  - Clarified which missing inputs are hard blockers versus degraded-but-acceptable control-center installs.
+- Verification:
+  - `npm run build`
+  - `npm run release:audit`
+
 ## Phase 144 (README visuals sanitized for public promotion) — Completed
 - Scope:
   - Remove real operational content from the public README visuals before promotion.