diff --git a/INSTALL_PROMPT.en.md b/INSTALL_PROMPT.en.md new file mode 100644 index 0000000..b8f5fbc --- /dev/null +++ b/INSTALL_PROMPT.en.md @@ -0,0 +1,101 @@ +# OpenClaw Control Center Install Prompt + +Language: [中文](INSTALL_PROMPT.md) | **English** + +Give the full prompt below to your own OpenClaw so it can install and connect `OpenClaw Control Center` to this machine's OpenClaw environment. + +```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. 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 +12. 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 +13. Only change these when the machine actually requires it: + - GATEWAY_URL + - OPENCLAW_HOME + - CODEX_HOME + - OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH + - UI_PORT +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 +19. Run: + - npm run build + - npm test + - npm run smoke:ui +20. If any step fails, stop and tell me: + - which step failed + - why it failed + - what I should do next +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 +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 + - 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 +``` diff --git a/INSTALL_PROMPT.md b/INSTALL_PROMPT.md new file mode 100644 index 0000000..2cee81c --- /dev/null +++ b/INSTALL_PROMPT.md @@ -0,0 +1,101 @@ +# OpenClaw Control Center 安装 Prompt + +默认语言：**中文** | [English](INSTALL_PROMPT.en.md) + +把下面整段原样交给你自己的 OpenClaw，让它帮你把 `OpenClaw Control Center` 安装并接到这台机器自己的 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. 确认这台机器上有哪些前提是真正存在的，哪些是缺失但允许降级的。至少分别判断： + - `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，并明确说明可信度下降。 + +第二阶段：安装项目 +9. 确认当前目录是 control-center 仓库根目录。 +10. 运行依赖安装。 +11. 如果 `.env` 不存在，就从 `.env.example` 创建；如果存在，就在保留安全默认值的前提下修正它。不要删除用户已有的无关安全配置，只改这次接线真正需要的项。 + +第三阶段：配置安全首次接入 +12. 保持这些值： + - 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 +13. 只有在本机环境确实不同的时候，才修改： + - GATEWAY_URL + - OPENCLAW_HOME + - CODEX_HOME + - OPENCLAW_SUBSCRIPTION_SNAPSHOT_PATH + - UI_PORT +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。 + +第四阶段：验证安装 +19. 运行： + - npm run build + - npm test + - npm run smoke:ui +20. 如果有任何一步失败，停止并告诉我： + - 哪一步失败了 + - 原因是什么 + - 我下一步该怎么修 +21. 如果 build / test / smoke 通过，但 live Gateway 仍不可达，也不要把这次接入判定为失败；要把结果归类为“本地 UI 已可用，但 live 观测尚未接通”。 +22. 如果 OpenClaw 自己因为外部 provider 凭证缺失而无法产出实时数据，也不要误判为 control-center 安装失败；要单独归类为“控制中心已装好，但上游 OpenClaw 前置条件未满足”。 + +第五阶段：交付可启动结果 +23. 如果验证通过，输出： + - 你实际修改了哪些 env 值 + - 最终 `.env` 中哪些值沿用了默认值 + - 我下一步启动 UI 的准确命令 + - 我应该先打开的 3 个页面 + - 哪些信号如果为空，属于“正常但未接线完全” + - 哪些能力现在已经可用 + - 哪些能力因为当前机器没有相关数据源而处于降级状态 + - 如果我以后补上订阅 / Codex / Gateway，只需要补哪几个 env 或前置条件 + - 如果当前缺的是 provider API key / 外部凭证 / 上游 OpenClaw 进程，请把它们列为“控制中心外部前置条件” + +最后请用这个格式给我结果： +- 环境检查 +- 差异与降级判断 +- 实际修改 +- 验证结果 +- 下一步命令 +- 首次打开页面 +``` diff --git a/README.en.md b/README.en.md index f220ef8..80ff6a5 100644 --- a/README.en.md +++ b/README.en.md @@ -145,6 +145,10 @@ cp .env.example .env ### 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 installation prompt 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 diff --git a/README.md b/README.md index 200b5b2..d976996 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,10 @@ cp .env.example .env ### 3. 默认推荐：让你自己的 OpenClaw 直接完成安装与接线 最推荐的接入方式，不是你手动一项项配，而是直接把下面这段 mega prompt 交给你自己的 OpenClaw。 +如果你想直接复制独立文件，用这个： +- [INSTALL_PROMPT.md](INSTALL_PROMPT.md) +- [INSTALL_PROMPT.en.md](INSTALL_PROMPT.en.md) + 它应该一次性帮你做完这些事： - 检查本机 OpenClaw / Gateway / 路径 - 安装依赖 diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index ebc95f8..e1eefc3 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -1,5 +1,23 @@ # Progress +## Phase 147 (Standalone install prompt files added) — Completed +- Scope: + - Make the public install prompt easier to copy without forcing users to extract it from the README. + - Keep Chinese as the default public path while preserving a matching English version. +- Changed files: + - `INSTALL_PROMPT.md` + - `INSTALL_PROMPT.en.md` + - `README.md` + - `README.en.md` + - `docs/PROGRESS.md` +- Implementation: + - Added standalone install prompt files in Chinese and English. + - Linked both README files to the standalone prompt files right before the embedded mega prompt. + - Kept the same environment-coverage rules, safety defaults, and handoff format in the extracted files. +- Verification: + - `npm run build` + - `npm run release:audit` + ## 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.