From 97122bb8c5966cf92acb8104e1a852b71b911441 Mon Sep 17 00:00:00 2001 From: thepagent Date: Sun, 5 Apr 2026 08:24:42 +0800 Subject: [PATCH 1/3] docs: add last_validated frontmatter to 9 docs Closes #385 #384 #383 #382 #380 #379 #378 #377 #376 --- docs/acp_kiro.md | 5 +++++ docs/acpx-harness.md | 5 +++++ docs/binding_telegram.md | 5 +++++ docs/cli.md | 5 +++++ docs/install.md | 5 +++++ docs/linux_systemd.md | 5 +++++ docs/nodes.md | 5 +++++ docs/openclaw-auto-update.md | 5 +++++ docs/pricing_howto.md | 5 +++++ 9 files changed, 45 insertions(+) diff --git a/docs/acp_kiro.md b/docs/acp_kiro.md index 592429b..33efe4d 100644 --- a/docs/acp_kiro.md +++ b/docs/acp_kiro.md @@ -1,3 +1,8 @@ +--- +last_validated: 2026-04-05 +validated_by: thepagent +--- + # OpenClaw × ACP × Kiro 整合指南 讓你的 OpenClaw 透過 ACP 轉接 Kiro，實現對話持久化。 diff --git a/docs/acpx-harness.md b/docs/acpx-harness.md index a8e9dba..ef05602 100644 --- a/docs/acpx-harness.md +++ b/docs/acpx-harness.md @@ -1,3 +1,8 @@ +--- +last_validated: 2026-04-05 +validated_by: thepagent +--- + # ACPX Harness ## ACPX Harness 是什麼 diff --git a/docs/binding_telegram.md b/docs/binding_telegram.md index f0c2bd2..021f6ba 100644 --- a/docs/binding_telegram.md +++ b/docs/binding_telegram.md @@ -1,3 +1,8 @@ +--- +last_validated: 2026-04-05 +validated_by: thepagent +--- + # Telegram Binding 指南 openclaw 的 `bindings` 設定支援兩種 Telegram 綁定模式： diff --git a/docs/cli.md b/docs/cli.md index c04e363..b113418 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,3 +1,8 @@ +--- +last_validated: 2026-04-05 +validated_by: thepagent +--- + # CLI Quick Reference（指令速查） > 目標：把最常用的 OpenClaw 指令整理成「抄得到就能用」的速查表。 diff --git a/docs/install.md b/docs/install.md index 090c4d2..8443ef3 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,3 +1,8 @@ +--- +last_validated: 2026-04-05 +validated_by: thepagent +--- + # Install（安裝） > 目標：用最少步驟把 OpenClaw 安裝好，並避免常見的 PATH / 權限 / Node 版本坑。 diff --git a/docs/linux_systemd.md b/docs/linux_systemd.md index 0488c99..5ff4d61 100644 --- a/docs/linux_systemd.md +++ b/docs/linux_systemd.md @@ -1,3 +1,8 @@ +--- +last_validated: 2026-04-05 +validated_by: thepagent +--- + # Linux（systemd）上的 OpenClaw Gateway：重啟、Port 衝突與 Model 設定踩坑 ## TL;DR diff --git a/docs/nodes.md b/docs/nodes.md index 302fae6..cbc6990 100644 --- a/docs/nodes.md +++ b/docs/nodes.md @@ -1,3 +1,8 @@ +--- +last_validated: 2026-04-05 +validated_by: thepagent +--- + # OpenClaw Nodes 深度解析 ## 概述 diff --git a/docs/openclaw-auto-update.md b/docs/openclaw-auto-update.md index 69484d7..e770abf 100644 --- a/docs/openclaw-auto-update.md +++ b/docs/openclaw-auto-update.md @@ -1,3 +1,8 @@ +--- +last_validated: 2026-04-05 +validated_by: thepagent +--- + # OpenClaw 自動更新流程 使用 openclaw cron、Telegram 與 kiro-cli 實現自動版本檢查與更新。 diff --git a/docs/pricing_howto.md b/docs/pricing_howto.md index df3f5b6..a69c80c 100644 --- a/docs/pricing_howto.md +++ b/docs/pricing_howto.md @@ -1,3 +1,8 @@ +--- +last_validated: 2026-04-05 +validated_by: thepagent +--- + # How to Configure Model Pricing in OpenClaw OpenClaw doesn't include a built-in pricing database. Instead, you configure costs in your config file to match your actual provider expenses. From 0566b45514dbcd58bae8e78aadfd11681857a058 Mon Sep 17 00:00:00 2001 From: thepagent Date: Sun, 5 Apr 2026 08:35:27 +0800 Subject: [PATCH 2/3] docs: update 5 docs against upstream openclaw/openclaw MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - install.md: Node >= 20 → Node 22.14+ required, Node 24 recommended - cli.md: add missing CLI commands (acp, mcp, flows, dashboard, backup, etc.) - binding_telegram.md: add dmPolicy section and security boundary notes - acpx-harness.md: add openclaw acp vs acpx distinction, CLI backends fallback - acp_kiro.md: add CLI backends fallback, fix acpx-harness link --- docs/acp_kiro.md | 34 ++++++++++++++++- docs/acpx-harness.md | 41 +++++++++++++++++++++ docs/binding_telegram.md | 28 ++++++++++++++ docs/cli.md | 79 ++++++++++++++++++++++++++++++---------- docs/install.md | 12 +++--- 5 files changed, 169 insertions(+), 25 deletions(-) diff --git a/docs/acp_kiro.md b/docs/acp_kiro.md index 33efe4d..81afab6 100644 --- a/docs/acp_kiro.md +++ b/docs/acp_kiro.md @@ -253,4 +253,36 @@ openclaw hooks list # 確認 ✓ ready - [OpenClaw × ACP × Codex 整合指南](./acp_codex.md) - [OpenClaw × ACP × Gemini 整合指南](./acp_gemini.md) -- [ACPX Harness 架構與演進史](../acpx-harness.md) +- [ACPX Harness 架構與演進史](./acpx-harness.md) + +--- + +## 補充：`openclaw acp` vs ACP Agents（ACPX Harness） + +本指南描述的是 **ACP Agents** 路線（OpenClaw → 啟動 Kiro CLI 執行任務）。 + +另一個容易混淆的概念是 `openclaw acp`，方向相反： + +| | `openclaw acp` | 本指南（ACP Agents） | +|---|---|---| +| 方向 | IDE → OpenClaw | OpenClaw → Kiro CLI | +| 用途 | IDE 透過 ACP 連接 Gateway | OpenClaw 委派任務給 Kiro | +| 工具 | 無（純 bridge） | Kiro 原生工具（file edit、bash 等） | + +## 補充：CLI Backends（text-only fallback） + +若只需要 text-only 的安全網（API 掛掉時的 fallback），不需要完整 ACP harness，可用 CLI backends： + +```json5 +{ + agents: { + defaults: { + cliBackends: { + "kiro-cli": { command: "/opt/homebrew/bin/kiro-cli" } + } + } + } +} +``` + +CLI backends 停用所有工具，僅做 text in → text out，適合作為 provider 故障時的降級方案。詳見 [ACPX Harness](./acpx-harness.md#cli-backends)。 diff --git a/docs/acpx-harness.md b/docs/acpx-harness.md index ef05602..e38c816 100644 --- a/docs/acpx-harness.md +++ b/docs/acpx-harness.md @@ -11,6 +11,47 @@ ACPX（ACP eXternal）Harness 是 OpenClaw ACP（Agent Communication Protocol） --- +## `openclaw acp` vs ACPX Harness（ACP Agents） + +OpenClaw 有兩個容易混淆的 ACP 概念： + +| | `openclaw acp` | ACPX Harness（ACP Agents） | +|---|---|---| +| 方向 | 外部 IDE/client → OpenClaw | OpenClaw → 外部 CLI | +| 用途 | IDE 透過 ACP 連接 OpenClaw Gateway | OpenClaw 啟動 Codex/Claude/Gemini 執行任務 | +| 指令 | `openclaw acp` | `/acp spawn`、binding `type: "acp"` | +| 工具 | 無（純 bridge） | 外部 CLI 原生工具 | + +簡單記法： +- **editor 想連 OpenClaw** → `openclaw acp` +- **OpenClaw 想用外部 CLI** → ACPX Harness + +## CLI Backends（text-only fallback） + +OpenClaw 也支援 **CLI backends** 作為 API provider 掛掉時的 text-only 安全網： + +```json5 +{ + agents: { + defaults: { + cliBackends: { + "claude-cli": { command: "/opt/homebrew/bin/claude" }, + "codex-cli": { command: "/opt/homebrew/bin/codex" }, + } + } + } +} +``` + +- 工具完全停用（text in → text out） +- 支援 session 和圖片傳遞 +- 不需要額外 API key（用 CLI 自身的認證） +- 設計為安全網，非主要路徑 + +> CLI backends ≠ ACP。若需要完整的 harness runtime（工具呼叫、thread binding、persistent session），用 ACPX Harness。 + +--- + ## 它解決了什麼痛點 ### 問題背景 diff --git a/docs/binding_telegram.md b/docs/binding_telegram.md index 021f6ba..c62f3c2 100644 --- a/docs/binding_telegram.md +++ b/docs/binding_telegram.md @@ -5,6 +5,34 @@ validated_by: thepagent # Telegram Binding 指南 +## DM 存取政策（dmPolicy） + +`channels.telegram.dmPolicy` 控制私訊存取模式（`2026.2.25+`）： + +| dmPolicy | 說明 | +|----------|------| +| `pairing`（預設） | 新使用者需透過 pairing code 配對後才能 DM | +| `allowlist` | 僅允許 `allowFrom` 中列出的 numeric Telegram user ID | +| `open` | 任何人都可以 DM（需 `allowFrom: ["*"]`） | +| `disabled` | 完全關閉 DM | + +```json5 +{ + channels: { + telegram: { + dmPolicy: "pairing", + allowFrom: [], // numeric Telegram user IDs + } + } +} +``` + +> ⚠️ **安全邊界（`2026.2.25+`）**：DM pairing 授權不會繼承到群組。Pairing 僅授予 DM 存取權。群組授權需透過 `groupAllowFrom` 或 per-group `allowFrom` 明確設定。 +> +> 若希望「配對一次就能同時使用 DM 和群組」，請將你的 numeric Telegram user ID 加入 `channels.telegram.allowFrom`。 + +--- + openclaw 的 `bindings` 設定支援兩種 Telegram 綁定模式： | 模式 | 說明 | `match` 欄位 | diff --git a/docs/cli.md b/docs/cli.md index b113418..e1b213c 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -38,58 +38,99 @@ openclaw onboard --install-daemon --- -## 3) Sessions / Subagents +## 3) Sessions / Agents -（以下命令視你的版本可能略有差異；以實際 help 為準） +```bash +openclaw sessions list +openclaw sessions history +openclaw agent --message "hi" +openclaw agents list +``` -- 列出 sessions -- 查某個 session 歷史 -- 對某個 session 發訊息 +--- -> 在 chat 介面中，多數情境你會直接用 agent 的內建工具 `sessions_list / sessions_history / sessions_send`。 +## 4) ACP / MCP ---- +```bash +openclaw acp # 啟動 ACP bridge（IDE 連 OpenClaw） +openclaw mcp serve # 啟動 MCP server（外部 MCP client 連 OpenClaw） +``` -## 4) Cron（排程） +> `openclaw acp` 是 Gateway-backed ACP bridge，不是 ACP harness。 +> 若要讓 OpenClaw 啟動外部 CLI（Codex/Claude/Gemini），用 ACP Agents（`/acp spawn`）。 + +--- -> 你也可以直接在 chat 用 `cron` tool 建立/管理。 +## 5) Cron / Flows / Tasks -概念： -- list：看有哪些 job -- add：新增 job -- run：立即觸發 -- runs：看執行紀錄 +```bash +openclaw cron list +openclaw cron add +openclaw cron run +openclaw cron runs +openclaw flows list # ClawFlow 工作流 +openclaw tasks list # 任務管理 +``` --- -## 5) Nodes +## 6) Nodes / Devices ```bash openclaw nodes status +openclaw nodes describe --node +openclaw devices list +openclaw devices approve ``` （配對流程與能力請看 `docs/nodes.md`） --- -## 6) 常用除錯 +## 7) 管理工具 + +```bash +openclaw doctor # 診斷 + 修復 +openclaw dashboard # Web dashboard +openclaw backup # 備份設定 +openclaw models list # 模型清單 +openclaw memory search # 記憶搜尋 +openclaw plugins list # 插件管理 +openclaw secrets list # Secrets 管理 +openclaw skills list # Skills 管理 +openclaw pairing list # 配對管理 +openclaw channels list # Channel 管理 +openclaw approvals list # 審批管理 +openclaw sandbox status # Sandbox 狀態 +openclaw browser # 瀏覽器工具 +openclaw hooks list # Hook 管理 +openclaw webhooks list # Webhook 管理 +openclaw logs # 查看日誌 +openclaw system info # 系統資訊 +``` + +--- + +## 8) 常用除錯 ```bash openclaw status +openclaw health openclaw gateway status +openclaw doctor --fix ``` --- -## 7) 常見工作流（例） +## 9) 常見工作流（例） -### 7.1 「我想確認 bot 還活著」 +### 9.1 「我想確認 bot 還活著」 ```bash openclaw gateway status ``` -### 7.2 「我想重啟所有東西」 +### 9.2 「我想重啟所有東西」 ```bash openclaw gateway restart diff --git a/docs/install.md b/docs/install.md index 8443ef3..5f8456b 100644 --- a/docs/install.md +++ b/docs/install.md @@ -14,8 +14,8 @@ validated_by: thepagent ## TL;DR ```bash -# 1) 安裝 Node.js（建議用 nvm 或 Volta 管） -node -v +# 1) 安裝 Node.js 24（建議用 nvm 或 Volta 管） +node -v # 需 v22.14+ 或 v24+ npm -v # 2) 安裝 OpenClaw CLI @@ -32,10 +32,12 @@ openclaw gateway status ## 1) 先決條件 -- Node.js LTS（建議 >= 20） +- **Node.js 22.14+**（必要），**Node 24 推薦**（安裝腳本、CI、release workflow 的預設版本） - npm - 可連外下載套件（公司網路可能要 proxy） +> ⚠️ Node 20 已不再支援。若 `node -v` 顯示 v20 或更舊，請先升級。 + ### 建議：不要用系統自帶 node 系統自帶 node 常常太舊，或權限/路徑容易混亂。 @@ -58,8 +60,8 @@ brew install node ```bash curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash -nvm install --lts -nvm use --lts +nvm install 24 +nvm use 24 ``` ### 2.2 安裝 OpenClaw From b43a65ecbedbc13bb6986a6b2c70fdee5228ba86 Mon Sep 17 00:00:00 2001 From: thepagent Date: Sun, 5 Apr 2026 08:41:34 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20fix=20acpx-harness=20link=20in=20ac?= =?UTF-8?q?p=5Fgemini.md=20(../=E2=86=92./)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/acp_gemini.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/acp_gemini.md b/docs/acp_gemini.md index a3a2f9a..66c0641 100644 --- a/docs/acp_gemini.md +++ b/docs/acp_gemini.md @@ -223,4 +223,4 @@ $ACPX --agent "gemini --experimental-acp" sessions new --name my-gemini-tg - [OpenClaw × ACP × Kiro 整合指南](./acp_kiro.md) - [OpenClaw × ACP × Codex 整合指南](./acp_codex.md) -- [ACPX Harness 架構與演進史](../acpx-harness.md) +- [ACPX Harness 架構與演進史](./acpx-harness.md)