chore(i18n): refresh zh-TW translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
c42af3619c
commit
f7c6432fa2
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 你遇到連線/驗證問題，並想要取得引導式修復
|
||||
- 你遇到連線/身分驗證問題，並想要引導式修正
|
||||
- 你已更新並想要進行合理性檢查
|
||||
summary: '`openclaw doctor` 的 CLI 參考（健康檢查 + 引導式修復）'
|
||||
title: 診斷
|
||||
summary: CLI 參考：`openclaw doctor`（健全性檢查 + 引導式修復）
|
||||
title: 診斷工具
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T02:53:37Z"
|
||||
generated_at: "2026-04-30T20:05:27Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 9985c84d23861dd9468a4659ee00519573fe6d540c436548da0a68067dbabc4c
|
||||
source_hash: 265d82a10da086cf89687886e491be018a720b70021e0b26bd8f39b25a907e14
|
||||
source_path: cli/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -35,38 +35,39 @@ openclaw doctor --generate-gateway-token
|
||||
## 選項
|
||||
|
||||
- `--no-workspace-suggestions`：停用工作區記憶體/搜尋建議
|
||||
- `--yes`：不提示即接受預設值
|
||||
- `--repair`：不提示即套用建議的修復
|
||||
- `--yes`：不提示並接受預設值
|
||||
- `--repair`：不提示並套用建議的修復
|
||||
- `--fix`：`--repair` 的別名
|
||||
- `--force`：套用積極修復，包括在需要時覆寫自訂服務設定
|
||||
- `--non-interactive`：不顯示提示執行；僅進行安全遷移
|
||||
- `--generate-gateway-token`：產生並設定 Gateway token
|
||||
- `--deep`：掃描系統服務中的額外 Gateway 安裝
|
||||
- `--force`：套用積極修復，必要時包括覆寫自訂服務設定
|
||||
- `--non-interactive`：不顯示提示執行；僅執行安全遷移
|
||||
- `--generate-gateway-token`：產生並設定 Gateway 權杖
|
||||
- `--deep`：掃描系統服務以尋找額外的 Gateway 安裝
|
||||
|
||||
注意事項：
|
||||
|
||||
- 互動式提示（例如 keychain/OAuth 修復）只會在 stdin 是 TTY 且**未**設定 `--non-interactive` 時執行。無頭執行（cron、Telegram、沒有終端機）會略過提示。
|
||||
- 效能：非互動式 `doctor` 執行會略過急切 Plugin 載入，讓無頭健康檢查保持快速。互動式工作階段在檢查需要 Plugin 貢獻時，仍會完整載入 Plugin。
|
||||
- `--fix`（`--repair` 的別名）會將備份寫入 `~/.openclaw/openclaw.json.bak`，並移除未知設定鍵，同時列出每項移除項目。
|
||||
- 狀態完整性檢查現在會偵測 sessions 目錄中的孤立 transcript 檔案。將其封存為 `.deleted.<timestamp>` 需要互動式確認；`--fix`、`--yes` 和無頭執行會將其保留在原位。
|
||||
- Doctor 也會掃描 `~/.openclaw/cron/jobs.json`（或 `cron.store`）中的舊版 cron job 形狀，並可在 scheduler 必須於執行階段自動正規化之前就地重寫。
|
||||
- Doctor 會修復缺少的內建 Plugin 執行階段依賴項，而不寫入已封裝的全域安裝。對於 root 擁有的 npm 安裝或加固的 systemd unit，請將 `OPENCLAW_PLUGIN_STAGE_DIR` 設為可寫入目錄，例如 `/var/lib/openclaw/plugin-runtime-deps`；它也可以是路徑清單，例如 `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`，其中較前面的根目錄是唯讀查找層，最後一個根目錄是修復目標。
|
||||
- Doctor 會透過從 `plugins.allow`/`plugins.entries` 移除遺失的 Plugin ID，以及在 Plugin 探索健康時移除相符的懸空通道設定、Heartbeat 目標和通道模型覆寫，來修復過期的 Plugin 設定。
|
||||
- Doctor 會隔離無效的 Plugin 設定，方法是停用受影響的 `plugins.entries.<id>` 項目，並移除其無效的 `config` payload。Gateway 啟動時已經只會略過該壞掉的 Plugin，因此其他 Plugin 與通道可以繼續執行。
|
||||
- 互動式提示（例如 keychain/OAuth 修復）只會在 stdin 是 TTY 且**未**設定 `--non-interactive` 時執行。無頭執行（cron、Telegram、無終端機）會略過提示。
|
||||
- 效能：非互動式 `doctor` 執行會略過預先載入 Plugin，讓無頭健康檢查保持快速。互動式工作階段仍會在檢查需要 Plugin 貢獻時完整載入 Plugin。
|
||||
- `--fix`（`--repair` 的別名）會將備份寫入 `~/.openclaw/openclaw.json.bak`，並移除未知設定鍵，同時列出每一項移除。
|
||||
- 狀態完整性檢查現在會偵測 sessions 目錄中的孤立 transcript 檔案。將它們封存為 `.deleted.<timestamp>` 需要互動式確認；`--fix`、`--yes` 與無頭執行會將它們保留在原處。
|
||||
- Doctor 也會掃描 `~/.openclaw/cron/jobs.json`（或 `cron.store`）中的舊版 cron 工作形狀，並可在排程器必須於執行階段自動正規化之前就地重寫。
|
||||
- Doctor 會修復缺少的內建 Plugin 執行階段依賴項目，而不會寫入封裝的全域安裝。對於 root 擁有的 npm 安裝或加固的 systemd 單元，請將 `OPENCLAW_PLUGIN_STAGE_DIR` 設為可寫入目錄，例如 `/var/lib/openclaw/plugin-runtime-deps`；它也可以是路徑清單，例如 `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`，其中較前面的根目錄是唯讀查找層，最後一個根目錄是修復目標。
|
||||
- Doctor 會透過從 `plugins.allow`/`plugins.entries` 移除缺少的 Plugin id，以及相符的懸空通道設定、Heartbeat 目標和通道模型覆寫，來修復過期的 Plugin 設定，前提是 Plugin 探索狀態正常。
|
||||
- Doctor 會隔離無效的 Plugin 設定，方法是停用受影響的 `plugins.entries.<id>` 項目，並移除其無效的 `config` 酬載。Gateway 啟動時已經只會略過該不良 Plugin，因此其他 Plugin 和通道可繼續執行。
|
||||
- 當另一個 supervisor 擁有 Gateway 生命週期時，請設定 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。Doctor 仍會回報 Gateway/服務健康狀態並套用非服務修復，但會略過服務安裝/啟動/重新啟動/bootstrap 和舊版服務清理。
|
||||
- 在 Linux 上，doctor 會忽略非使用中的額外類 Gateway systemd unit，且在修復期間不會為正在執行的 systemd Gateway 服務重寫 command/entrypoint metadata。當你有意替換作用中的 launcher 時，請先停止服務，或使用 `openclaw gateway install --force`。
|
||||
- 在 Linux 上，doctor 會忽略未啟用的額外類 Gateway systemd 單元，且不會在修復期間為執行中的 systemd Gateway 服務重寫命令/進入點中繼資料。當你有意替換作用中的啟動器時，請先停止服務或使用 `openclaw gateway install --force`。
|
||||
- Doctor 會將舊版扁平 Talk 設定（`talk.voiceId`、`talk.modelId` 及相關項目）自動遷移至 `talk.provider` + `talk.providers.<provider>`。
|
||||
- 重複執行 `doctor --fix` 時，如果唯一差異是物件鍵順序，將不再回報/套用 Talk 正規化。
|
||||
- Doctor 包含記憶體搜尋就緒狀態檢查，並可在缺少 embedding credentials 時建議 `openclaw configure --section model`。
|
||||
- Doctor 會在未設定命令擁有者時發出警告。命令擁有者是允許執行僅限擁有者命令並核准危險動作的人類操作者帳號。DM pairing 只允許某人與 bot 對話；如果你在 first-owner bootstrap 存在前核准過寄件者，請明確設定 `commands.ownerAllowFrom`。
|
||||
- 如果已啟用 sandbox mode 但 Docker 不可用，doctor 會回報高訊號警告並提供修復方式（`install Docker` 或 `openclaw config set agents.defaults.sandbox.mode off`）。
|
||||
- 如果 `gateway.auth.token`/`gateway.auth.password` 由 SecretRef 管理，且在目前命令路徑中不可用，doctor 會回報唯讀警告，且不會寫入明文 fallback credentials。
|
||||
- 如果通道 SecretRef 檢查在修復路徑中失敗，doctor 會繼續並回報警告，而不是提前結束。
|
||||
- Telegram `allowFrom` 使用者名稱自動解析（`doctor --fix`）需要目前命令路徑中有可解析的 Telegram token。如果 token 檢查不可用，doctor 會回報警告，並在該次執行略過自動解析。
|
||||
- Doctor 包含記憶體搜尋就緒檢查，並可在缺少嵌入憑證時建議 `openclaw configure --section model`。
|
||||
- Doctor 會在未設定命令擁有者時發出警告。命令擁有者是允許執行僅限擁有者命令並核准危險動作的人類操作員帳號。DM 配對只允許某人與機器人交談；如果你在首次擁有者 bootstrap 存在之前核准過寄件者，請明確設定 `commands.ownerAllowFrom`。
|
||||
- Doctor 會在已設定 Codex 模式代理程式，且操作員的 Codex home 中存在個人 Codex CLI 資產時發出警告。本機 Codex app-server 啟動會使用隔離的個別代理程式 home，因此請使用 `openclaw migrate codex --dry-run` 盤點應該刻意提升的資產。
|
||||
- 如果已啟用沙箱模式但 Docker 不可用，doctor 會回報高訊號警告並提供補救方式（`install Docker` 或 `openclaw config set agents.defaults.sandbox.mode off`）。
|
||||
- 如果 `gateway.auth.token`/`gateway.auth.password` 由 SecretRef 管理，且在目前命令路徑中不可用，doctor 會回報唯讀警告，且不會寫入純文字後援憑證。
|
||||
- 如果通道 SecretRef 檢查在修復路徑中失敗，doctor 會繼續並回報警告，而不是提早結束。
|
||||
- Telegram `allowFrom` 使用者名稱自動解析（`doctor --fix`）需要目前命令路徑中有可解析的 Telegram 權杖。如果權杖檢查不可用，doctor 會回報警告，並略過該次執行的自動解析。
|
||||
|
||||
## macOS：`launchctl` env 覆寫
|
||||
## macOS：`launchctl` 環境變數覆寫
|
||||
|
||||
如果你先前執行過 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），該值會覆寫你的設定檔，並可能導致持續的「未授權」錯誤。
|
||||
如果你先前執行過 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），該值會覆寫你的設定檔，並可能造成持續的「未授權」錯誤。
|
||||
|
||||
```bash
|
||||
launchctl getenv OPENCLAW_GATEWAY_TOKEN
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想從 Hermes 或其他代理系統遷移到 OpenClaw
|
||||
- 你正在新增由 Plugin 擁有的遷移提供者
|
||||
- 你正在新增一個由 Plugin 擁有的遷移提供者
|
||||
summary: '`openclaw migrate` 的 CLI 參考（從另一個代理系統匯入狀態）'
|
||||
title: 遷移
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T02:54:47Z"
|
||||
generated_at: "2026-04-30T20:05:27Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d3db14c16b8f9dcbf86a4f12558cf4e8555aa9a255637034fb804148996a225e
|
||||
source_hash: ffcd9e874bdaa0a5195e712d4fccd7b3d53034cb362c7f7462e9c7df72477b1a
|
||||
source_path: cli/migrate.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw migrate`
|
||||
|
||||
透過 Plugin 所擁有的遷移提供者，從另一個代理系統匯入狀態。內建提供者涵蓋 [Claude](/zh-TW/install/migrating-claude) 和 [Hermes](/zh-TW/install/migrating-hermes)；第三方插件可以註冊其他提供者。
|
||||
透過 Plugin 擁有的遷移提供者，從另一個代理系統匯入狀態。內建提供者涵蓋 Codex CLI 狀態、[Claude](/zh-TW/install/migrating-claude) 和 [Hermes](/zh-TW/install/migrating-hermes)；第三方 Plugin 可以註冊其他提供者。
|
||||
|
||||
<Tip>
|
||||
如需面向使用者的逐步說明，請參閱[從 Claude 遷移](/zh-TW/install/migrating-claude)和[從 Hermes 遷移](/zh-TW/install/migrating-hermes)。[遷移中心](/zh-TW/install/migrating)列出所有路徑。
|
||||
如需面向使用者的逐步指南，請參閱[從 Claude 遷移](/zh-TW/install/migrating-claude)和[從 Hermes 遷移](/zh-TW/install/migrating-hermes)。[遷移中心](/zh-TW/install/migrating)會列出所有路徑。
|
||||
</Tip>
|
||||
|
||||
## 命令
|
||||
@ -26,8 +26,12 @@ x-i18n:
|
||||
```bash
|
||||
openclaw migrate list
|
||||
openclaw migrate claude --dry-run
|
||||
openclaw migrate codex --dry-run
|
||||
openclaw migrate codex --skill gog-vault77-google-workspace
|
||||
openclaw migrate hermes --dry-run
|
||||
openclaw migrate hermes
|
||||
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
|
||||
openclaw migrate apply codex --yes
|
||||
openclaw migrate apply claude --yes
|
||||
openclaw migrate apply hermes --yes
|
||||
openclaw migrate apply hermes --include-secrets --yes
|
||||
@ -40,28 +44,31 @@ openclaw onboard --import-from hermes --import-source ~/.hermes
|
||||
已註冊遷移提供者的名稱，例如 `hermes`。執行 `openclaw migrate list` 以查看已安裝的提供者。
|
||||
</ParamField>
|
||||
<ParamField path="--dry-run" type="boolean">
|
||||
建立計畫後結束，不變更狀態。
|
||||
建立計畫並離開，不變更狀態。
|
||||
</ParamField>
|
||||
<ParamField path="--from <path>" type="string">
|
||||
覆寫來源狀態目錄。Hermes 預設為 `~/.hermes`。
|
||||
</ParamField>
|
||||
<ParamField path="--include-secrets" type="boolean">
|
||||
匯入支援的憑證。預設為關閉。
|
||||
匯入支援的憑證。預設關閉。
|
||||
</ParamField>
|
||||
<ParamField path="--overwrite" type="boolean">
|
||||
當計畫回報衝突時，允許套用取代現有目標。
|
||||
當計畫回報衝突時，允許套用作業取代既有目標。
|
||||
</ParamField>
|
||||
<ParamField path="--yes" type="boolean">
|
||||
略過確認提示。在非互動模式中必填。
|
||||
略過確認提示。非互動模式中必填。
|
||||
</ParamField>
|
||||
<ParamField path="--skill <name>" type="string">
|
||||
依 Skills 名稱或項目 id 選取一個 Skills 複製項目。重複此旗標可遷移多個 Skills。省略時，互動式 Codex 遷移會顯示核取方塊選擇器，非互動式遷移會保留所有規劃中的 Skills。
|
||||
</ParamField>
|
||||
<ParamField path="--no-backup" type="boolean">
|
||||
略過套用前備份。當本機 OpenClaw 狀態存在時，需要搭配 `--force`。
|
||||
</ParamField>
|
||||
<ParamField path="--force" type="boolean">
|
||||
當套用原本會拒絕略過備份時，必須與 `--no-backup` 一起使用。
|
||||
當套用作業原本會拒絕略過備份時，必須與 `--no-backup` 一起使用。
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
以 JSON 列印計畫或套用結果。使用 `--json` 且未使用 `--yes` 時，套用會列印計畫且不變更狀態。
|
||||
以 JSON 列印計畫或套用結果。使用 `--json` 且未使用 `--yes` 時，套用作業會列印計畫且不變更狀態。
|
||||
</ParamField>
|
||||
|
||||
## 安全模型
|
||||
@ -69,66 +76,88 @@ openclaw onboard --import-from hermes --import-source ~/.hermes
|
||||
`openclaw migrate` 以預覽優先。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Preview before apply">
|
||||
在任何變更發生前，提供者會傳回逐項列出的計畫，其中包含衝突、略過的項目和敏感項目。JSON 計畫、套用輸出和遷移報告會遮蔽巢狀且看似祕密的鍵，例如 API 金鑰、權杖、授權標頭、Cookie 和密碼。
|
||||
<Accordion title="套用前預覽">
|
||||
提供者會在任何變更發生前回傳逐項計畫，包含衝突、略過項目和敏感項目。JSON 計畫、套用輸出和遷移報告會遮蔽巢狀且看似祕密的金鑰，例如 API keys、tokens、authorization headers、cookies 和 passwords。
|
||||
|
||||
`openclaw migrate apply <provider>` 會先預覽計畫，並在變更狀態前提示，除非已設定 `--yes`。在非互動模式中，套用需要 `--yes`。
|
||||
`openclaw migrate apply <provider>` 會預覽計畫，並在變更狀態前提示確認，除非已設定 `--yes`。在非互動模式中，套用作業需要 `--yes`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Backups">
|
||||
套用會在套用遷移前建立並驗證 OpenClaw 備份。如果尚未存在本機 OpenClaw 狀態，則會略過備份步驟，遷移可以繼續。若要在狀態存在時略過備份，請同時傳入 `--no-backup` 和 `--force`。
|
||||
<Accordion title="備份">
|
||||
套用作業會在套用遷移前建立並驗證 OpenClaw 備份。如果尚無本機 OpenClaw 狀態，備份步驟會略過，且遷移可繼續。若要在狀態存在時略過備份，請同時傳入 `--no-backup` 和 `--force`。
|
||||
</Accordion>
|
||||
<Accordion title="Conflicts">
|
||||
當計畫有衝突時，套用會拒絕繼續。請檢閱計畫，若有意取代現有目標，再使用 `--overwrite` 重新執行。提供者仍可在遷移報告目錄中，為被覆寫的檔案寫入項目層級備份。
|
||||
<Accordion title="衝突">
|
||||
當計畫有衝突時，套用作業會拒絕繼續。請檢閱計畫，若確定要取代既有目標，再以 `--overwrite` 重新執行。提供者仍可在遷移報告目錄中，為被覆寫的檔案寫入項目層級備份。
|
||||
</Accordion>
|
||||
<Accordion title="Secrets">
|
||||
預設永遠不會匯入祕密。使用 `--include-secrets` 匯入支援的憑證。
|
||||
<Accordion title="祕密">
|
||||
預設永遠不會匯入祕密。使用 `--include-secrets` 以匯入支援的憑證。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Claude 提供者
|
||||
|
||||
內建 Claude 提供者預設會偵測 `~/.claude` 的 Claude Code 狀態。使用 `--from <path>` 匯入特定 Claude Code 主目錄或專案根目錄。
|
||||
內建 Claude 提供者預設會在 `~/.claude` 偵測 Claude Code 狀態。使用 `--from <path>` 可匯入特定 Claude Code 主目錄或專案根目錄。
|
||||
|
||||
<Tip>
|
||||
如需面向使用者的逐步說明，請參閱[從 Claude 遷移](/zh-TW/install/migrating-claude)。
|
||||
如需面向使用者的逐步指南，請參閱[從 Claude 遷移](/zh-TW/install/migrating-claude)。
|
||||
</Tip>
|
||||
|
||||
### Claude 會匯入什麼
|
||||
### Claude 會匯入的內容
|
||||
|
||||
- 將專案 `CLAUDE.md` 和 `.claude/CLAUDE.md` 匯入 OpenClaw 代理工作區。
|
||||
- 將使用者的 `~/.claude/CLAUDE.md` 附加到工作區 `USER.md`。
|
||||
- 將使用者 `~/.claude/CLAUDE.md` 附加到工作區 `USER.md`。
|
||||
- 從專案 `.mcp.json`、Claude Code `~/.claude.json` 和 Claude Desktop `claude_desktop_config.json` 匯入 MCP 伺服器定義。
|
||||
- 包含 `SKILL.md` 的 Claude skill 目錄。
|
||||
- 將 Claude 命令 Markdown 檔案轉換為僅能手動叫用的 OpenClaw skills。
|
||||
- 包含 `SKILL.md` 的 Claude Skills 目錄。
|
||||
- 將 Claude 命令 Markdown 檔案轉換為僅可手動叫用的 OpenClaw Skills。
|
||||
|
||||
### 封存和手動檢閱狀態
|
||||
### 封存與需手動檢閱的狀態
|
||||
|
||||
Claude 掛鉤、權限、環境預設值、本機記憶、路徑範圍規則、子代理、快取、計畫和專案歷史會保留在遷移報告中，或回報為手動檢閱項目。OpenClaw 不會自動執行掛鉤、複製廣泛允許清單，或匯入 OAuth/Desktop 憑證狀態。
|
||||
Claude hooks、permissions、environment defaults、local memory、path-scoped rules、subagents、caches、plans 和 project history 會保留在遷移報告中，或回報為需手動檢閱的項目。OpenClaw 不會自動執行 hooks、複製廣泛 allowlists，或匯入 OAuth/Desktop 憑證狀態。
|
||||
|
||||
## Codex 提供者
|
||||
|
||||
內建 Codex 提供者預設會在 `~/.codex` 偵測 Codex CLI 狀態，或在設定該環境變數時，於 `CODEX_HOME` 偵測。使用 `--from <path>` 可盤點特定 Codex 主目錄。
|
||||
|
||||
當你要移至 OpenClaw Codex harness，並想有意識地提升有用的個人 Codex CLI 資產時，請使用此提供者。本機 Codex app-server 啟動會使用每個代理各自的 `CODEX_HOME` 和 `HOME` 目錄，因此預設不會讀取你的個人 Codex CLI 狀態。
|
||||
|
||||
在互動式終端機中執行 `openclaw migrate codex` 會預覽完整計畫，接著在最終套用確認前，為 Skills 複製項目開啟核取方塊選擇器。所有 Skills 一開始都會被選取；取消勾選你不想複製到此代理的任何 Skills。若要用於腳本或精確執行，請針對每個 Skills 傳入一次 `--skill <name>`，例如：
|
||||
|
||||
```bash
|
||||
openclaw migrate codex --dry-run --skill gog-vault77-google-workspace
|
||||
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
|
||||
```
|
||||
|
||||
### Codex 會匯入的內容
|
||||
|
||||
- `$CODEX_HOME/skills` 底下的 Codex CLI Skills 目錄，不包含 Codex 的 `.system` 快取。
|
||||
- `$HOME/.agents/skills` 底下的個人 AgentSkills，當你希望由每個代理擁有時，會複製到目前的 OpenClaw 代理工作區。
|
||||
|
||||
### 需手動檢閱的 Codex 狀態
|
||||
|
||||
Codex 原生 Plugin、`config.toml` 和原生 `hooks/hooks.json` 不會自動啟用。Plugin 可能會公開 MCP 伺服器、apps、hooks 或其他可執行行為，因此提供者會將它們回報以供檢閱，而不是載入 OpenClaw。Config 和 hook 檔案會複製到遷移報告中以供手動檢閱。
|
||||
|
||||
## Hermes 提供者
|
||||
|
||||
內建 Hermes 提供者預設會偵測 `~/.hermes` 的狀態。當 Hermes 位於其他位置時，請使用 `--from <path>`。
|
||||
內建 Hermes 提供者預設會在 `~/.hermes` 偵測狀態。當 Hermes 位於其他位置時，請使用 `--from <path>`。
|
||||
|
||||
### Hermes 會匯入什麼
|
||||
### Hermes 會匯入的內容
|
||||
|
||||
- 從 `config.yaml` 匯入預設模型設定。
|
||||
- 從 `providers` 和 `custom_providers` 匯入已設定的模型提供者和自訂 OpenAI 相容端點。
|
||||
- 從 `mcp_servers` 或 `mcp.servers` 匯入 MCP 伺服器定義。
|
||||
- 來自 `config.yaml` 的預設模型設定。
|
||||
- 來自 `providers` 和 `custom_providers` 的已設定模型提供者與自訂 OpenAI 相容端點。
|
||||
- 來自 `mcp_servers` 或 `mcp.servers` 的 MCP 伺服器定義。
|
||||
- 將 `SOUL.md` 和 `AGENTS.md` 匯入 OpenClaw 代理工作區。
|
||||
- 將 `memories/MEMORY.md` 和 `memories/USER.md` 附加到工作區記憶檔案。
|
||||
- OpenClaw 檔案記憶的記憶設定預設值，以及外部記憶提供者（例如 Honcho）的封存或手動檢閱項目。
|
||||
- OpenClaw 檔案記憶體的記憶體設定預設值，以及 Honcho 等外部記憶體提供者的封存或需手動檢閱項目。
|
||||
- `skills/<name>/` 底下包含 `SKILL.md` 檔案的 Skills。
|
||||
- 從 `skills.config` 匯入每個 skill 的設定值。
|
||||
- 從 `.env` 匯入支援的 API 金鑰，僅在使用 `--include-secrets` 時。
|
||||
- 來自 `skills.config` 的每個 Skills 設定值。
|
||||
- 來自 `.env` 的受支援 API keys，僅在使用 `--include-secrets` 時匯入。
|
||||
|
||||
### 支援的 `.env` 鍵
|
||||
### 支援的 `.env` 金鑰
|
||||
|
||||
`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENROUTER_API_KEY`、`GOOGLE_API_KEY`、`GEMINI_API_KEY`、`GROQ_API_KEY`、`XAI_API_KEY`、`MISTRAL_API_KEY`、`DEEPSEEK_API_KEY`。
|
||||
`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`.
|
||||
|
||||
### 僅封存狀態
|
||||
### 僅封存的狀態
|
||||
|
||||
OpenClaw 無法安全解讀的 Hermes 狀態會複製到遷移報告以供手動檢閱，但不會載入即時 OpenClaw 設定或憑證。這會保留不透明或不安全的狀態，而不假裝 OpenClaw 可以自動執行或信任它：
|
||||
OpenClaw 無法安全解譯的 Hermes 狀態會複製到遷移報告中以供手動檢閱，但不會載入即時 OpenClaw 設定或憑證。這會保留不透明或不安全的狀態，而不假裝 OpenClaw 能自動執行或信任它：
|
||||
|
||||
- `plugins/`
|
||||
- `sessions/`
|
||||
@ -138,7 +167,7 @@ OpenClaw 無法安全解讀的 Hermes 狀態會複製到遷移報告以供手動
|
||||
- `auth.json`
|
||||
- `state.db`
|
||||
|
||||
### 套用之後
|
||||
### 套用後
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
@ -146,7 +175,7 @@ openclaw doctor
|
||||
|
||||
## Plugin 合約
|
||||
|
||||
遷移來源是插件。插件會在 `openclaw.plugin.json` 中宣告其提供者 ID：
|
||||
遷移來源是 Plugin。Plugin 會在 `openclaw.plugin.json` 中宣告其提供者 id：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -156,22 +185,22 @@ openclaw doctor
|
||||
}
|
||||
```
|
||||
|
||||
執行階段中，Plugin 會呼叫 `api.registerMigrationProvider(...)`。提供者會實作 `detect`、`plan` 和 `apply`。核心負責 CLI 編排、備份政策、提示、JSON 輸出和衝突預檢。核心會將已檢閱的計畫傳入 `apply(ctx, plan)`，而提供者只有在為了相容性且該引數不存在時，才可以重建計畫。
|
||||
執行時，Plugin 會呼叫 `api.registerMigrationProvider(...)`。提供者會實作 `detect`、`plan` 和 `apply`。Core 擁有 CLI 編排、備份政策、提示、JSON 輸出和衝突預檢。Core 會將已檢閱的計畫傳入 `apply(ctx, plan)`，而提供者只能在為了相容性且該引數不存在時重建計畫。
|
||||
|
||||
提供者插件可以使用 `openclaw/plugin-sdk/migration` 來建構項目和彙總計數，並使用 `openclaw/plugin-sdk/migration-runtime` 來進行可感知衝突的檔案複製、僅封存的報告複製、快取設定執行階段包裝器，以及遷移報告。
|
||||
Provider Plugin 可以使用 `openclaw/plugin-sdk/migration` 進行項目建構與摘要計數，並使用 `openclaw/plugin-sdk/migration-runtime` 進行可感知衝突的檔案複製、僅封存報告複製、快取的 config-runtime wrappers，以及遷移報告。
|
||||
|
||||
## Onboarding 整合
|
||||
|
||||
當提供者偵測到已知來源時，Onboarding 可以提供遷移。`openclaw onboard --flow import` 和 `openclaw setup --wizard --import-from hermes` 都使用相同的插件遷移提供者，並且仍會在套用前顯示預覽。
|
||||
當提供者偵測到已知來源時，Onboarding 可以提供遷移。`openclaw onboard --flow import` 和 `openclaw setup --wizard --import-from hermes` 都會使用相同的 Plugin 遷移提供者，並且仍會在套用前顯示預覽。
|
||||
|
||||
<Note>
|
||||
Onboarding 匯入需要全新的 OpenClaw 設定。如果你已經有本機狀態，請先重設設定、憑證、工作階段和工作區。對於現有設定，備份加覆寫或合併匯入功能受功能旗標控管。
|
||||
Onboarding 匯入需要全新的 OpenClaw 設定。如果你已經有本機狀態，請先重設設定、憑證、工作階段和工作區。備份加覆寫或合併匯入，對既有設定仍受功能旗標控管。
|
||||
</Note>
|
||||
|
||||
## 相關
|
||||
|
||||
- [從 Hermes 遷移](/zh-TW/install/migrating-hermes)：面向使用者的逐步說明。
|
||||
- [從 Claude 遷移](/zh-TW/install/migrating-claude)：面向使用者的逐步說明。
|
||||
- [從 Hermes 遷移](/zh-TW/install/migrating-hermes)：面向使用者的逐步指南。
|
||||
- [從 Claude 遷移](/zh-TW/install/migrating-claude)：面向使用者的逐步指南。
|
||||
- [遷移](/zh-TW/install/migrating)：將 OpenClaw 移至新機器。
|
||||
- [Doctor](/zh-TW/gateway/doctor)：套用遷移後的健康檢查。
|
||||
- [插件](/zh-TW/tools/plugin)：插件安裝和註冊。
|
||||
- [Plugin](/zh-TW/tools/plugin)：Plugin 安裝與註冊。
|
||||
|
||||
@ -1,27 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要說明代理程式工作區或其檔案配置
|
||||
- 你想要備份或遷移代理程式工作區
|
||||
- 你需要說明代理工作區或其檔案配置
|
||||
- 您想要備份或遷移代理程式工作區
|
||||
sidebarTitle: Agent workspace
|
||||
summary: 代理工作區：位置、結構與備份策略
|
||||
title: 代理程式工作區
|
||||
summary: 代理工作區：位置、版面配置與備份策略
|
||||
title: 代理工作區
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T02:58:14Z"
|
||||
generated_at: "2026-04-30T20:05:24Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 35d59d1f0dec05db30f9166a43bfa519d7299b08d093bbeb905d8f83e5cd022a
|
||||
source_hash: b1ccf74cbec3ff20f4c1c1ce52f099a7ca3365b2536b0aad6ff1d3a5fafcca0a
|
||||
source_path: concepts/agent-workspace.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
工作區是代理的家。它是檔案工具和工作區內容脈絡唯一使用的工作目錄。請保持私密，並將其視為記憶。
|
||||
工作區是代理程式的家。它是檔案工具與工作區內容使用的唯一工作目錄。請保持其私密，並將它視為記憶。
|
||||
|
||||
這與 `~/.openclaw/` 不同，後者用來儲存設定、憑證和工作階段。
|
||||
這與 `~/.openclaw/` 分開，後者儲存設定、憑證與工作階段。
|
||||
|
||||
<Warning>
|
||||
工作區是**預設 cwd**，不是嚴格的沙箱。工具會以工作區解析相對路徑，但除非啟用沙箱，否則絕對路徑仍可存取主機上的其他位置。如果你需要隔離，請使用 [`agents.defaults.sandbox`](/zh-TW/gateway/sandboxing)（以及／或個別代理沙箱設定）。
|
||||
工作區是**預設 cwd**，不是硬性沙箱。工具會依工作區解析相對路徑，但除非已啟用沙箱，否則絕對路徑仍可存取主機上的其他位置。如果你需要隔離，請使用 [`agents.defaults.sandbox`](/zh-TW/gateway/sandboxing)（及/或個別代理程式的沙箱設定）。
|
||||
|
||||
啟用沙箱且 `workspaceAccess` 不是 `"rw"` 時，工具會在 `~/.openclaw/sandboxes` 底下的沙箱工作區內運作，而不是你的主機工作區。
|
||||
啟用沙箱且 `workspaceAccess` 不是 `"rw"` 時，工具會在 `~/.openclaw/sandboxes` 底下的沙箱工作區內運作，而不是在你的主機工作區內。
|
||||
</Warning>
|
||||
|
||||
## 預設位置
|
||||
@ -40,10 +40,10 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
如果工作區和啟動檔案不存在，`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 會建立工作區並植入啟動檔案。
|
||||
如果缺少工作區與啟動檔案，`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 會建立工作區並植入這些檔案。
|
||||
|
||||
<Note>
|
||||
沙箱種子複製只接受工作區內的一般檔案；解析到來源工作區外部的符號連結／硬連結別名會被忽略。
|
||||
沙箱種子複本只接受工作區內的一般檔案；解析到來源工作區外部的符號連結/硬連結別名會被忽略。
|
||||
</Note>
|
||||
|
||||
如果你已經自行管理工作區檔案，可以停用啟動檔案建立：
|
||||
@ -54,82 +54,83 @@ x-i18n:
|
||||
|
||||
## 額外工作區資料夾
|
||||
|
||||
較舊的安裝可能建立過 `~/openclaw`。保留多個工作區目錄可能造成令人困惑的驗證或狀態漂移，因為一次只有一個工作區是作用中的。
|
||||
較舊的安裝可能建立了 `~/openclaw`。保留多個工作區目錄可能造成令人困惑的驗證或狀態偏移，因為一次只有一個工作區是作用中的。
|
||||
|
||||
<Note>
|
||||
**建議：** 保留單一作用中工作區。如果你不再使用額外資料夾，請封存或移到垃圾桶（例如 `trash ~/openclaw`）。如果你刻意保留多個工作區，請確保 `agents.defaults.workspace` 指向作用中的那一個。
|
||||
**建議：**保留單一作用中工作區。如果你不再使用額外資料夾，請封存或移到垃圾桶（例如 `trash ~/openclaw`）。如果你刻意保留多個工作區，請確保 `agents.defaults.workspace` 指向作用中的那一個。
|
||||
|
||||
`openclaw doctor` 偵測到額外工作區目錄時會發出警告。
|
||||
`openclaw doctor` 偵測到額外工作區目錄時會提出警告。
|
||||
</Note>
|
||||
|
||||
## 工作區檔案對照表
|
||||
## 工作區檔案對照
|
||||
|
||||
以下是 OpenClaw 預期工作區內具備的標準檔案：
|
||||
以下是 OpenClaw 預期在工作區內存在的標準檔案：
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="AGENTS.md — operating instructions">
|
||||
代理的操作指示，以及它應如何使用記憶。每個工作階段開始時載入。適合放置規則、優先順序和「行為方式」細節。
|
||||
<Accordion title="AGENTS.md — 操作指示">
|
||||
代理程式的操作指示，以及它應如何使用記憶。每個工作階段開始時載入。適合放置規則、優先順序，以及「如何表現」的細節。
|
||||
</Accordion>
|
||||
<Accordion title="SOUL.md — persona and tone">
|
||||
人格、語氣和界線。每個工作階段載入。指南：[SOUL.md 人格指南](/zh-TW/concepts/soul)。
|
||||
<Accordion title="SOUL.md — 人格與語氣">
|
||||
人格、語氣與界線。每個工作階段都會載入。指南：[SOUL.md personality guide](/zh-TW/concepts/soul)。
|
||||
</Accordion>
|
||||
<Accordion title="USER.md — who the user is">
|
||||
使用者是誰，以及應如何稱呼他們。每個工作階段載入。
|
||||
<Accordion title="USER.md — 使用者是誰">
|
||||
使用者是誰，以及如何稱呼他們。每個工作階段都會載入。
|
||||
</Accordion>
|
||||
<Accordion title="IDENTITY.md — name, vibe, emoji">
|
||||
代理的名稱、氛圍和 emoji。在啟動儀式期間建立／更新。
|
||||
<Accordion title="IDENTITY.md — 名稱、氛圍、表情符號">
|
||||
代理程式的名稱、氛圍與表情符號。於啟動儀式期間建立/更新。
|
||||
</Accordion>
|
||||
<Accordion title="TOOLS.md — local tool conventions">
|
||||
關於你的本機工具和慣例的註記。不控制工具可用性；它只是指引。
|
||||
<Accordion title="TOOLS.md — 本機工具慣例">
|
||||
關於你的本機工具與慣例的備註。不控制工具可用性；僅作為指引。
|
||||
</Accordion>
|
||||
<Accordion title="HEARTBEAT.md — heartbeat checklist">
|
||||
Heartbeat 執行用的選用小型檢查清單。保持簡短以避免消耗 token。
|
||||
<Accordion title="HEARTBEAT.md — Heartbeat 檢查清單">
|
||||
Heartbeat 執行用的選用極簡檢查清單。請保持簡短以避免消耗 token。
|
||||
</Accordion>
|
||||
<Accordion title="BOOT.md — startup checklist">
|
||||
Gateway 重新啟動時自動執行的選用啟動檢查清單（啟用[內部 hooks](/zh-TW/automation/hooks) 時）。保持簡短；對外傳送請使用訊息工具。
|
||||
<Accordion title="BOOT.md — 啟動檢查清單">
|
||||
Gateway 重新啟動時自動執行的選用啟動檢查清單（啟用[內部 hook](/zh-TW/automation/hooks) 時）。請保持簡短；對外傳送請使用訊息工具。
|
||||
</Accordion>
|
||||
<Accordion title="BOOTSTRAP.md — first-run ritual">
|
||||
一次性的首次執行儀式。只會為全新工作區建立。儀式完成後請刪除。
|
||||
<Accordion title="BOOTSTRAP.md — 首次執行儀式">
|
||||
一次性的首次執行儀式。僅為全新工作區建立。儀式完成後請刪除它。
|
||||
</Accordion>
|
||||
<Accordion title="memory/YYYY-MM-DD.md — daily memory log">
|
||||
每日記憶記錄（每天一個檔案）。建議在工作階段開始時讀取今天與昨天。
|
||||
<Accordion title="memory/YYYY-MM-DD.md — 每日記憶日誌">
|
||||
每日記憶日誌（每天一個檔案）。建議在工作階段開始時閱讀今天與昨天。
|
||||
</Accordion>
|
||||
<Accordion title="MEMORY.md — curated long-term memory (optional)">
|
||||
經整理的長期記憶。只在主要的私人工作階段載入（不要在共用／群組內容脈絡中載入）。請參閱[記憶](/zh-TW/concepts/memory)了解工作流程和自動記憶清理。
|
||||
<Accordion title="MEMORY.md — 精選長期記憶（選用）">
|
||||
精選長期記憶。僅在主要、私密工作階段中載入（不要在共享/群組情境中載入）。工作流程與自動記憶清除請參閱 [Memory](/zh-TW/concepts/memory)。
|
||||
</Accordion>
|
||||
<Accordion title="skills/ — workspace skills (optional)">
|
||||
工作區專屬 Skills。這是該工作區中優先順序最高的 skill 位置。名稱衝突時，會覆寫專案代理 Skills、個人代理 Skills、受管理 Skills、內建 Skills，以及 `skills.load.extraDirs`。
|
||||
<Accordion title="skills/ — 工作區 Skills（選用）">
|
||||
工作區專屬 Skills。該工作區中優先序最高的 skill 位置。名稱衝突時會覆寫專案代理程式 skills、個人代理程式 skills、受管理 skills、內建 skills，以及 `skills.load.extraDirs`。
|
||||
</Accordion>
|
||||
<Accordion title="canvas/ — Canvas UI files (optional)">
|
||||
<Accordion title="canvas/ — Canvas UI 檔案（選用）">
|
||||
節點顯示用的 Canvas UI 檔案（例如 `canvas/index.html`）。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
如果缺少任何啟動檔案，OpenClaw 會將「缺少檔案」標記注入工作階段並繼續。大型啟動檔案在注入時會被截斷；可用 `agents.defaults.bootstrapMaxChars`（預設：12000）和 `agents.defaults.bootstrapTotalMaxChars`（預設：60000）調整限制。`openclaw setup` 可以重新建立缺少的預設檔案，而不覆寫既有檔案。
|
||||
如果任何啟動檔案缺失，OpenClaw 會將「缺少檔案」標記注入工作階段並繼續。大型啟動檔案在注入時會被截斷；可使用 `agents.defaults.bootstrapMaxChars`（預設：12000）與 `agents.defaults.bootstrapTotalMaxChars`（預設：60000）調整限制。`openclaw setup` 可以重新建立缺失的預設檔案，而不覆寫現有檔案。
|
||||
</Note>
|
||||
|
||||
## 工作區內不包含什麼
|
||||
## 工作區中不包含什麼
|
||||
|
||||
這些位於 `~/.openclaw/` 底下，不應提交到工作區 repo：
|
||||
|
||||
- `~/.openclaw/openclaw.json`（設定）
|
||||
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（模型驗證設定檔：OAuth + API 金鑰）
|
||||
- `~/.openclaw/credentials/`（channel/provider 狀態，加上舊版 OAuth 匯入資料）
|
||||
- `~/.openclaw/agents/<agentId>/sessions/`（工作階段逐字稿 + 中繼資料）
|
||||
- `~/.openclaw/skills/`（受管理的 Skills）
|
||||
- `~/.openclaw/agents/<agentId>/agent/codex-home/`（個別代理程式的 Codex 執行階段帳戶、設定、skills、plugins 與原生 thread 狀態）
|
||||
- `~/.openclaw/credentials/`（頻道/提供者狀態，加上舊版 OAuth 匯入資料）
|
||||
- `~/.openclaw/agents/<agentId>/sessions/`（工作階段 transcript + metadata）
|
||||
- `~/.openclaw/skills/`（受管理 skills）
|
||||
|
||||
如果你需要遷移工作階段或設定，請分開複製，並讓它們留在版本控制之外。
|
||||
如果你需要移轉工作階段或設定，請分開複製它們，並讓它們保持在版本控制之外。
|
||||
|
||||
## Git 備份（建議，私人）
|
||||
## Git 備份（建議，私密）
|
||||
|
||||
將工作區視為私人記憶。把它放在**私人** git repo 中，讓它可備份且可復原。
|
||||
將工作區視為私密記憶。請把它放進**私密** git repo，以便備份與復原。
|
||||
|
||||
在 Gateway 執行所在的機器上執行以下步驟（工作區也位於該處）。
|
||||
在 Gateway 執行的機器上執行這些步驟（也就是工作區所在的位置）。
|
||||
|
||||
<Steps>
|
||||
<Step title="Initialize the repo">
|
||||
如果已安裝 git，全新的工作區會自動初始化。如果此工作區還不是 repo，請執行：
|
||||
<Step title="初始化 repo">
|
||||
如果已安裝 git，全新工作區會自動初始化。如果這個工作區還不是 repo，請執行：
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace
|
||||
@ -139,13 +140,13 @@ x-i18n:
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Add a private remote">
|
||||
<Step title="新增私密遠端">
|
||||
<Tabs>
|
||||
<Tab title="GitHub web UI">
|
||||
1. 在 GitHub 上建立新的**私人**儲存庫。
|
||||
2. 不要用 README 初始化（避免合併衝突）。
|
||||
<Tab title="GitHub 網頁 UI">
|
||||
1. 在 GitHub 上建立新的**私密** repository。
|
||||
2. 不要用 README 初始化（避免 merge conflicts）。
|
||||
3. 複製 HTTPS 遠端 URL。
|
||||
4. 加入遠端並推送：
|
||||
4. 新增遠端並推送：
|
||||
|
||||
```bash
|
||||
git branch -M main
|
||||
@ -159,11 +160,11 @@ x-i18n:
|
||||
gh repo create openclaw-workspace --private --source . --remote origin --push
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="GitLab web UI">
|
||||
1. 在 GitLab 上建立新的**私人**儲存庫。
|
||||
2. 不要用 README 初始化（避免合併衝突）。
|
||||
<Tab title="GitLab 網頁 UI">
|
||||
1. 在 GitLab 上建立新的**私密** repository。
|
||||
2. 不要用 README 初始化（避免 merge conflicts）。
|
||||
3. 複製 HTTPS 遠端 URL。
|
||||
4. 加入遠端並推送：
|
||||
4. 新增遠端並推送：
|
||||
|
||||
```bash
|
||||
git branch -M main
|
||||
@ -174,7 +175,7 @@ x-i18n:
|
||||
</Tabs>
|
||||
|
||||
</Step>
|
||||
<Step title="Ongoing updates">
|
||||
<Step title="持續更新">
|
||||
```bash
|
||||
git status
|
||||
git add .
|
||||
@ -187,13 +188,13 @@ x-i18n:
|
||||
## 不要提交秘密
|
||||
|
||||
<Warning>
|
||||
即使在私人 repo 中，也請避免將秘密儲存在工作區：
|
||||
即使在私密 repo 中，也請避免在工作區儲存秘密：
|
||||
|
||||
- API 金鑰、OAuth token、密碼或私人憑證。
|
||||
- API 金鑰、OAuth token、密碼或私密憑證。
|
||||
- `~/.openclaw/` 底下的任何內容。
|
||||
- 聊天或敏感附件的原始傾印。
|
||||
|
||||
如果你必須儲存敏感參照，請使用佔位符，並將真正的秘密保存在其他地方（密碼管理器、環境變數，或 `~/.openclaw/`）。
|
||||
如果必須儲存敏感參照，請使用 placeholders，並將真正的秘密保存在其他地方（密碼管理器、環境變數，或 `~/.openclaw/`）。
|
||||
</Warning>
|
||||
|
||||
建議的 `.gitignore` 起始內容：
|
||||
@ -209,28 +210,28 @@ x-i18n:
|
||||
## 將工作區移到新機器
|
||||
|
||||
<Steps>
|
||||
<Step title="Clone the repo">
|
||||
將 repo 複製到所需路徑（預設 `~/.openclaw/workspace`）。
|
||||
<Step title="Clone repo">
|
||||
將 repo clone 到所需路徑（預設為 `~/.openclaw/workspace`）。
|
||||
</Step>
|
||||
<Step title="Update config">
|
||||
<Step title="更新設定">
|
||||
在 `~/.openclaw/openclaw.json` 中將 `agents.defaults.workspace` 設為該路徑。
|
||||
</Step>
|
||||
<Step title="Seed missing files">
|
||||
執行 `openclaw setup --workspace <path>` 以植入任何缺少的檔案。
|
||||
<Step title="植入缺失檔案">
|
||||
執行 `openclaw setup --workspace <path>` 以植入任何缺失檔案。
|
||||
</Step>
|
||||
<Step title="Copy sessions (optional)">
|
||||
<Step title="複製工作階段（選用）">
|
||||
如果你需要工作階段，請從舊機器分開複製 `~/.openclaw/agents/<agentId>/sessions/`。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 進階註記
|
||||
## 進階備註
|
||||
|
||||
- 多代理路由可以為每個代理使用不同工作區。請參閱[Channel 路由](/zh-TW/channels/channel-routing)了解路由設定。
|
||||
- 如果啟用 `agents.defaults.sandbox`，非主要工作階段可使用 `agents.defaults.sandbox.workspaceRoot` 底下的個別工作階段沙箱工作區。
|
||||
- 多代理程式路由可以為每個代理程式使用不同工作區。路由設定請參閱[頻道路由](/zh-TW/channels/channel-routing)。
|
||||
- 如果已啟用 `agents.defaults.sandbox`，非主要工作階段可以使用 `agents.defaults.sandbox.workspaceRoot` 底下的個別工作階段沙箱工作區。
|
||||
|
||||
## 相關
|
||||
|
||||
- [Heartbeat](/zh-TW/gateway/heartbeat) — HEARTBEAT.md 工作區檔案
|
||||
- [沙箱](/zh-TW/gateway/sandboxing) — 沙箱環境中的工作區存取
|
||||
- [工作階段](/zh-TW/concepts/session) — 工作階段儲存路徑
|
||||
- [常設指令](/zh-TW/automation/standing-orders) — 工作區檔案中的持久化指示
|
||||
- [常駐指令](/zh-TW/automation/standing-orders) — 工作區檔案中的持久指示
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,144 +1,193 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想使用隨附的 Codex app-server 測試框架
|
||||
- 您想使用隨附的 Codex app-server 執行框架
|
||||
- 你需要 Codex 執行框架設定範例
|
||||
- 你希望僅限 Codex 的部署失敗，而不是回退到 PI
|
||||
summary: 透過隨附的 Codex app-server 測試框架執行 OpenClaw 嵌入式代理回合
|
||||
title: Codex 執行框架
|
||||
summary: 透過隨附的 Codex app-server 執行框架執行 OpenClaw 內嵌代理回合
|
||||
title: Codex 測試框架
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T03:23:11Z"
|
||||
generated_at: "2026-04-30T20:05:39Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 93abb72e9590aad265e5b6b8691dd16314178c4d255679b4e53da33b792a6e6b
|
||||
source_hash: 335ec60cbdb76579db833eccb5151ffc5bcd28b370ca2e99587abdb578eeee4f
|
||||
source_path: plugins/codex-harness.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
隨附的 `codex` Plugin 讓 OpenClaw 透過 Codex app-server 執行嵌入式代理回合，而不是使用內建 PI harness。
|
||||
隨附的 `codex` Plugin 可讓 OpenClaw 透過
|
||||
Codex app-server 執行內嵌代理回合，而不是使用內建 PI harness。
|
||||
|
||||
當你希望 Codex 擁有低階代理工作階段時使用此方式：模型探索、原生執行緒續接、原生 Compaction，以及 app-server 執行。OpenClaw 仍然擁有聊天頻道、工作階段檔案、模型選擇、工具、核准、媒體傳遞，以及可見的逐字稿鏡像。
|
||||
當你希望 Codex 擁有低階代理工作階段時，請使用這個 Plugin：模型
|
||||
探索、原生執行緒續接、原生 Compaction，以及 app-server 執行。
|
||||
OpenClaw 仍然負責聊天頻道、工作階段檔案、模型選擇、工具、
|
||||
核准、媒體傳送，以及可見的逐字稿鏡像。
|
||||
|
||||
如果你正在嘗試建立方向感，請從
|
||||
如果你正在嘗試定位概念，請從
|
||||
[代理執行環境](/zh-TW/concepts/agent-runtimes)開始。簡短版本是：
|
||||
`openai/gpt-5.5` 是模型參照，`codex` 是執行環境，而 Telegram、Discord、Slack 或其他頻道仍然是通訊介面。
|
||||
`openai/gpt-5.5` 是模型參照，`codex` 是執行環境，而 Telegram、
|
||||
Discord、Slack 或其他頻道仍然是通訊介面。
|
||||
|
||||
## 此 Plugin 會改變什麼
|
||||
## 這個 Plugin 會改變什麼
|
||||
|
||||
隨附的 `codex` Plugin 提供數個獨立能力：
|
||||
隨附的 `codex` Plugin 提供多個獨立能力：
|
||||
|
||||
| 能力 | 使用方式 | 它的作用 |
|
||||
| 能力 | 使用方式 | 作用 |
|
||||
| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| 原生嵌入式執行環境 | `agentRuntime.id: "codex"` | 透過 Codex app-server 執行 OpenClaw 嵌入式代理回合。 |
|
||||
| 原生聊天控制指令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 從訊息對話綁定並控制 Codex app-server 執行緒。 |
|
||||
| Codex app-server 提供者/目錄 | `codex` internals, surfaced through the harness | 讓執行環境探索並驗證 app-server 模型。 |
|
||||
| Codex 媒體理解路徑 | `codex/*` image-model compatibility paths | 針對支援的影像理解模型執行有界的 Codex app-server 回合。 |
|
||||
| 原生 hook relay | Plugin hooks around Codex-native events | 讓 OpenClaw 觀察/阻擋支援的 Codex 原生工具/完成事件。 |
|
||||
| 原生內嵌執行環境 | `agentRuntime.id: "codex"` | 透過 Codex app-server 執行 OpenClaw 內嵌代理回合。 |
|
||||
| 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 從訊息對話綁定並控制 Codex app-server 執行緒。 |
|
||||
| Codex app-server 提供者/目錄 | `codex` 內部機制，透過 harness 公開 | 讓執行環境探索並驗證 app-server 模型。 |
|
||||
| Codex 媒體理解路徑 | `codex/*` 影像模型相容性路徑 | 針對支援的影像理解模型執行有界限的 Codex app-server 回合。 |
|
||||
| 原生 hook 中繼 | Codex 原生事件周圍的 Plugin hooks | 讓 OpenClaw 觀察/阻擋支援的 Codex 原生工具/完成事件。 |
|
||||
|
||||
啟用 Plugin 會讓這些能力可用。它**不會**：
|
||||
啟用此 Plugin 會讓這些能力可用。它**不會**：
|
||||
|
||||
- 開始對每個 OpenAI 模型使用 Codex
|
||||
- 將 `openai-codex/*` 模型參照轉換為原生執行環境
|
||||
- 將 `openai-codex/*` 模型參照轉換成原生執行環境
|
||||
- 讓 ACP/acpx 成為預設 Codex 路徑
|
||||
- 熱切換已經記錄 PI 執行環境的既有工作階段
|
||||
- 取代 OpenClaw 頻道傳遞、工作階段檔案、auth-profile 儲存或訊息路由
|
||||
- 熱切換已經記錄 PI 執行環境的現有工作階段
|
||||
- 取代 OpenClaw 頻道傳送、工作階段檔案、驗證設定檔儲存或
|
||||
訊息路由
|
||||
|
||||
同一個 Plugin 也擁有原生 `/codex` 聊天控制指令介面。如果 Plugin 已啟用，且使用者要求從聊天中綁定、續接、導向、停止或檢查 Codex 執行緒，代理應優先使用 `/codex ...` 而不是 ACP。當使用者要求 ACP/acpx 或正在測試 ACP Codex 配接器時，ACP 仍是明確的備援。
|
||||
同一個 Plugin 也擁有原生 `/codex` 聊天控制命令介面。如果
|
||||
Plugin 已啟用，且使用者要求從聊天綁定、續接、引導、停止或檢查
|
||||
Codex 執行緒，代理應優先使用 `/codex ...` 而不是 ACP。當使用者要求
|
||||
ACP/acpx，或正在測試 ACP Codex 轉接器時，ACP 仍是明確的後援。
|
||||
|
||||
原生 Codex 回合會保留 OpenClaw Plugin hooks 作為公開相容層。這些是程序內 OpenClaw hooks，不是 Codex `hooks.json` 指令 hooks：
|
||||
原生 Codex 回合會保留 OpenClaw Plugin hooks 作為公開相容層。
|
||||
這些是處理程序內的 OpenClaw hooks，不是 Codex `hooks.json` 命令 hooks：
|
||||
|
||||
- `before_prompt_build`
|
||||
- `before_compaction`, `after_compaction`
|
||||
- `llm_input`, `llm_output`
|
||||
- `before_tool_call`, `after_tool_call`
|
||||
- `before_message_write` 用於鏡像逐字稿記錄
|
||||
- `before_agent_finalize` 透過 Codex `Stop` relay
|
||||
- 透過 Codex `Stop` 中繼的 `before_agent_finalize`
|
||||
- `agent_end`
|
||||
|
||||
Plugins 也可以註冊執行環境中立的工具結果中介軟體，以便在 OpenClaw 執行工具之後、結果回傳給 Codex 之前，改寫 OpenClaw 動態工具結果。這與公開的 `tool_result_persist` Plugin hook 分開，後者會轉換 OpenClaw 擁有的逐字稿工具結果寫入。
|
||||
Plugins 也可以註冊執行環境中立的工具結果中介軟體，在 OpenClaw
|
||||
執行工具之後、結果回傳給 Codex 之前，改寫 OpenClaw 動態工具結果。
|
||||
這不同於公開的 `tool_result_persist` Plugin hook，後者會轉換
|
||||
OpenClaw 擁有的逐字稿工具結果寫入。
|
||||
|
||||
如需 Plugin hook 語意本身，請參閱 [Plugin hooks](/zh-TW/plugins/hooks)
|
||||
與 [Plugin guard 行為](/zh-TW/tools/plugin)。
|
||||
與 [Plugin guard behavior](/zh-TW/tools/plugin)。
|
||||
|
||||
harness 預設關閉。新設定應將 OpenAI 模型參照維持為標準的 `openai/gpt-*`，並在需要原生 app-server 執行時，明確強制
|
||||
`agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。舊版 `codex/*` 模型參照仍會為了相容性自動選擇 harness，但由執行環境支援的舊版提供者前綴不會顯示為一般模型/提供者選項。
|
||||
harness 預設為關閉。新設定應將 OpenAI 模型參照維持為標準的
|
||||
`openai/gpt-*`，並在需要原生 app-server 執行時，明確強制使用
|
||||
`agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。舊版
|
||||
`codex/*` 模型參照仍會為了相容性自動選取 harness，但由執行環境支援的
|
||||
舊版提供者前綴不會顯示為一般模型/提供者選項。
|
||||
|
||||
如果 `codex` Plugin 已啟用，但主要模型仍是
|
||||
`openai-codex/*`，`openclaw doctor` 會發出警告，而不是變更路由。這是刻意的：`openai-codex/*` 仍然是 PI Codex OAuth/訂閱路徑，而原生 app-server 執行仍是明確的執行環境選擇。
|
||||
如果 `codex` Plugin 已啟用，但主要模型仍是 `openai-codex/*`，
|
||||
`openclaw doctor` 會發出警告，而不是變更路由。這是刻意設計：
|
||||
`openai-codex/*` 仍是 PI Codex OAuth/訂閱路徑，而原生 app-server
|
||||
執行仍是明確的執行環境選擇。
|
||||
|
||||
## 路由對照表
|
||||
|
||||
變更設定前請使用此表：
|
||||
|
||||
| 期望行為 | 模型參照 | 執行環境設定 | Plugin 需求 | 預期狀態標籤 |
|
||||
| ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ |
|
||||
| 透過一般 OpenClaw runner 使用 OpenAI API | `openai/gpt-*` | 省略或 `runtime: "pi"` | OpenAI 提供者 | `Runtime: OpenClaw Pi Default` |
|
||||
| 透過 PI 使用 Codex OAuth/訂閱 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth 提供者 | `Runtime: OpenClaw Pi Default` |
|
||||
| 原生 Codex app-server 嵌入式回合 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` Plugin | `Runtime: OpenAI Codex` |
|
||||
| 採保守自動模式的混合提供者 | 提供者特定參照 | `agentRuntime.id: "auto"` | 選用的 Plugin 執行環境 | 取決於所選執行環境 |
|
||||
| 明確的 Codex ACP 配接器工作階段 | 取決於 ACP prompt/model | `sessions_spawn` with `runtime: "acp"` | 健康的 `acpx` 後端 | ACP 任務/工作階段狀態 |
|
||||
| 期望行為 | 模型參照 | 執行環境設定 | Plugin 需求 | 預期狀態標籤 |
|
||||
| ------------------------------------------- | -------------------------- | -------------------------------------- | -------------------------- | ------------------------------ |
|
||||
| 透過一般 OpenClaw runner 使用 OpenAI API | `openai/gpt-*` | 省略或 `runtime: "pi"` | OpenAI 提供者 | `Runtime: OpenClaw Pi Default` |
|
||||
| 透過 PI 使用 Codex OAuth/訂閱 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth 提供者 | `Runtime: OpenClaw Pi Default` |
|
||||
| 原生 Codex app-server 內嵌回合 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` Plugin | `Runtime: OpenAI Codex` |
|
||||
| 使用保守自動模式的混合提供者 | 提供者特定參照 | `agentRuntime.id: "auto"` | 選用 Plugin 執行環境 | 取決於選定的執行環境 |
|
||||
| 明確的 Codex ACP 轉接器工作階段 | 依 ACP 提示/模型而定 | `sessions_spawn` 搭配 `runtime: "acp"` | 健康的 `acpx` 後端 | ACP 任務/工作階段狀態 |
|
||||
|
||||
重要分界是提供者與執行環境：
|
||||
重要的區分是提供者與執行環境：
|
||||
|
||||
- `openai-codex/*` 回答「PI 應使用哪個提供者/auth 路由？」
|
||||
- `agentRuntime.id: "codex"` 回答「哪個迴圈應執行這個嵌入式回合？」
|
||||
- `openai-codex/*` 回答「PI 應使用哪個提供者/驗證路由？」
|
||||
- `agentRuntime.id: "codex"` 回答「哪個迴圈應執行這個
|
||||
內嵌回合？」
|
||||
- `/codex ...` 回答「這個聊天應綁定或控制哪個原生 Codex 對話？」
|
||||
- ACP 回答「acpx 應啟動哪個外部 harness 程序？」
|
||||
|
||||
## 選擇正確的模型前綴
|
||||
|
||||
OpenAI 系列路由依前綴區分。當你想透過 PI 使用 Codex OAuth 時，請使用 `openai-codex/*`；當你想直接存取 OpenAI API，或正在強制使用原生 Codex app-server harness 時，請使用 `openai/*`：
|
||||
OpenAI 系列路由依前綴區分。當你想透過 PI 使用 Codex OAuth 時，請使用
|
||||
`openai-codex/*`；當你想直接存取 OpenAI API，或正在強制使用原生
|
||||
Codex app-server harness 時，請使用 `openai/*`：
|
||||
|
||||
| 模型參照 | 執行環境路徑 | 使用時機 |
|
||||
| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.4` | 透過 OpenClaw/PI plumbing 的 OpenAI 提供者 | 你想搭配 `OPENAI_API_KEY` 使用目前直接的 OpenAI Platform API 存取。 |
|
||||
| `openai-codex/gpt-5.5` | 透過 OpenClaw/PI 的 OpenAI Codex OAuth | 你想搭配預設 PI runner 使用 ChatGPT/Codex 訂閱 auth。 |
|
||||
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你想為嵌入式代理回合使用原生 Codex app-server 執行。 |
|
||||
| 模型參照 | 執行環境路徑 | 使用時機 |
|
||||
| --------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.4` | 透過 OpenClaw/PI 管線使用 OpenAI 提供者 | 你想使用目前以 `OPENAI_API_KEY` 直接存取的 OpenAI Platform API。 |
|
||||
| `openai-codex/gpt-5.5` | 透過 OpenClaw/PI 使用 OpenAI Codex OAuth | 你想以預設 PI runner 使用 ChatGPT/Codex 訂閱驗證。 |
|
||||
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你想為內嵌代理回合使用原生 Codex app-server 執行。 |
|
||||
|
||||
GPT-5.5 目前在 OpenClaw 中僅支援訂閱/OAuth。PI OAuth 請使用
|
||||
`openai-codex/gpt-5.5`，或搭配 Codex app-server harness 使用
|
||||
`openai/gpt-5.5`。一旦 OpenAI 在公開 API 啟用 GPT-5.5，就支援
|
||||
`openai/gpt-5.5` 的直接 API key 存取。
|
||||
`openai-codex/gpt-5.5`，或將 `openai/gpt-5.5` 搭配 Codex
|
||||
app-server harness 使用。一旦 OpenAI 在公開 API 上啟用 GPT-5.5，
|
||||
`openai/gpt-5.5` 的直接 API 金鑰存取即受支援。
|
||||
|
||||
舊版 `codex/gpt-*` 參照仍會作為相容別名被接受。Doctor 相容性遷移會將舊版主要執行環境參照改寫為標準模型參照，並另外記錄執行環境政策；而僅作為備援的舊版參照會保持不變，因為執行環境是為整個代理容器設定。新的 PI Codex OAuth 設定應使用 `openai-codex/gpt-*`；新的原生 app-server harness 設定應使用 `openai/gpt-*` 加上
|
||||
舊版 `codex/gpt-*` 參照仍作為相容別名被接受。Doctor 相容性遷移會將
|
||||
舊版主要執行環境參照改寫為標準模型參照，並分開記錄執行環境政策；
|
||||
而僅作為後援的舊版參照會保持不變，因為執行環境是針對整個代理容器設定。
|
||||
新的 PI Codex OAuth 設定應使用 `openai-codex/gpt-*`；新的原生
|
||||
app-server harness 設定應使用 `openai/gpt-*` 加上
|
||||
`agentRuntime.id: "codex"`。
|
||||
|
||||
`agents.defaults.imageModel` 遵循相同的前綴分界。當影像理解應透過 OpenAI Codex OAuth 提供者路徑執行時，請使用
|
||||
`openai-codex/gpt-*`。當影像理解應透過有界的 Codex app-server 回合執行時，請使用 `codex/gpt-*`。Codex app-server 模型必須宣告支援影像輸入；純文字 Codex 模型會在媒體回合開始前失敗。
|
||||
`agents.defaults.imageModel` 遵循相同的前綴區分。當影像理解應透過
|
||||
OpenAI Codex OAuth 提供者路徑執行時，請使用 `openai-codex/gpt-*`。
|
||||
當影像理解應透過有界限的 Codex app-server 回合執行時，請使用
|
||||
`codex/gpt-*`。Codex app-server 模型必須宣告支援影像輸入；純文字
|
||||
Codex 模型會在媒體回合開始前失敗。
|
||||
|
||||
使用 `/status` 確認目前工作階段的有效 harness。如果選擇出乎意料，請為 `agents/harness` 子系統啟用偵錯記錄，並檢查 Gateway 的結構化 `agent harness selected` 記錄。它包含所選 harness id、選擇原因、執行環境/備援政策，以及在 `auto` 模式下各 Plugin 候選項的支援結果。
|
||||
使用 `/status` 確認目前工作階段的有效 harness。如果選擇結果令人意外，
|
||||
請為 `agents/harness` 子系統啟用偵錯記錄，並檢查 Gateway 的結構化
|
||||
`agent harness selected` 記錄。它包含選定的 harness id、選擇原因、
|
||||
執行環境/後援政策，以及在 `auto` 模式中每個 Plugin 候選項目的支援結果。
|
||||
|
||||
### doctor 警告的意義
|
||||
### Doctor 警告代表什麼
|
||||
|
||||
當下列全部為真時，`openclaw doctor` 會發出警告：
|
||||
當以下條件全都成立時，`openclaw doctor` 會發出警告：
|
||||
|
||||
- 隨附的 `codex` Plugin 已啟用或被允許
|
||||
- 代理的主要模型是 `openai-codex/*`
|
||||
- 隨附的 `codex` Plugin 已啟用或允許
|
||||
- 某個代理的主要模型是 `openai-codex/*`
|
||||
- 該代理的有效執行環境不是 `codex`
|
||||
|
||||
這個警告存在，是因為使用者常預期「Codex Plugin 已啟用」就代表「原生 Codex app-server 執行環境」。OpenClaw 不會做這個跳躍。此警告表示：
|
||||
此警告存在，是因為使用者常預期「Codex Plugin 已啟用」代表
|
||||
「原生 Codex app-server 執行環境」。OpenClaw 不會做這個跳躍。
|
||||
此警告表示：
|
||||
|
||||
- 如果你原本就打算透過 PI 使用 ChatGPT/Codex OAuth，**不需要變更**。
|
||||
- 如果你原本打算使用原生 app-server 執行，請將模型改為 `openai/<model>` 並設定
|
||||
`agentRuntime.id: "codex"`。
|
||||
- 執行環境變更後，既有工作階段仍需要 `/new` 或 `/reset`，因為工作階段執行環境釘選具有黏性。
|
||||
- 如果你原本就打算透過 PI 使用 ChatGPT/Codex OAuth，則**不需要變更**。
|
||||
- 如果你原本打算使用原生 app-server 執行，請將模型變更為
|
||||
`openai/<model>`，並設定 `agentRuntime.id: "codex"`。
|
||||
- 執行環境變更後，現有工作階段仍需要 `/new` 或 `/reset`，
|
||||
因為工作階段執行環境釘選是黏著的。
|
||||
|
||||
harness 選擇不是即時工作階段控制。當嵌入式回合執行時，OpenClaw 會在該工作階段上記錄所選 harness id，並在同一工作階段 id 的後續回合持續使用它。當你希望未來工作階段使用另一個 harness 時，請變更 `agentRuntime` 設定或 `OPENCLAW_AGENT_RUNTIME`；在 PI 與 Codex 之間切換既有對話前，請使用 `/new` 或 `/reset` 開始新的工作階段。這可避免將同一份逐字稿透過兩套不相容的原生工作階段系統重播。
|
||||
harness 選擇不是即時工作階段控制。當內嵌回合執行時，OpenClaw
|
||||
會在該工作階段上記錄選定的 harness id，並在同一個工作階段 id 的後續回合繼續使用它。
|
||||
若希望未來工作階段使用其他 harness，請變更 `agentRuntime` 設定或
|
||||
`OPENCLAW_AGENT_RUNTIME`；在現有對話於 PI 與 Codex 之間切換前，請使用
|
||||
`/new` 或 `/reset` 啟動新的工作階段。這可避免透過兩套不相容的原生工作階段系統
|
||||
重播同一份逐字稿。
|
||||
|
||||
在 harness 釘選之前建立的舊版工作階段，一旦已有逐字稿歷史，就會被視為已釘選到 PI。變更設定後，請使用 `/new` 或 `/reset` 讓該對話改用 Codex。
|
||||
在 harness 釘選出現前建立的舊版工作階段，一旦已有逐字稿歷史，就會被視為
|
||||
PI 釘選。變更設定後，請使用 `/new` 或 `/reset` 將該對話改用 Codex。
|
||||
|
||||
`/status` 會顯示有效模型執行環境。預設 PI harness 會顯示為
|
||||
`Runtime: OpenClaw Pi Default`，而 Codex app-server harness 會顯示為
|
||||
`/status` 會顯示有效的模型執行環境。預設 PI harness 會顯示為
|
||||
`Runtime: OpenClaw Pi Default`，Codex app-server harness 會顯示為
|
||||
`Runtime: OpenAI Codex`。
|
||||
|
||||
## 需求
|
||||
|
||||
- OpenClaw 可使用隨附的 `codex` Plugin。
|
||||
- Codex app-server `0.125.0` 或更新版本。隨附的 Plugin 預設會管理相容的 Codex app-server 二進位檔，因此 `PATH` 上的本機 `codex` 指令不會影響一般 harness 啟動。
|
||||
- app-server 程序或 OpenClaw 的 Codex auth bridge 可取得 Codex auth。
|
||||
- Codex app-server `0.125.0` 或更新版本。隨附的 Plugin 預設會管理相容的
|
||||
Codex app-server 二進位檔，因此 `PATH` 上的本機 `codex` 命令不會影響
|
||||
一般 harness 啟動。
|
||||
- app-server 程序或 OpenClaw 的 Codex 驗證橋接器可使用 Codex 驗證。
|
||||
本機 stdio app-server 啟動會為每個代理使用 OpenClaw 管理的 Codex home，
|
||||
以及隔離的子程序 `HOME`，因此預設不會讀取你的個人
|
||||
`~/.codex` 帳號、Skills、Plugins、設定、執行緒狀態或原生
|
||||
`$HOME/.agents/skills`。
|
||||
|
||||
Plugin 會阻擋較舊或未版本化的 app-server handshake。這會讓 OpenClaw 維持在已測試過的協定介面上。
|
||||
此 Plugin 會阻擋較舊或無版本的 app-server 交握。這可讓 OpenClaw 維持在
|
||||
已測試過的協定介面上。
|
||||
|
||||
對於 live 與 Docker smoke tests，auth 通常來自 Codex CLI 帳號或 OpenClaw `openai-codex` auth profile。當沒有帳號時，本機 stdio app-server 啟動也可以退回使用 `CODEX_API_KEY` / `OPENAI_API_KEY`。
|
||||
對於即時與 Docker smoke tests，驗證通常來自 Codex CLI 帳號或 OpenClaw
|
||||
`openai-codex` 驗證設定檔。當沒有帳號存在時，本機 stdio app-server 啟動也可以後援使用
|
||||
`CODEX_API_KEY` / `OPENAI_API_KEY`。
|
||||
|
||||
## 最小設定
|
||||
|
||||
@ -179,22 +228,21 @@ Plugin 會阻擋較舊或未版本化的 app-server handshake。這會讓 OpenCl
|
||||
}
|
||||
```
|
||||
|
||||
將 `agents.defaults.model` 或代理模型設為 `codex/<model>` 的舊版設定，仍會自動啟用隨附的 `codex` Plugin。新設定應優先使用 `openai/<model>` 加上上方明確的 `agentRuntime` 項目。
|
||||
將 `agents.defaults.model` 或某個代理模型設定為 `codex/<model>` 的舊版設定，
|
||||
仍會自動啟用隨附的 `codex` Plugin。新設定應優先使用 `openai/<model>`，
|
||||
並加上上方明確的 `agentRuntime` 項目。
|
||||
|
||||
## 與其他模型並用 Codex
|
||||
## 與其他模型並列加入 Codex
|
||||
|
||||
如果同一個代理應可在 Codex 與非 Codex 提供者模型之間自由切換，請不要全域設定 `agentRuntime.id: "codex"`。強制執行環境會套用到該代理或工作階段的每個嵌入式回合。如果你在強制使用該執行環境時選擇 Anthropic 模型，OpenClaw 仍會嘗試 Codex harness，並封閉式失敗，而不是默默將該回合透過 PI 路由。
|
||||
如果同一個 agent 應該能在 Codex 與非 Codex 提供者模型之間自由切換，請不要全域設定 `agentRuntime.id: "codex"`。強制指定的 runtime 會套用到該 agent 或 session 的每一個嵌入式回合。如果你在強制使用該 runtime 時選擇 Anthropic 模型，OpenClaw 仍會嘗試 Codex harness，並以封閉方式失敗，而不是悄悄將該回合透過 Pi 路由。
|
||||
|
||||
改用以下其中一種形態：
|
||||
請改用下列其中一種形式：
|
||||
|
||||
- 將 Codex 放在使用 `agentRuntime.id: "codex"` 的專用代理程式上。
|
||||
- 將預設代理程式保留在 `agentRuntime.id: "auto"`，並使用 PI fallback 供一般混合
|
||||
提供者使用。
|
||||
- 僅為相容性使用舊版 `codex/*` 參照。新設定應偏好
|
||||
`openai/*` 加上明確的 Codex runtime policy。
|
||||
- 將 Codex 放在專用 agent 上，並設定 `agentRuntime.id: "codex"`。
|
||||
- 讓預設 agent 維持 `agentRuntime.id: "auto"`，並使用 Pi fallback 供一般混合提供者使用情境。
|
||||
- 只為相容性使用舊版 `codex/*` 參照。新設定應優先使用 `openai/*`，並搭配明確的 Codex runtime policy。
|
||||
|
||||
例如，這會將預設代理程式保留在一般自動選擇，
|
||||
並加入一個獨立的 Codex 代理程式：
|
||||
例如，這會讓預設 agent 使用一般自動選擇，並新增一個獨立的 Codex agent：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -231,39 +279,33 @@ Plugin 會阻擋較舊或未版本化的 app-server handshake。這會讓 OpenCl
|
||||
}
|
||||
```
|
||||
|
||||
使用此形態時：
|
||||
使用這種形式時：
|
||||
|
||||
- 預設 `main` 代理程式會使用一般提供者路徑與 PI 相容性 fallback。
|
||||
- `codex` 代理程式會使用 Codex app-server harness。
|
||||
- 如果 Codex 對 `codex` 代理程式缺失或不受支援，該回合會失敗，
|
||||
而不是悄悄使用 PI。
|
||||
- 預設的 `main` agent 會使用一般提供者路徑與 Pi 相容性 fallback。
|
||||
- `codex` agent 會使用 Codex app-server harness。
|
||||
- 如果 `codex` agent 缺少 Codex 或不受支援，該回合會失敗，而不是悄悄使用 Pi。
|
||||
|
||||
## 代理程式命令路由
|
||||
## Agent 命令路由
|
||||
|
||||
代理程式應依意圖路由使用者要求，而不是只依據「Codex」這個字：
|
||||
Agents 應依意圖路由使用者請求，而不是只依「Codex」這個詞：
|
||||
|
||||
| 使用者要求... | 代理程式應使用... |
|
||||
| 使用者要求... | Agent 應使用... |
|
||||
| -------------------------------------------------------- | ------------------------------------------------ |
|
||||
| 「將這個聊天綁定到 Codex」 | `/codex bind` |
|
||||
| 「在這裡繼續 Codex thread `<id>`」 | `/codex resume <id>` |
|
||||
| 「顯示 Codex threads」 | `/codex threads` |
|
||||
| 「為一次不良 Codex 執行提交支援報告」 | `/diagnostics [note]` |
|
||||
| 「只為這個附加 thread 傳送 Codex feedback」 | `/codex diagnostics [note]` |
|
||||
| 「使用 Codex 作為此代理程式的 runtime」 | 將設定變更為 `agentRuntime.id` |
|
||||
| 「搭配一般 OpenClaw 使用我的 ChatGPT/Codex 訂閱」 | `openai-codex/*` model refs |
|
||||
| 「透過 ACP/acpx 執行 Codex」 | ACP `sessions_spawn({ runtime: "acp", ... })` |
|
||||
| 「在 thread 中啟動 Claude Code/Gemini/OpenCode/Cursor」 | ACP/acpx，而非 `/codex`，也不是原生子代理程式 |
|
||||
|「將此 chat 綁定到 Codex」 | `/codex bind` |
|
||||
|「在這裡繼續 Codex thread `<id>`」 | `/codex resume <id>` |
|
||||
|「顯示 Codex threads」 | `/codex threads` |
|
||||
|「為失敗的 Codex 執行提交支援報告」 | `/diagnostics [note]` |
|
||||
|「只針對這個附加的 thread 傳送 Codex feedback」 | `/codex diagnostics [note]` |
|
||||
|「使用 Codex 作為此 agent 的 runtime」 | 將設定變更為 `agentRuntime.id` |
|
||||
|「用我的 ChatGPT/Codex 訂閱搭配一般 OpenClaw」 | `openai-codex/*` 模型參照 |
|
||||
|「透過 ACP/acpx 執行 Codex」 | ACP `sessions_spawn({ runtime: "acp", ... })` |
|
||||
|「在 thread 中啟動 Claude Code/Gemini/OpenCode/Cursor」 | ACP/acpx，而不是 `/codex`，也不是原生 sub-agents |
|
||||
|
||||
OpenClaw 只會在 ACP 已啟用、可分派，且由已載入的 runtime backend 支援時，
|
||||
才向代理程式宣告 ACP spawn 指引。如果 ACP 不可用，
|
||||
系統提示與 Plugin skills 不應教導代理程式 ACP
|
||||
路由。
|
||||
只有在 ACP 已啟用、可分派，並由已載入的 runtime backend 支援時，OpenClaw 才會向 agents 宣告 ACP spawn 指引。如果 ACP 不可用，system prompt 與 Plugin skills 不應教 agent ACP 路由。
|
||||
|
||||
## 僅 Codex 的部署
|
||||
|
||||
當你需要證明每個嵌入式代理程式回合都使用 Codex 時，請強制使用 Codex harness。
|
||||
明確的 Plugin runtime 預設沒有 PI fallback，因此
|
||||
`fallback: "none"` 是選用的，但通常很適合作為文件說明：
|
||||
當你需要證明每個嵌入式 agent 回合都使用 Codex 時，請強制使用 Codex harness。明確的 Plugin runtime 預設沒有 Pi fallback，因此 `fallback: "none"` 是選用的，但通常可作為有用的文件說明：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -285,15 +327,11 @@ OpenClaw 只會在 ACP 已啟用、可分派，且由已載入的 runtime backen
|
||||
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
|
||||
```
|
||||
|
||||
在強制使用 Codex 時，如果 Codex Plugin 已停用、
|
||||
app-server 太舊，或 app-server 無法啟動，OpenClaw 會提早失敗。只有在你有意讓 PI 處理
|
||||
缺失的 harness 選擇時，才設定
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。
|
||||
強制使用 Codex 時，如果 Codex Plugin 已停用、app-server 太舊，或 app-server 無法啟動，OpenClaw 會提早失敗。只有在你有意讓 Pi 處理缺少 harness 選擇時，才設定 `OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。
|
||||
|
||||
## 逐代理程式 Codex
|
||||
## 每個 agent 的 Codex
|
||||
|
||||
你可以讓一個代理程式僅使用 Codex，同時讓預設代理程式保留一般
|
||||
自動選擇：
|
||||
你可以讓某個 agent 僅使用 Codex，同時讓預設 agent 保持一般自動選擇：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -324,15 +362,11 @@ app-server 太舊，或 app-server 無法啟動，OpenClaw 會提早失敗。只
|
||||
}
|
||||
```
|
||||
|
||||
使用一般 session 命令切換代理程式與模型。`/new` 會建立新的
|
||||
OpenClaw session，而 Codex harness 會視需要建立或繼續其 sidecar app-server
|
||||
thread。`/reset` 會清除此 thread 的 OpenClaw session binding，
|
||||
並讓下一個回合再次從目前設定解析 harness。
|
||||
使用一般 session 命令切換 agents 與模型。`/new` 會建立新的 OpenClaw session，而 Codex harness 會視需要建立或繼續其 sidecar app-server thread。`/reset` 會清除該 thread 的 OpenClaw session 綁定，並讓下一個回合再次從目前設定解析 harness。
|
||||
|
||||
## 模型探索
|
||||
|
||||
預設情況下，Codex Plugin 會向 app-server 詢問可用模型。如果
|
||||
探索失敗或逾時，則會對以下項目使用內建 fallback catalog：
|
||||
預設情況下，Codex Plugin 會向 app-server 詢問可用模型。如果探索失敗或逾時，它會使用內建 fallback catalog：
|
||||
|
||||
- GPT-5.5
|
||||
- GPT-5.4 mini
|
||||
@ -358,8 +392,7 @@ thread。`/reset` 會清除此 thread 的 OpenClaw session binding，
|
||||
}
|
||||
```
|
||||
|
||||
當你希望啟動時避免探測 Codex，並固定使用
|
||||
fallback catalog 時，請停用探索：
|
||||
當你希望啟動時避免探測 Codex，並固定使用 fallback catalog，請停用探索：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -378,7 +411,7 @@ fallback catalog 時，請停用探索：
|
||||
}
|
||||
```
|
||||
|
||||
## App-server 連線與政策
|
||||
## App-server 連線與 policy
|
||||
|
||||
預設情況下，Plugin 會在本機啟動 OpenClaw 管理的 Codex binary：
|
||||
|
||||
@ -386,16 +419,9 @@ fallback catalog 時，請停用探索：
|
||||
codex app-server --listen stdio://
|
||||
```
|
||||
|
||||
受管理的 binary 會宣告為內建 Plugin runtime dependency，並與其餘
|
||||
`codex` Plugin dependencies 一起 staged。這會讓 app-server
|
||||
版本繫結到內建 Plugin，而不是本機剛好安裝的任何獨立 Codex CLI。
|
||||
只有在你有意執行不同 executable 時，才設定 `appServer.command`。
|
||||
受管理的 binary 會宣告為內建 Plugin runtime dependency，並與其餘 `codex` Plugin dependencies 一起 staged。這會讓 app-server 版本與內建 Plugin 綁定，而不是使用本機剛好安裝的另一個 Codex CLI。只有在你有意執行不同 executable 時，才設定 `appServer.command`。
|
||||
|
||||
預設情況下，OpenClaw 會以 YOLO 模式啟動本機 Codex harness sessions：
|
||||
`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及
|
||||
`sandbox: "danger-full-access"`。這是用於自主 Heartbeat 的受信任本機操作者姿態：
|
||||
Codex 可以使用 shell 與網路工具，而不會因無人在場回應的原生 approval prompts
|
||||
而停止。
|
||||
預設情況下，OpenClaw 會以 YOLO 模式啟動本機 Codex harness sessions：`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及 `sandbox: "danger-full-access"`。這是自主 heartbeats 使用的受信任本機 operator 姿態：Codex 可以使用 shell 與網路工具，而不會因無人在場回答的原生核准提示而停下。
|
||||
|
||||
若要選擇使用 Codex guardian-reviewed approvals，請設定 `appServer.mode:
|
||||
"guardian"`：
|
||||
@ -418,19 +444,9 @@ Codex 可以使用 shell 與網路工具，而不會因無人在場回應的原
|
||||
}
|
||||
```
|
||||
|
||||
Guardian 模式使用 Codex 的原生 auto-review approval path。當 Codex 要求
|
||||
離開 sandbox、寫入 workspace 外部，或新增像網路
|
||||
存取這類權限時，Codex 會將該 approval request 路由到原生 reviewer，而不是
|
||||
人類提示。reviewer 會套用 Codex 的風險框架，並核准或拒絕
|
||||
該特定要求。當你需要比 YOLO 模式更多防護措施，但仍需要無人值守的代理程式
|
||||
持續推進時，請使用 Guardian。
|
||||
Guardian 模式會使用 Codex 的原生 auto-review approval path。當 Codex 要求離開 sandbox、寫入 workspace 外部，或新增網路存取等權限時，Codex 會將該核准請求路由到原生 reviewer，而不是人類提示。reviewer 會套用 Codex 的風險框架，並核准或拒絕該特定請求。當你想要比 YOLO 模式更多 guardrails，但仍需要無人值守的 agents 持續推進時，請使用 Guardian。
|
||||
|
||||
`guardian` preset 會展開為 `approvalPolicy: "on-request"`、
|
||||
`approvalsReviewer: "auto_review"`，以及 `sandbox: "workspace-write"`。
|
||||
個別 policy fields 仍會覆寫 `mode`，因此進階部署可以將
|
||||
preset 與明確選項混用。較舊的 `guardian_subagent` reviewer value
|
||||
仍會作為相容性別名接受，但新設定應使用
|
||||
`auto_review`。
|
||||
`guardian` preset 會展開為 `approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"`，以及 `sandbox: "workspace-write"`。個別 policy 欄位仍會覆寫 `mode`，因此進階部署可以混合使用 preset 與明確選項。舊版 `guardian_subagent` reviewer 值仍會作為相容性 alias 被接受，但新設定應使用 `auto_review`。
|
||||
|
||||
對於已在執行的 app-server，請使用 WebSocket transport：
|
||||
|
||||
@ -454,25 +470,27 @@ preset 與明確選項混用。較舊的 `guardian_subagent` reviewer value
|
||||
}
|
||||
```
|
||||
|
||||
Stdio app-server launches 預設會繼承 OpenClaw 的 process environment，
|
||||
但 OpenClaw 擁有 Codex app-server account bridge。Auth 會依照以下
|
||||
順序選取：
|
||||
Stdio app-server launches 預設會繼承 OpenClaw 的 process environment，但 OpenClaw 會擁有 Codex app-server account bridge，並將 `CODEX_HOME` 與 `HOME` 都設為該 agent 的 OpenClaw state 下的每個 agent 目錄。Codex 自己的 skill loader 會讀取 `$CODEX_HOME/skills` 與 `$HOME/.agents/skills`，因此這兩個值都會針對本機 app-server launches 隔離。這會讓 Codex-native skills、plugins、config、accounts 與 thread state 限定在 OpenClaw agent 範圍內，而不是從 operator 個人的 Codex CLI home 洩漏進來。
|
||||
|
||||
1. 代理程式的明確 OpenClaw Codex auth profile。
|
||||
2. app-server 現有的 account，例如本機 Codex CLI ChatGPT sign-in。
|
||||
3. 僅限本機 stdio app-server launches，當沒有 app-server account，且仍需要 OpenAI auth 時，使用 `CODEX_API_KEY`，接著是
|
||||
OpenClaw plugins 與 OpenClaw skill snapshots 仍會透過 OpenClaw 自己的 Plugin registry 與 skill loader 流動。個人 Codex CLI assets 不會。如果你有實用的 Codex CLI skills 或 plugins 應成為 OpenClaw agent 的一部分，請明確 inventory 它們：
|
||||
|
||||
```bash
|
||||
openclaw migrate codex --dry-run
|
||||
openclaw migrate apply codex --yes
|
||||
```
|
||||
|
||||
Codex migration provider 會將 skills 複製到目前的 OpenClaw agent workspace。Codex native plugins、hooks 與 config files 會被報告或封存以供手動審查，而不是自動啟用，因為它們可以執行命令、公開 MCP servers，或攜帶 credentials。
|
||||
|
||||
Auth 會依下列順序選擇：
|
||||
|
||||
1. 該 agent 的明確 OpenClaw Codex auth profile。
|
||||
2. app-server 在該 agent 的 Codex home 中既有的 account。
|
||||
3. 僅限本機 stdio app-server launches，當沒有 app-server account 且仍需要 OpenAI auth 時，使用 `CODEX_API_KEY`，接著使用
|
||||
`OPENAI_API_KEY`。
|
||||
|
||||
當 OpenClaw 看到 ChatGPT subscription-style Codex auth profile 時，會從 spawned Codex child process 中移除
|
||||
`CODEX_API_KEY` 與 `OPENAI_API_KEY`。這會讓 Gateway-level API keys
|
||||
仍可供 embeddings 或直接 OpenAI models 使用，而不會意外讓原生 Codex app-server turns
|
||||
透過 API 計費。明確的 Codex API-key profiles 與本機 stdio env-key fallback 會使用 app-server
|
||||
login，而不是繼承的 child-process env。WebSocket app-server connections
|
||||
不會收到 Gateway env API-key fallback；請使用明確的 auth profile，或
|
||||
遠端 app-server 自己的 account。
|
||||
當 OpenClaw 看到 ChatGPT 訂閱式 Codex auth profile 時，會從產生的 Codex child process 移除 `CODEX_API_KEY` 與 `OPENAI_API_KEY`。這會讓 Gateway 層級的 API keys 仍可用於 embeddings 或直接 OpenAI models，而不會讓原生 Codex app-server 回合意外透過 API 計費。明確的 Codex API-key profiles 與本機 stdio env-key fallback 會使用 app-server login，而不是繼承的 child-process env。WebSocket app-server connections 不會收到 Gateway env API-key fallback；請使用明確 auth profile 或 remote app-server 自己的 account。
|
||||
|
||||
如果部署需要額外的環境隔離，請將那些變數加入
|
||||
`appServer.clearEnv`：
|
||||
如果部署需要額外的環境隔離，請將那些 variables 加到 `appServer.clearEnv`：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -491,29 +509,38 @@ login，而不是繼承的 child-process env。WebSocket app-server connections
|
||||
}
|
||||
```
|
||||
|
||||
`appServer.clearEnv` 只會影響 spawned Codex app-server child process。
|
||||
`appServer.clearEnv` 只會影響產生的 Codex app-server child process。
|
||||
|
||||
支援的 `appServer` 欄位：
|
||||
|
||||
| 欄位 | 預設值 | 意義 |
|
||||
| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `transport` | `"stdio"` | `"stdio"` 會產生 Codex；`"websocket"` 會連線到 `url`。 |
|
||||
| `command` | 受管理的 Codex 二進位檔 | stdio 傳輸使用的可執行檔。保留未設定即可使用受管理的二進位檔；只有在明確覆寫時才設定。 |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | stdio 傳輸使用的引數。 |
|
||||
| `url` | 未設定 | WebSocket app-server URL。 |
|
||||
| `authToken` | 未設定 | WebSocket 傳輸使用的 Bearer 權杖。 |
|
||||
| `headers` | `{}` | 額外的 WebSocket 標頭。 |
|
||||
| `clearEnv` | `[]` | OpenClaw 建立其繼承環境之後，從產生的 stdio app-server 程序中移除的額外環境變數名稱。 |
|
||||
| `requestTimeoutMs` | `60000` | app-server 控制平面呼叫的逾時。 |
|
||||
| `mode` | `"yolo"` | YOLO 或守護程式審查執行的預設設定。 |
|
||||
| `approvalPolicy` | `"never"` | 傳送到執行緒啟動/恢復/回合的原生 Codex 核准原則。 |
|
||||
| `sandbox` | `"danger-full-access"` | 傳送到執行緒啟動/恢復的原生 Codex sandbox 模式。 |
|
||||
| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 讓 Codex 審查原生核准提示。`guardian_subagent` 仍是舊版別名。 |
|
||||
| `serviceTier` | 未設定 | 選用的 Codex app-server 服務層級：`"fast"`、`"flex"` 或 `null`。無效的舊版值會被忽略。 |
|
||||
| 欄位 | 預設值 | 意義 |
|
||||
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `transport` | `"stdio"` | `"stdio"` 會產生 Codex；`"websocket"` 會連線到 `url`。 |
|
||||
| `command` | 受管理的 Codex 二進位檔 | stdio 傳輸使用的可執行檔。保留未設定即可使用受管理的二進位檔；只有在明確覆寫時才設定。 |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | stdio 傳輸使用的引數。 |
|
||||
| `url` | 未設定 | WebSocket app-server URL。 |
|
||||
| `authToken` | 未設定 | WebSocket 傳輸使用的 Bearer token。 |
|
||||
| `headers` | `{}` | 額外的 WebSocket 標頭。 |
|
||||
| `clearEnv` | `[]` | OpenClaw 建立繼承環境後，從產生的 stdio app-server 程序中移除的額外環境變數名稱。`CODEX_HOME` 和 `HOME` 保留給 OpenClaw 在本機啟動時用於每個代理程式的 Codex 隔離。 |
|
||||
| `requestTimeoutMs` | `60000` | app-server 控制平面呼叫的逾時時間。 |
|
||||
| `mode` | `"yolo"` | YOLO 或 guardian 審查執行的預設組態。 |
|
||||
| `approvalPolicy` | `"never"` | 傳送到執行緒開始/恢復/回合的原生 Codex 核准政策。 |
|
||||
| `sandbox` | `"danger-full-access"` | 傳送到執行緒開始/恢復的原生 Codex 沙箱模式。 |
|
||||
| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 讓 Codex 審查原生核准提示。`guardian_subagent` 仍是舊版別名。 |
|
||||
| `serviceTier` | 未設定 | 選用的 Codex app-server 服務層級：`"fast"`、`"flex"` 或 `null`。無效的舊版值會被忽略。 |
|
||||
|
||||
OpenClaw 擁有的動態工具呼叫會與 `appServer.requestTimeoutMs` 分開限制：每個 Codex `item/tool/call` 請求都必須在 30 秒內收到 OpenClaw 回應。逾時時，OpenClaw 會在支援的情況下中止工具訊號，並將失敗的動態工具回應傳回給 Codex，讓該回合可以繼續，而不是讓工作階段停留在 `processing`。
|
||||
OpenClaw 擁有的動態工具呼叫會獨立於
|
||||
`appServer.requestTimeoutMs` 受限制：每個 Codex `item/tool/call` 要求都必須在
|
||||
30 秒內收到 OpenClaw 回應。逾時時，OpenClaw 會在支援的情況下中止工具
|
||||
訊號，並向 Codex 回傳失敗的動態工具回應，讓該回合可以繼續，而不是讓工作階段停留在
|
||||
`processing`。
|
||||
|
||||
OpenClaw 回應 Codex 回合範圍的 app-server 請求後，測試框架也預期 Codex 以 `turn/completed` 完成原生回合。如果 app-server 在該回應後靜默 60 秒，OpenClaw 會盡力中斷 Codex 回合、記錄診斷逾時，並釋放 OpenClaw 工作階段通道，讓後續聊天訊息不會排在過期的原生回合後方。
|
||||
OpenClaw 回應 Codex 回合範圍的 app-server 要求後，測試框架
|
||||
也預期 Codex 以 `turn/completed` 完成原生回合。如果
|
||||
app-server 在該回應後靜默 60 秒，OpenClaw 會盡力
|
||||
中斷 Codex 回合、記錄診斷逾時，並釋放
|
||||
OpenClaw 工作階段通道，讓後續聊天訊息不會排在過期的
|
||||
原生回合後面。
|
||||
|
||||
環境覆寫仍可用於本機測試：
|
||||
|
||||
@ -525,16 +552,27 @@ OpenClaw 回應 Codex 回合範圍的 app-server 請求後，測試框架也預
|
||||
|
||||
當 `appServer.command` 未設定時，`OPENCLAW_CODEX_APP_SERVER_BIN` 會略過受管理的二進位檔。
|
||||
|
||||
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已移除。請改用 `plugins.entries.codex.config.appServer.mode: "guardian"`，或使用 `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` 進行一次性本機測試。可重複部署時偏好使用設定，因為它會將 Plugin 行為與其餘 Codex 測試框架設定保留在同一個已審查檔案中。
|
||||
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已移除。請改用
|
||||
`plugins.entries.codex.config.appServer.mode: "guardian"`，或針對一次性本機測試使用
|
||||
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。可重複部署時偏好使用設定，
|
||||
因為它會讓 Plugin 行為與其餘 Codex 測試框架設定保留在同一個
|
||||
已審查的檔案中。
|
||||
|
||||
## 電腦使用
|
||||
|
||||
電腦使用在自己的設定指南中說明：
|
||||
[Codex 電腦使用](/zh-TW/plugins/codex-computer-use)。
|
||||
|
||||
簡短版本：OpenClaw 不會內建桌面控制應用程式，也不會自行執行桌面動作。它會準備 Codex app-server、驗證 `computer-use` MCP 伺服器可用，然後讓 Codex 在 Codex 模式回合期間處理原生 MCP 工具呼叫。
|
||||
簡短版本：OpenClaw 不會內建桌面控制應用程式，也不會自行執行
|
||||
桌面動作。它會準備 Codex app-server、驗證
|
||||
`computer-use` MCP 伺服器可用，然後讓 Codex 在 Codex 模式回合期間處理原生
|
||||
MCP 工具呼叫。
|
||||
|
||||
若要在 Codex 市集流程之外直接存取 TryCua 驅動程式，請使用 `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` 註冊 `cua-driver mcp`。請參閱 [Codex 電腦使用](/zh-TW/plugins/codex-computer-use)，了解 Codex 擁有的電腦使用與直接 MCP 註冊之間的差異。
|
||||
若要在 Codex marketplace 流程之外直接存取 TryCua 驅動程式，請使用
|
||||
`openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` 註冊
|
||||
`cua-driver mcp`。
|
||||
請參閱 [Codex 電腦使用](/zh-TW/plugins/codex-computer-use)，了解 Codex 擁有的電腦使用
|
||||
與直接 MCP 註冊之間的差異。
|
||||
|
||||
最小設定：
|
||||
|
||||
@ -564,18 +602,27 @@ OpenClaw 回應 Codex 回合範圍的 app-server 請求後，測試框架也預
|
||||
}
|
||||
```
|
||||
|
||||
可從命令介面檢查或安裝設定：
|
||||
可以從命令介面檢查或安裝設定：
|
||||
|
||||
- `/codex computer-use status`
|
||||
- `/codex computer-use install`
|
||||
- `/codex computer-use install --source <marketplace-source>`
|
||||
- `/codex computer-use install --marketplace-path <path>`
|
||||
|
||||
電腦使用僅適用於 macOS，且 Codex MCP 伺服器能控制應用程式之前，可能需要本機作業系統權限。如果 `computerUse.enabled` 為 true 且 MCP 伺服器無法使用，Codex 模式回合會在線程啟動前失敗，而不是在沒有原生電腦使用工具的情況下靜默執行。請參閱 [Codex 電腦使用](/zh-TW/plugins/codex-computer-use)，了解市集選項、遠端目錄限制、狀態原因和疑難排解。
|
||||
電腦使用為 macOS 專用，且在
|
||||
Codex MCP 伺服器可以控制應用程式前，可能需要本機作業系統權限。如果 `computerUse.enabled` 為 true 且 MCP
|
||||
伺服器不可用，Codex 模式回合會在執行緒開始前失敗，而不是在沒有原生電腦使用工具的情況下
|
||||
靜默執行。請參閱
|
||||
[Codex 電腦使用](/zh-TW/plugins/codex-computer-use)，了解 marketplace 選項、
|
||||
遠端目錄限制、狀態原因和疑難排解。
|
||||
|
||||
當 `computerUse.autoInstall` 為 true 時，如果 Codex 尚未探索到本機市集，OpenClaw 可以從 `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 註冊標準內建的 Codex Desktop 市集。變更執行階段或電腦使用設定後，請使用 `/new` 或 `/reset`，讓現有工作階段不要保留舊的 PI 或 Codex 執行緒繫結。
|
||||
當 `computerUse.autoInstall` 為 true 時，如果 Codex
|
||||
尚未探索到本機 marketplace，OpenClaw 可以從
|
||||
`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 註冊標準
|
||||
內建 Codex Desktop marketplace。變更執行階段或電腦使用設定後，請使用 `/new` 或 `/reset`，
|
||||
讓既有工作階段不會保留舊的 PI 或 Codex 執行緒繫結。
|
||||
|
||||
## 常見配方
|
||||
## 常用配方
|
||||
|
||||
使用預設 stdio 傳輸的本機 Codex：
|
||||
|
||||
@ -591,7 +638,7 @@ OpenClaw 回應 Codex 回合範圍的 app-server 請求後，測試框架也預
|
||||
}
|
||||
```
|
||||
|
||||
僅限 Codex 的測試框架驗證：
|
||||
僅 Codex 的測試框架驗證：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -613,7 +660,7 @@ OpenClaw 回應 Codex 回合範圍的 app-server 請求後，測試框架也預
|
||||
}
|
||||
```
|
||||
|
||||
守護程式審查的 Codex 核准：
|
||||
guardian 審查的 Codex 核准：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -658,199 +705,165 @@ OpenClaw 回應 Codex 回合範圍的 app-server 請求後，測試框架也預
|
||||
}
|
||||
```
|
||||
|
||||
模型切換仍由 OpenClaw 控制。當 OpenClaw 工作階段附加到現有 Codex 執行緒時，下一個回合會再次將目前選取的 OpenAI 模型、供應商、核准原則、sandbox 和服務層級傳送到 app-server。從 `openai/gpt-5.5` 切換到 `openai/gpt-5.2` 會保留執行緒繫結，但要求 Codex 使用新選取的模型繼續。
|
||||
模型切換仍由 OpenClaw 控制。當 OpenClaw 工作階段附加到
|
||||
既有 Codex 執行緒時，下一個回合會再次將目前選取的
|
||||
OpenAI 模型、供應商、核准政策、沙箱和服務層級傳送到
|
||||
app-server。從 `openai/gpt-5.5` 切換到 `openai/gpt-5.2` 會保留
|
||||
執行緒繫結，但要求 Codex 使用新選取的模型繼續。
|
||||
|
||||
## Codex 命令
|
||||
|
||||
內建 Plugin 會將 `/codex` 註冊為已授權的斜線命令。它是通用命令，適用於任何支援 OpenClaw 文字命令的通道。
|
||||
內建 Plugin 會將 `/codex` 註冊為授權的斜線命令。它是
|
||||
通用命令，適用於任何支援 OpenClaw 文字命令的頻道。
|
||||
|
||||
常見形式：
|
||||
常用形式：
|
||||
|
||||
- `/codex status` 顯示即時 app-server 連線能力、模型、帳戶、速率限制、MCP 伺服器和 Skills。
|
||||
- `/codex status` 顯示即時 app-server 連線能力、模型、帳戶、速率限制、MCP 伺服器和 skills。
|
||||
- `/codex models` 列出即時 Codex app-server 模型。
|
||||
- `/codex threads [filter]` 列出最近的 Codex 執行緒。
|
||||
- `/codex resume <thread-id>` 將目前 OpenClaw 工作階段附加到現有 Codex 執行緒。
|
||||
- `/codex resume <thread-id>` 將目前的 OpenClaw 工作階段附加到既有 Codex 執行緒。
|
||||
- `/codex compact` 要求 Codex app-server 壓縮附加的執行緒。
|
||||
- `/codex review` 針對附加的執行緒啟動 Codex 原生審查。
|
||||
- `/codex diagnostics [note]` 在傳送附加執行緒的 Codex 診斷意見回饋前先詢問。
|
||||
- `/codex review` 為附加的執行緒啟動 Codex 原生審查。
|
||||
- `/codex diagnostics [note]` 在傳送附加執行緒的 Codex 診斷回饋前先詢問。
|
||||
- `/codex computer-use status` 檢查已設定的電腦使用 Plugin 和 MCP 伺服器。
|
||||
- `/codex computer-use install` 安裝已設定的電腦使用 Plugin 並重新載入 MCP 伺服器。
|
||||
- `/codex account` 顯示帳戶和速率限制狀態。
|
||||
- `/codex mcp` 列出 Codex app-server MCP 伺服器狀態。
|
||||
- `/codex skills` 列出 Codex app-server Skills。
|
||||
- `/codex skills` 列出 Codex app-server skills。
|
||||
|
||||
### 常見除錯工作流程
|
||||
### 常用偵錯工作流程
|
||||
|
||||
當 Codex 支援的代理程式在 Telegram、Discord、Slack 或其他通道中做出令人意外的事情時，請從發生問題的對話開始：
|
||||
當 Codex 支援的代理程式在 Telegram、Discord、Slack
|
||||
或其他頻道中出現意外行為時，請從發生問題的對話開始：
|
||||
|
||||
1. 執行 `/diagnostics bad tool choice after image upload`，或輸入另一則描述你所見情況的簡短備註。
|
||||
2. 核准一次診斷請求。核准會建立本機 Gateway 診斷 zip，且因為工作階段正在使用 Codex 測試框架，也會將相關的 Codex 意見回饋套件傳送到 OpenAI 伺服器。
|
||||
3. 將完成的診斷回覆複製到錯誤報告或支援討論串。它包含本機套件路徑、隱私摘要、OpenClaw 工作階段 ID、Codex 執行緒 ID，以及每個 Codex 執行緒的 `Inspect locally` 行。
|
||||
4. 如果你想自行偵錯該次執行，請在終端機中執行印出的 `Inspect locally` 命令。它看起來像 `codex resume <thread-id>`，會開啟原生 Codex 執行緒，讓你可以檢查對話、在本機繼續，或詢問 Codex 為何選擇特定工具或計畫。
|
||||
1. 執行 `/diagnostics bad tool choice after image upload` 或另一個描述你所見情況的簡短註記。
|
||||
2. 核准診斷要求一次。該核准會建立本機 Gateway
|
||||
診斷 zip，並且因為工作階段正在使用 Codex 測試框架，也會
|
||||
將相關的 Codex 回饋套件傳送到 OpenAI 伺服器。
|
||||
3. 將完成的診斷回覆複製到錯誤報告或支援討論串中。
|
||||
其中包含本機套件路徑、隱私摘要、OpenClaw 工作階段 ID、
|
||||
Codex 執行緒 ID，以及每個 Codex 執行緒的 `Inspect locally` 行。
|
||||
4. 如果想自行偵錯該次執行，請在終端機中執行列印出的 `Inspect locally`
|
||||
命令。它看起來像 `codex resume <thread-id>`，並會開啟
|
||||
原生 Codex 執行緒，讓你檢查對話、在本機繼續，
|
||||
或詢問 Codex 為何選擇特定工具或計畫。
|
||||
|
||||
只有在你特別想為目前附加的執行緒上傳 Codex 意見回饋，而不需要完整 OpenClaw Gateway 診斷套件時，才使用 `/codex diagnostics [note]`。對於大多數支援報告，`/diagnostics [note]` 是較佳的起點，因為它會在同一則回覆中將本機 Gateway 狀態與 Codex 執行緒 ID 關聯起來。請參閱 [診斷匯出](/zh-TW/gateway/diagnostics)，了解完整隱私模型與群組聊天行為。
|
||||
只有在你特別想要目前附加執行緒的 Codex 意見回饋上傳，而不需要完整 OpenClaw Gateway 診斷套件時，才使用 `/codex diagnostics [note]`。對大多數支援回報來說，`/diagnostics [note]` 是更好的起點，因為它會在同一則回覆中把本機 Gateway 狀態與 Codex 執行緒 ID 串在一起。完整的隱私模型與群組聊天行為請參閱[診斷匯出](/zh-TW/gateway/diagnostics)。
|
||||
|
||||
核心 OpenClaw 也會公開僅限擁有者的 `/diagnostics [note]`，作為一般 Gateway 診斷命令。其核准提示會顯示敏感資料前言、連結到 [診斷匯出](/zh-TW/gateway/diagnostics)，並每次都透過明確的執行核准請求 `openclaw gateway diagnostics export --json`。請勿使用允許全部規則核准診斷。核准後，OpenClaw 會傳送可貼上的報告，其中包含本機套件路徑與清單摘要。當作用中的 OpenClaw 工作階段使用 Codex 測試框架時，同一個核准也會授權將相關的 Codex 意見回饋套件傳送到 OpenAI 伺服器。核准提示會說明將傳送 Codex 意見回饋，但不會在核准前列出 Codex 工作階段或執行緒 ID。
|
||||
核心 OpenClaw 也會將僅限擁有者使用的 `/diagnostics [note]` 暴露為一般 Gateway 診斷命令。它的核准提示會顯示敏感資料前言、連結到[診斷匯出](/zh-TW/gateway/diagnostics)，並且每次都透過明確的 exec 核准請求 `openclaw gateway diagnostics export --json`。不要用 allow-all 規則核准診斷。核准後，OpenClaw 會傳送一份可貼上的報告，其中包含本機套件路徑與 manifest 摘要。當作用中的 OpenClaw 工作階段正在使用 Codex harness 時，同一個核准也會授權將相關的 Codex 意見回饋套件傳送到 OpenAI 伺服器。核准提示會說明將會傳送 Codex 意見回饋，但在核准前不會列出 Codex 工作階段或執行緒 ID。
|
||||
|
||||
如果 `/diagnostics` 是由群組聊天中的擁有者叫用，OpenClaw 會保持共享通道乾淨：群組只會收到簡短通知，而診斷前言、核准提示和 Codex 工作階段/執行緒 ID 會透過私人核准路由傳送給擁有者。如果沒有私人擁有者路由，OpenClaw 會拒絕群組請求，並要求擁有者從 DM 執行。
|
||||
如果擁有者在群組聊天中呼叫 `/diagnostics`，OpenClaw 會保持共享頻道簡潔：群組只會收到一則短通知，而診斷前言、核准提示，以及 Codex 工作階段/執行緒 ID 會透過私人核准路由傳送給擁有者。如果沒有私人擁有者路由，OpenClaw 會拒絕群組請求，並要求擁有者從 DM 執行。
|
||||
|
||||
已核准的 Codex 上傳會呼叫 Codex app-server `feedback/upload`，並要求
|
||||
app-server 在可用時，為每個列出的對話串和衍生的 Codex 子對話串包含記錄。
|
||||
上傳會透過 Codex 一般的意見回饋路徑送往 OpenAI
|
||||
伺服器；如果該 app-server 中停用了 Codex 意見回饋，命令會回傳
|
||||
app-server 錯誤。完成的診斷回覆會列出已傳送對話串的頻道、
|
||||
OpenClaw 工作階段 ID、Codex 對話串 ID，以及本機 `codex resume <thread-id>`
|
||||
命令。如果你拒絕或忽略核准，OpenClaw 不會印出那些 Codex ID。這次上傳不會取代本機
|
||||
Gateway 診斷匯出。
|
||||
已核准的 Codex 上傳會呼叫 Codex app-server `feedback/upload`，並要求 app-server 在可用時包含每個列出執行緒與衍生 Codex 子執行緒的記錄。上傳會透過 Codex 的一般意見回饋路徑傳送到 OpenAI 伺服器；如果該 app-server 停用了 Codex 意見回饋，命令會回傳 app-server 錯誤。完成的診斷回覆會列出已傳送執行緒的頻道、OpenClaw 工作階段 ID、Codex 執行緒 ID，以及本機 `codex resume <thread-id>` 命令。如果你拒絕或忽略核准，OpenClaw 不會列印那些 Codex ID。這項上傳不會取代本機 Gateway 診斷匯出。
|
||||
|
||||
`/codex resume` 會寫入與 harness 用於一般回合相同的附屬繫結檔案。
|
||||
在下一則訊息中，OpenClaw 會恢復該 Codex 對話串，將目前選取的
|
||||
OpenClaw 模型傳入 app-server，並保持延伸歷史記錄啟用。
|
||||
`/codex resume` 會寫入 harness 在一般回合中使用的同一個 sidecar 綁定檔。下一則訊息時，OpenClaw 會恢復該 Codex 執行緒，將目前選取的 OpenClaw 模型傳入 app-server，並保持延伸歷史記錄啟用。
|
||||
|
||||
### 從 CLI 檢查 Codex 對話串
|
||||
### 從 CLI 檢查 Codex 執行緒
|
||||
|
||||
理解一次不良 Codex 執行的最快方式，通常是直接開啟原生 Codex
|
||||
對話串：
|
||||
了解有問題的 Codex 執行時，最快的方式通常是直接開啟原生 Codex 執行緒：
|
||||
|
||||
```sh
|
||||
codex resume <thread-id>
|
||||
```
|
||||
|
||||
當你在頻道對話中注意到錯誤，並想檢查有問題的
|
||||
Codex 工作階段、在本機繼續該工作階段，或詢問 Codex 為什麼做出某個
|
||||
工具或推理選擇時，請使用這個命令。最簡單的路徑通常是先執行
|
||||
`/diagnostics [note]`：核准後，完成的報告會列出
|
||||
每個 Codex 對話串，並印出一個 `Inspect locally` 命令，例如
|
||||
`codex resume <thread-id>`。你可以將該命令直接複製到終端機中。
|
||||
當你在頻道對話中注意到錯誤，並且想檢查有問題的 Codex 工作階段、在本機繼續它，或詢問 Codex 為何做出特定工具或推理選擇時，請使用這個方式。最簡單的路徑通常是先執行 `/diagnostics [note]`：核准後，完成的報告會列出每個 Codex 執行緒，並列印一個 `Inspect locally` 命令，例如 `codex resume <thread-id>`。你可以直接把該命令複製到終端機。
|
||||
|
||||
你也可以從目前聊天的 `/codex binding`，或近期 Codex app-server 對話串的
|
||||
`/codex threads [filter]` 取得對話串 ID，然後在 shell 中執行相同的
|
||||
`codex resume` 命令。
|
||||
你也可以從目前聊天的 `/codex binding`，或最近 Codex app-server 執行緒的 `/codex threads [filter]` 取得執行緒 ID，然後在 shell 中執行同一個 `codex resume` 命令。
|
||||
|
||||
這個命令介面需要 Codex app-server `0.125.0` 或更新版本。如果未來或自訂
|
||||
app-server 未公開該 JSON-RPC 方法，個別控制方法會回報為
|
||||
`unsupported by this Codex app-server`。
|
||||
命令介面需要 Codex app-server `0.125.0` 或更新版本。如果未來或自訂 app-server 未暴露該 JSON-RPC 方法，個別控制方法會回報為 `unsupported by this Codex app-server`。
|
||||
|
||||
## Hook 邊界
|
||||
|
||||
Codex harness 有三層 hook：
|
||||
Codex harness 有三個 Hook 層：
|
||||
|
||||
| 層級 | 擁有者 | 目的 |
|
||||
| 層 | 擁有者 | 目的 |
|
||||
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
|
||||
| OpenClaw Plugin hooks | OpenClaw | 跨 PI 和 Codex harness 的產品/Plugin 相容性。 |
|
||||
| Codex app-server extension middleware | OpenClaw bundled plugins | 圍繞 OpenClaw 動態工具的每回合轉接器行為。 |
|
||||
| Codex native hooks | Codex | 來自 Codex 設定的低階 Codex 生命週期與原生工具政策。 |
|
||||
| OpenClaw Plugin Hook | OpenClaw | 跨 PI 與 Codex harness 的產品/Plugin 相容性。 |
|
||||
| Codex app-server 擴充中介軟體 | OpenClaw bundled plugins | 圍繞 OpenClaw 動態工具的逐回合 adapter 行為。 |
|
||||
| Codex 原生 Hook | Codex | 來自 Codex 設定的底層 Codex 生命週期與原生工具政策。 |
|
||||
|
||||
OpenClaw 不會使用專案或全域 Codex `hooks.json` 檔案來路由
|
||||
OpenClaw Plugin 行為。對於受支援的原生工具與權限橋接，
|
||||
OpenClaw 會為 `PreToolUse`、`PostToolUse`、
|
||||
`PermissionRequest` 和 `Stop` 注入每個對話串的 Codex 設定。其他 Codex hooks，例如 `SessionStart` 和
|
||||
`UserPromptSubmit`，仍然是 Codex 層級的控制；它們不會在 v1 合約中作為
|
||||
OpenClaw Plugin hooks 公開。
|
||||
OpenClaw 不使用專案或全域 Codex `hooks.json` 檔案來路由 OpenClaw Plugin 行為。對於受支援的原生工具與權限橋接，OpenClaw 會為 `PreToolUse`、`PostToolUse`、`PermissionRequest` 和 `Stop` 注入逐執行緒 Codex 設定。其他 Codex Hook，例如 `SessionStart` 和 `UserPromptSubmit`，仍然是 Codex 層級的控制；它們不會在 v1 合約中暴露為 OpenClaw Plugin Hook。
|
||||
|
||||
對於 OpenClaw 動態工具，OpenClaw 會在 Codex 要求呼叫後執行該工具，
|
||||
因此 OpenClaw 會在 harness 轉接器中觸發它所擁有的 Plugin 和 middleware 行為。對於 Codex 原生工具，Codex 擁有標準工具記錄。
|
||||
OpenClaw 可以鏡像選定事件，但除非 Codex 透過 app-server 或原生 hook
|
||||
callbacks 公開該操作，否則它無法重寫原生 Codex 對話串。
|
||||
對於 OpenClaw 動態工具，OpenClaw 會在 Codex 請求呼叫後執行工具，因此 OpenClaw 會在 harness adapter 中觸發它所擁有的 Plugin 與中介軟體行為。對於 Codex 原生工具，Codex 擁有標準工具記錄。OpenClaw 可以鏡像選定事件，但除非 Codex 透過 app-server 或原生 Hook callback 暴露該操作，否則 OpenClaw 無法重寫原生 Codex 執行緒。
|
||||
|
||||
Compaction 和 LLM 生命週期投影來自 Codex app-server
|
||||
通知與 OpenClaw 轉接器狀態，而不是原生 Codex hook 命令。
|
||||
OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和
|
||||
`llm_output` 事件是轉接器層級的觀察結果，不是逐位元組捕捉
|
||||
Codex 內部請求或 Compaction 承載。
|
||||
Compaction 與 LLM 生命週期投影來自 Codex app-server 通知與 OpenClaw adapter 狀態，而不是原生 Codex Hook 命令。OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 `llm_output` 事件是 adapter 層級觀察結果，不是 Codex 內部請求或 Compaction payload 的逐位元組擷取。
|
||||
|
||||
Codex 原生 `hook/started` 和 `hook/completed` app-server 通知
|
||||
會投影為 `codex_app_server.hook` 代理事件，用於軌跡與偵錯。
|
||||
它們不會叫用 OpenClaw Plugin hooks。
|
||||
Codex 原生 `hook/started` 和 `hook/completed` app-server 通知會被投影為 `codex_app_server.hook` 代理事件，用於軌跡與除錯。它們不會呼叫 OpenClaw Plugin Hook。
|
||||
|
||||
## V1 支援合約
|
||||
|
||||
Codex 模式不是在底層換成不同模型呼叫的 PI。Codex 擁有更多
|
||||
原生模型迴圈，而 OpenClaw 會圍繞該邊界調整其 Plugin 和工作階段介面。
|
||||
Codex 模式不是在底層換成不同模型呼叫的 PI。Codex 擁有更多原生模型迴圈，而 OpenClaw 會圍繞該邊界調整其 Plugin 與工作階段介面。
|
||||
|
||||
Codex runtime v1 支援：
|
||||
|
||||
| 介面 | 支援情況 | 原因 |
|
||||
| --------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 透過 Codex 的 OpenAI 模型迴圈 | 支援 | Codex app-server 擁有 OpenAI 回合、原生對話串恢復，以及原生工具延續。 |
|
||||
| OpenClaw 頻道路由與傳遞 | 支援 | Telegram、Discord、Slack、WhatsApp、iMessage 和其他頻道保持在模型 runtime 外部。 |
|
||||
| OpenClaw 動態工具 | 支援 | Codex 會要求 OpenClaw 執行這些工具，因此 OpenClaw 仍在執行路徑中。 |
|
||||
| 提示與內容 Plugin | 支援 | OpenClaw 會在啟動或恢復對話串之前建構提示覆蓋層，並將內容投影到 Codex 回合中。 |
|
||||
| 內容引擎生命週期 | 支援 | 組裝、擷取或回合後維護，以及內容引擎 Compaction 協調會針對 Codex 回合執行。 |
|
||||
| 動態工具 hooks | 支援 | `before_tool_call`、`after_tool_call` 和工具結果 middleware 會圍繞 OpenClaw 擁有的動態工具執行。 |
|
||||
| 生命週期 hooks | 作為轉接器觀察結果支援 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 會以真實的 Codex 模式承載觸發。 |
|
||||
| 最終答案修訂閘門 | 透過原生 hook 轉送支援 | Codex `Stop` 會轉送到 `before_agent_finalize`；`revise` 會要求 Codex 在最終化之前再進行一次模型傳遞。 |
|
||||
| 原生 shell、patch 和 MCP 封鎖或觀察 | 透過原生 hook 轉送支援 | Codex `PreToolUse` 和 `PostToolUse` 會針對已承諾的原生工具介面轉送，包括 Codex app-server `0.125.0` 或更新版本上的 MCP 承載。支援封鎖；不支援引數重寫。 |
|
||||
| 原生權限政策 | 透過原生 hook 轉送支援 | Codex `PermissionRequest` 可在 runtime 公開時透過 OpenClaw 政策路由。如果 OpenClaw 未回傳決策，Codex 會透過其一般 guardian 或使用者核准路徑繼續。 |
|
||||
| App-server 軌跡捕捉 | 支援 | OpenClaw 會記錄它傳送給 app-server 的請求，以及它收到的 app-server 通知。 |
|
||||
| 介面 | 支援 | 原因 |
|
||||
| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 透過 Codex 的 OpenAI 模型迴圈 | 支援 | Codex app-server 擁有 OpenAI 回合、原生執行緒恢復，以及原生工具延續。 |
|
||||
| OpenClaw 頻道路由與傳遞 | 支援 | Telegram、Discord、Slack、WhatsApp、iMessage 和其他頻道保持在模型 runtime 之外。 |
|
||||
| OpenClaw 動態工具 | 支援 | Codex 會要求 OpenClaw 執行這些工具，因此 OpenClaw 仍在執行路徑中。 |
|
||||
| Prompt 與內容 Plugin | 支援 | OpenClaw 會建立 prompt overlay，並在啟動或恢復執行緒前將內容投影到 Codex 回合中。 |
|
||||
| 內容引擎生命週期 | 支援 | 組裝、擷取或回合後維護，以及內容引擎 Compaction 協調會針對 Codex 回合執行。 |
|
||||
| 動態工具 Hook | 支援 | `before_tool_call`、`after_tool_call` 和工具結果中介軟體會圍繞 OpenClaw 擁有的動態工具執行。 |
|
||||
| 生命週期 Hook | 作為 adapter 觀察結果支援 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 會以誠實的 Codex 模式 payload 觸發。 |
|
||||
| 最終答案修訂閘門 | 透過原生 Hook relay 支援 | Codex `Stop` 會被轉送到 `before_agent_finalize`；`revise` 會在最終化前要求 Codex 再執行一次模型 pass。 |
|
||||
| 原生 shell、patch 和 MCP 封鎖或觀察 | 透過原生 Hook relay 支援 | Codex `PreToolUse` 和 `PostToolUse` 會針對已承諾的原生工具介面被轉送，包括 Codex app-server `0.125.0` 或更新版本上的 MCP payload。支援封鎖；不支援引數重寫。 |
|
||||
| 原生權限政策 | 透過原生 Hook relay 支援 | Codex `PermissionRequest` 可以在 runtime 暴露時透過 OpenClaw 政策路由。如果 OpenClaw 沒有回傳決策，Codex 會繼續透過其一般 guardian 或使用者核准路徑。 |
|
||||
| App-server 軌跡擷取 | 支援 | OpenClaw 會記錄它傳送給 app-server 的請求，以及它收到的 app-server 通知。 |
|
||||
|
||||
Codex runtime v1 不支援：
|
||||
|
||||
| 介面 | V1 邊界 | 未來路徑 |
|
||||
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| 原生工具引數變更 | Codex 原生 pre-tool hooks 可以封鎖，但 OpenClaw 不會重寫 Codex 原生工具引數。 | 需要 Codex hook/schema 支援替換工具輸入。 |
|
||||
| 可編輯的 Codex 原生 transcript 歷史 | Codex 擁有標準原生對話串歷史。OpenClaw 擁有鏡像並可投影未來內容，但不應變更不受支援的內部資料。 | 如果需要原生對話串手術，請新增明確的 Codex app-server API。 |
|
||||
| Codex 原生工具記錄的 `tool_result_persist` | 該 hook 會轉換 OpenClaw 擁有的 transcript 寫入，而不是 Codex 原生工具記錄。 | 可以鏡像已轉換的記錄，但標準重寫需要 Codex 支援。 |
|
||||
| 豐富的原生 Compaction 中繼資料 | OpenClaw 會觀察 Compaction 開始與完成，但不會收到穩定的保留/丟棄清單、token delta 或摘要承載。 | 需要更豐富的 Codex Compaction 事件。 |
|
||||
| Compaction 介入 | 目前 OpenClaw Compaction hooks 在 Codex 模式中屬於通知層級。 | 如果 Plugin 需要否決或重寫原生 Compaction，請新增 Codex pre/post Compaction hooks。 |
|
||||
| 逐位元組模型 API 請求捕捉 | OpenClaw 可以捕捉 app-server 請求與通知，但 Codex core 會在內部建構最終 OpenAI API 請求。 | 需要 Codex model-request 追蹤事件或偵錯 API。 |
|
||||
| 表面 | V1 邊界 | 未來路徑 |
|
||||
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| 原生工具引數變更 | Codex 原生工具前置鉤子可以封鎖，但 OpenClaw 不會重寫 Codex 原生工具引數。 | 需要 Codex 鉤子／架構支援替換工具輸入。 |
|
||||
| 可編輯的 Codex 原生逐字稿歷史 | Codex 擁有標準原生對話串歷史。OpenClaw 擁有鏡像並可投射未來內容脈絡，但不應變更不受支援的內部項目。 | 如果需要原生對話串手術，請新增明確的 Codex app-server API。 |
|
||||
| Codex 原生工具記錄的 `tool_result_persist` | 該鉤子會轉換 OpenClaw 擁有的逐字稿寫入，而非 Codex 原生工具記錄。 | 可以鏡像轉換後的記錄，但標準重寫需要 Codex 支援。 |
|
||||
| 豐富的原生 Compaction 中繼資料 | OpenClaw 會觀察 Compaction 開始與完成，但不會收到穩定的保留／捨棄清單、權杖差異或摘要承載資料。 | 需要更豐富的 Codex Compaction 事件。 |
|
||||
| Compaction 介入 | 目前在 Codex 模式中，OpenClaw Compaction 鉤子屬於通知層級。 | 如果 plugins 需要否決或重寫原生 Compaction，請新增 Codex Compaction 前置／後置鉤子。 |
|
||||
| 逐位元組模型 API 請求擷取 | OpenClaw 可以擷取 app-server 請求與通知，但 Codex 核心會在內部建構最終 OpenAI API 請求。 | 需要 Codex 模型請求追蹤事件或除錯 API。 |
|
||||
|
||||
## 工具、媒體與 Compaction
|
||||
|
||||
Codex harness 只會變更低階的嵌入式代理執行器。
|
||||
Codex harness 只會變更低階嵌入式代理執行器。
|
||||
|
||||
OpenClaw 仍會建構工具清單，並從 harness 接收動態工具結果。
|
||||
文字、圖片、影片、音樂、TTS、核准，以及訊息工具輸出
|
||||
會繼續透過一般 OpenClaw 傳遞路徑。
|
||||
OpenClaw 仍會建構工具清單，並從 harness 接收動態工具結果。文字、影像、影片、音樂、TTS、核准與訊息工具輸出會繼續透過一般 OpenClaw 傳遞路徑。
|
||||
|
||||
原生 hook 轉送刻意保持泛用，但 v1 支援合約
|
||||
僅限於 OpenClaw 測試的 Codex 原生工具與權限路徑。在
|
||||
Codex runtime 中，這包含 shell、patch 和 MCP `PreToolUse`、
|
||||
`PostToolUse` 與 `PermissionRequest` 承載。不要假設每個未來的
|
||||
Codex hook 事件都是 OpenClaw Plugin 介面，除非 runtime 合約明確命名它。
|
||||
原生鉤子轉送刻意保持通用，但 v1 支援合約僅限於 OpenClaw 測試過的 Codex 原生工具與權限路徑。在 Codex runtime 中，這包括 shell、patch，以及 MCP `PreToolUse`、`PostToolUse` 和 `PermissionRequest` 承載資料。在 runtime 合約明確命名前，請勿假設每個未來 Codex 鉤子事件都是 OpenClaw Plugin 表面。
|
||||
|
||||
對於 `PermissionRequest`，只有在政策做出決定時，OpenClaw 才會回傳明確允許或拒絕決策。
|
||||
沒有決策的結果不是允許。Codex 會將它視為沒有
|
||||
hook 決策，並落入其自身 guardian 或使用者核准路徑。
|
||||
對於 `PermissionRequest`，OpenClaw 只會在政策作出判斷時回傳明確的允許或拒絕決策。沒有決策的結果不是允許。Codex 會將其視為沒有鉤子決策，並落入自己的 guardian 或使用者核准路徑。
|
||||
|
||||
當 Codex 將 `_meta.codex_approval_kind` 標記為
|
||||
`"mcp_tool_call"` 時，Codex MCP 工具核准徵求會透過 OpenClaw 的 Plugin
|
||||
核准流程路由。Codex `request_user_input` 提示會傳回
|
||||
來源聊天，而下一則已佇列的後續訊息會回答該原生
|
||||
伺服器請求，而不是被導向為額外內容。其他 MCP 徵求
|
||||
請求仍會以關閉方式失敗。
|
||||
當 Codex 將 `_meta.codex_approval_kind` 標記為 `"mcp_tool_call"` 時，Codex MCP 工具核准請求會透過 OpenClaw 的 Plugin 核准流程路由。Codex `request_user_input` 提示會傳回原始聊天，而下一則排隊的後續訊息會回答該原生伺服器請求，而不是被導向為額外內容脈絡。其他 MCP 請求仍會失敗關閉。
|
||||
|
||||
作用中執行佇列導向會對應到 Codex app-server `turn/steer`。使用預設的 `messages.queue.mode: "steer"` 時，OpenClaw 會在設定的安靜視窗內批次處理排入佇列的聊天訊息，並依抵達順序將它們作為一個 `turn/steer` 請求送出。舊版 `queue` 模式會送出個別的 `turn/steer` 請求。Codex 審查和手動 Compaction 回合可能會拒絕同一回合導向，在這種情況下，若所選模式允許後援，OpenClaw 會使用後續佇列。請參閱[導向佇列](/zh-TW/concepts/queue-steering)。
|
||||
作用中執行佇列導向會對應到 Codex app-server `turn/steer`。使用預設 `messages.queue.mode: "steer"` 時，OpenClaw 會在已設定的靜默視窗內批次處理排隊的聊天訊息，並依抵達順序將它們作為一個 `turn/steer` 請求傳送。舊版 `queue` 模式會傳送個別 `turn/steer` 請求。Codex 審查與手動 Compaction 回合可能會拒絕同回合導向，在這種情況下，當所選模式允許備援時，OpenClaw 會使用後續佇列。請參閱[導向佇列](/zh-TW/concepts/queue-steering)。
|
||||
|
||||
當所選模型使用 Codex harness 時，原生執行緒 Compaction 會委派給 Codex app-server。OpenClaw 會保留轉錄鏡像，用於頻道歷史、搜尋、`/new`、`/reset`，以及日後切換模型或 harness。鏡像包含使用者提示、最終助理文字，以及 app-server 發出時的輕量 Codex 推理或計畫記錄。目前，OpenClaw 只會記錄原生 Compaction 的開始與完成訊號。它尚未公開人類可讀的 Compaction 摘要，或可稽核的清單來列出 Codex 在 Compaction 後保留了哪些項目。
|
||||
當所選模型使用 Codex harness 時，原生對話串 Compaction 會委派給 Codex app-server。OpenClaw 會保留逐字稿鏡像，用於頻道歷史、搜尋、`/new`、`/reset`，以及未來的模型或 harness 切換。鏡像包含使用者提示、最終助理文字，以及 app-server 發出時的輕量 Codex 推理或計畫記錄。目前，OpenClaw 只記錄原生 Compaction 開始與完成訊號。它尚未公開人類可讀的 Compaction 摘要，也尚未提供可稽核的清單來顯示 Codex 在 Compaction 後保留了哪些項目。
|
||||
|
||||
因為 Codex 擁有標準原生執行緒，`tool_result_persist` 目前不會重寫 Codex 原生工具結果記錄。它只會在 OpenClaw 寫入由 OpenClaw 擁有的工作階段轉錄工具結果時套用。
|
||||
因為 Codex 擁有標準原生對話串，`tool_result_persist` 目前不會重寫 Codex 原生工具結果記錄。它只會在 OpenClaw 寫入 OpenClaw 擁有的工作階段逐字稿工具結果時套用。
|
||||
|
||||
媒體生成不需要 PI。圖片、影片、音樂、PDF、TTS 和媒體理解會繼續使用相符的供應商/模型設定，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。
|
||||
媒體生成不需要 PI。影像、影片、音樂、PDF、TTS 與媒體理解會繼續使用相符的供應商／模型設定，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。
|
||||
|
||||
## 疑難排解
|
||||
|
||||
**Codex 未以一般 `/model` 供應商顯示：** 對新組態而言這是預期行為。請選取具有 `agentRuntime.id: "codex"` 的 `openai/gpt-*` 模型（或舊版 `codex/*` 參照），啟用 `plugins.entries.codex.enabled`，並檢查 `plugins.allow` 是否排除了 `codex`。
|
||||
**Codex 未顯示為一般 `/model` 供應商：** 對新設定而言，這是預期行為。選取具有 `agentRuntime.id: "codex"` 的 `openai/gpt-*` 模型（或舊版 `codex/*` 參照），啟用 `plugins.entries.codex.enabled`，並檢查 `plugins.allow` 是否排除 `codex`。
|
||||
|
||||
**OpenClaw 使用 PI 而不是 Codex：** 當沒有 Codex harness 宣告執行時，`agentRuntime.id: "auto"` 仍可使用 PI 作為相容性後端。測試時請設定 `agentRuntime.id: "codex"` 以強制選取 Codex。現在，強制 Codex runtime 會失敗，而不是回退到 PI，除非你明確設定 `agentRuntime.fallback: "pi"`。一旦選取 Codex app-server，其失敗會直接呈現，不需要額外的後援組態。
|
||||
**OpenClaw 使用 PI 而非 Codex：** 當沒有 Codex harness 宣告該次執行時，`agentRuntime.id: "auto"` 仍可使用 PI 作為相容性後端。測試時請設定 `agentRuntime.id: "codex"` 以強制選取 Codex。除非你明確設定 `agentRuntime.fallback: "pi"`，否則強制 Codex runtime 現在會失敗，而不是退回 PI。一旦選取 Codex app-server，其失敗會直接浮現，不需要額外的備援設定。
|
||||
|
||||
**app-server 被拒絕：** 請升級 Codex，讓 app-server 交握回報 `0.125.0` 或更新版本。同版本預發行版或附加建置尾碼的版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，都會被拒絕，因為 OpenClaw 測試的是穩定版 `0.125.0` 協定下限。
|
||||
**app-server 被拒絕：** 升級 Codex，讓 app-server 交握回報版本 `0.125.0` 或更新版本。相同版本的預發布版本或帶有建置後綴的版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，會被拒絕，因為穩定的 `0.125.0` 協定下限才是 OpenClaw 測試的目標。
|
||||
|
||||
**模型探索速度很慢：** 請降低 `plugins.entries.codex.config.discovery.timeoutMs`，或停用探索。
|
||||
**模型探索速度很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` 或停用探索。
|
||||
|
||||
**WebSocket 傳輸立即失敗：** 請檢查 `appServer.url`、`authToken`，以及遠端 app-server 是否使用相同的 Codex app-server 協定版本。
|
||||
**WebSocket 傳輸立即失敗：** 檢查 `appServer.url`、`authToken`，以及遠端 app-server 是否使用相同的 Codex app-server 協定版本。
|
||||
|
||||
**非 Codex 模型使用 PI：** 這是預期行為，除非你為該代理程式強制設定了 `agentRuntime.id: "codex"`，或選取了舊版 `codex/*` 參照。一般 `openai/gpt-*` 和其他供應商參照在 `auto` 模式下會維持在其正常供應商路徑。如果你強制設定 `agentRuntime.id: "codex"`，該代理程式的每個嵌入式回合都必須是 Codex 支援的 OpenAI 模型。
|
||||
**非 Codex 模型使用 PI：** 除非你為該代理強制設定 `agentRuntime.id: "codex"`，或選取舊版 `codex/*` 參照，否則這是預期行為。一般 `openai/gpt-*` 和其他供應商參照在 `auto` 模式中會留在其一般供應商路徑上。如果你強制設定 `agentRuntime.id: "codex"`，該代理的每個嵌入式回合都必須是 Codex 支援的 OpenAI 模型。
|
||||
|
||||
**Computer Use 已安裝但工具未執行：** 請從新的工作階段執行 `/codex computer-use status`。如果工具回報 `Native hook relay unavailable`，請使用 `/new` 或 `/reset`；如果問題持續，請重新啟動 Gateway 以清除過時的原生 hook 註冊。如果 `computer-use.list_apps` 逾時，請重新啟動 Codex Computer Use 或 Codex Desktop，然後重試。
|
||||
**Computer Use 已安裝但工具未執行：** 從新的工作階段檢查 `/codex computer-use status`。如果工具回報 `Native hook relay unavailable`，請使用 `/new` 或 `/reset`；如果仍然存在，請重新啟動 gateway 以清除過期的原生鉤子註冊。如果 `computer-use.list_apps` 逾時，請重新啟動 Codex Computer Use 或 Codex Desktop，然後重試。
|
||||
|
||||
## 相關內容
|
||||
## 相關
|
||||
|
||||
- [代理程式 harness Plugin](/zh-TW/plugins/sdk-agent-harness)
|
||||
- [代理程式 runtime](/zh-TW/concepts/agent-runtimes)
|
||||
- [代理 harness plugins](/zh-TW/plugins/sdk-agent-harness)
|
||||
- [代理 runtimes](/zh-TW/concepts/agent-runtimes)
|
||||
- [模型供應商](/zh-TW/concepts/model-providers)
|
||||
- [OpenAI 供應商](/zh-TW/providers/openai)
|
||||
- [狀態](/zh-TW/cli/status)
|
||||
- [Plugin hook](/zh-TW/plugins/hooks)
|
||||
- [Plugin 鉤子](/zh-TW/plugins/hooks)
|
||||
- [組態參考](/zh-TW/gateway/configuration-reference)
|
||||
- [測試](/zh-TW/help/testing-live#live-codex-app-server-harness-smoke)
|
||||
|
||||
@ -1,38 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- 新增或修改 Skills
|
||||
- 變更技能門控、允許清單或載入規則
|
||||
- 了解技能優先順序與快照行為
|
||||
- 變更 Skills 閘控、允許清單或載入規則
|
||||
- 了解 Skills 優先順序與快照行為
|
||||
sidebarTitle: Skills
|
||||
summary: Skills：受管理型與工作區、門控規則、代理程式允許清單與設定串接
|
||||
summary: Skills：受管理與工作區、閘門規則、代理程式允許清單與設定接線
|
||||
title: Skills
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T09:36:15Z"
|
||||
generated_at: "2026-04-30T20:05:43Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d7dd17f52119bf0a0bb197025070abb68f7667a7d22c3d5fa6ef2f666110a45a
|
||||
source_hash: b58d690786756bd3539940aae9f2abcb8a497798ed7b6afeb5e6d6e255fcf257
|
||||
source_path: tools/skills.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw 使用與 **[AgentSkills](https://agentskills.io) 相容**的 Skills 資料夾，教導代理如何使用工具。每個 Skills 都是一個目錄，其中包含帶有 YAML frontmatter 和指示的 `SKILL.md`。OpenClaw 會載入內建 Skills 加上選用的本機覆寫，並在載入時根據環境、設定和二進位檔是否存在進行篩選。
|
||||
OpenClaw 使用與 **[AgentSkills](https://agentskills.io) 相容**的技能資料夾來教導代理如何使用工具。每個技能都是一個目錄，內含具有 YAML frontmatter 和指令的 `SKILL.md`。OpenClaw 會載入內建技能以及選用的本機覆寫，並在載入時根據環境、設定和二進位檔是否存在進行篩選。
|
||||
|
||||
## 位置與優先順序
|
||||
|
||||
OpenClaw 會從下列來源載入 Skills，**優先順序由高到低**：
|
||||
OpenClaw 會從這些來源載入技能，**優先順序由高到低**：
|
||||
|
||||
| # | 來源 | 路徑 |
|
||||
| --- | --------------------- | -------------------------------- |
|
||||
| 1 | 工作區 Skills | `<workspace>/skills` |
|
||||
| 2 | 專案代理 Skills | `<workspace>/.agents/skills` |
|
||||
| 3 | 個人代理 Skills | `~/.agents/skills` |
|
||||
| 4 | 受管理/本機 Skills | `~/.openclaw/skills` |
|
||||
| 5 | 內建 Skills | 隨安裝提供 |
|
||||
| 6 | 額外 Skills 資料夾 | `skills.load.extraDirs` (設定) |
|
||||
| 1 | 工作區技能 | `<workspace>/skills` |
|
||||
| 2 | 專案代理技能 | `<workspace>/.agents/skills` |
|
||||
| 3 | 個人代理技能 | `~/.agents/skills` |
|
||||
| 4 | 受管理/本機技能 | `~/.openclaw/skills` |
|
||||
| 5 | 內建技能 | 隨安裝提供 |
|
||||
| 6 | 額外技能資料夾 | `skills.load.extraDirs`（設定） |
|
||||
|
||||
如果 Skills 名稱衝突，優先順序最高的來源勝出。
|
||||
如果技能名稱衝突，優先順序最高的來源會勝出。
|
||||
|
||||
## 每代理與共用 Skills
|
||||
Codex CLI 原生的 `$CODEX_HOME/skills` 目錄不是 OpenClaw 的技能根目錄之一。在 Codex harness 模式中，本機 app-server 啟動會使用每個代理隔離的 Codex home，因此不會隱含載入個人的 Codex CLI 技能。使用 `openclaw migrate codex --dry-run` 盤點它們，並使用 `openclaw migrate codex` 透過互動式核取方塊提示選擇技能目錄，再將它們複製到目前的 OpenClaw 代理工作區。若要非互動式執行，請針對要複製的精確技能重複使用 `--skill <name>`。
|
||||
|
||||
## 每代理與共享技能
|
||||
|
||||
在**多代理**設定中，每個代理都有自己的工作區：
|
||||
|
||||
@ -41,18 +43,14 @@ OpenClaw 會從下列來源載入 Skills，**優先順序由高到低**：
|
||||
| 每代理 | `<workspace>/skills` | 僅該代理 |
|
||||
| 專案代理 | `<workspace>/.agents/skills` | 僅該工作區的代理 |
|
||||
| 個人代理 | `~/.agents/skills` | 該機器上的所有代理 |
|
||||
| 共用受管理/本機 | `~/.openclaw/skills` | 該機器上的所有代理 |
|
||||
| 共用額外目錄 | `skills.load.extraDirs` (最低優先順序) | 該機器上的所有代理 |
|
||||
| 共享受管理/本機 | `~/.openclaw/skills` | 該機器上的所有代理 |
|
||||
| 共享額外目錄 | `skills.load.extraDirs`（最低優先順序） | 該機器上的所有代理 |
|
||||
|
||||
同名出現在多個位置 → 優先順序最高的來源勝出。工作區優先於
|
||||
專案代理，專案代理優先於個人代理，個人代理優先於受管理/本機，受管理/本機優先於內建，
|
||||
內建優先於額外目錄。
|
||||
多個位置有相同名稱 → 優先順序最高的來源會勝出。工作區勝過專案代理，勝過個人代理，勝過受管理/本機，勝過內建，勝過額外目錄。
|
||||
|
||||
## 代理 Skills 允許清單
|
||||
## 代理技能允許清單
|
||||
|
||||
Skills **位置**和 Skills **可見性**是分開的控制項。
|
||||
位置/優先順序決定同名 Skills 的哪個副本勝出；代理
|
||||
允許清單決定代理實際可以使用哪些 Skills。
|
||||
技能**位置**和技能**可見性**是分開的控制項。位置/優先順序決定同名技能的哪個副本勝出；代理允許清單決定代理實際上可以使用哪些技能。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -61,9 +59,9 @@ Skills **位置**和 Skills **可見性**是分開的控制項。
|
||||
skills: ["github", "weather"],
|
||||
},
|
||||
list: [
|
||||
{ id: "writer" }, // 繼承 github、weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // 取代預設值
|
||||
{ id: "locked-down", skills: [] }, // 沒有 Skills
|
||||
{ id: "writer" }, // inherits github, weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
|
||||
{ id: "locked-down", skills: [] }, // no skills
|
||||
],
|
||||
},
|
||||
}
|
||||
@ -71,68 +69,56 @@ Skills **位置**和 Skills **可見性**是分開的控制項。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="允許清單規則">
|
||||
- 省略 `agents.defaults.skills` 時，預設不限制 Skills。
|
||||
- 省略 `agents.list[].skills` 時，繼承 `agents.defaults.skills`。
|
||||
- 設定 `agents.list[].skills: []` 表示沒有 Skills。
|
||||
- 省略 `agents.defaults.skills`，預設即可不限制技能。
|
||||
- 省略 `agents.list[].skills` 以繼承 `agents.defaults.skills`。
|
||||
- 設定 `agents.list[].skills: []` 表示沒有技能。
|
||||
- 非空的 `agents.list[].skills` 清單是該代理的**最終**集合，不會與預設值合併。
|
||||
- 有效允許清單會套用於提示建構、Skills 斜線命令探索、沙箱同步，以及 Skills 快照。
|
||||
|
||||
- 有效的允許清單會套用於提示建構、技能 slash-command 探索、sandbox 同步和技能快照。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Plugin 與 Skills
|
||||
## Plugin 與技能
|
||||
|
||||
Plugin 可以在 `openclaw.plugin.json` 中列出 `skills` 目錄來隨附自己的 Skills（路徑相對於 Plugin 根目錄）。Plugin 啟用時會載入 Plugin Skills。這適合放置工具專用的操作指南：內容太長不適合放在工具描述中，但只要 Plugin 已安裝就應該可用。例如，瀏覽器 Plugin 會隨附 `browser-automation` Skills，用於多步驟瀏覽器控制。
|
||||
Plugin 可以透過在 `openclaw.plugin.json` 中列出 `skills` 目錄來隨附自己的技能（路徑相對於 Plugin 根目錄）。Plugin 啟用時會載入 Plugin 技能。這是放置工具專用操作指南的正確位置，適合那些對工具描述來說太長、但只要 Plugin 已安裝就應可使用的內容，例如瀏覽器 Plugin 會提供 `browser-automation` 技能，用於多步驟瀏覽器控制。
|
||||
|
||||
Plugin Skills 目錄會合併到與 `skills.load.extraDirs` 相同的低優先順序路徑，因此同名的內建、受管理、代理或工作區 Skills 會覆寫它們。你可以透過 Plugin 設定項目上的 `metadata.openclaw.requires.config` 控制它們的啟用條件。
|
||||
Plugin 技能目錄會合併到與 `skills.load.extraDirs` 相同的低優先順序路徑，因此同名的內建、受管理、代理或工作區技能會覆寫它們。你可以透過 Plugin 設定項目上的 `metadata.openclaw.requires.config` 來控管它們。
|
||||
|
||||
請參閱 [Plugin](/zh-TW/tools/plugin) 了解探索/設定，並參閱 [工具](/zh-TW/tools) 了解這些 Skills 所教導的工具介面。
|
||||
請參閱 [Plugin](/zh-TW/tools/plugin) 了解探索/設定，並參閱[工具](/zh-TW/tools)了解這些技能所教導的工具介面。
|
||||
|
||||
## Skill Workshop
|
||||
|
||||
選用且實驗性的 **Skill Workshop** Plugin 可以從代理工作期間觀察到的可重用程序，建立或更新工作區 Skills。它預設為停用，必須透過 `plugins.entries.skill-workshop` 明確啟用。
|
||||
選用且實驗性的 **Skill Workshop** Plugin 可以根據代理工作期間觀察到的可重複使用程序，建立或更新工作區技能。它預設停用，且必須透過 `plugins.entries.skill-workshop` 明確啟用。
|
||||
|
||||
Skill Workshop 只會寫入 `<workspace>/skills`，會掃描產生的內容，支援待核准或自動安全寫入，隔離不安全提案，並在成功寫入後重新整理 Skills 快照，讓新 Skills 無需重新啟動 Gateway 即可使用。
|
||||
Skill Workshop 只會寫入 `<workspace>/skills`、掃描產生的內容、支援待核准或自動安全寫入、隔離不安全的提案，並在成功寫入後重新整理技能快照，讓新技能無需重新啟動 Gateway 即可使用。
|
||||
|
||||
可用於像是 _「下次，驗證 GIF 歸屬」_ 這類修正，或是媒體 QA 檢查清單等得來不易的工作流程。請先從待核准開始；只有在受信任的工作區中檢閱其提案後，才使用自動寫入。完整指南：[Skill Workshop Plugin](/zh-TW/plugins/skill-workshop)。
|
||||
可將它用於像是 _「下次驗證 GIF 署名」_ 這類修正，或像媒體 QA 檢查清單這類得來不易的工作流程。先從待核准開始；只有在檢閱其提案後，才在受信任的工作區中使用自動寫入。完整指南：[Skill Workshop Plugin](/zh-TW/plugins/skill-workshop)。
|
||||
|
||||
## ClawHub（安裝與同步）
|
||||
|
||||
[ClawHub](https://clawhub.ai) 是 OpenClaw 的公開 Skills 登錄庫。
|
||||
使用原生 `openclaw skills` 命令進行探索/安裝/更新，或使用獨立的 `clawhub` CLI 進行發布/同步工作流程。完整指南：
|
||||
[ClawHub](/zh-TW/tools/clawhub)。
|
||||
[ClawHub](https://clawhub.ai) 是 OpenClaw 的公共技能登錄庫。使用原生 `openclaw skills` 命令進行探索/安裝/更新，或使用獨立的 `clawhub` CLI 進行發布/同步工作流程。完整指南：[ClawHub](/zh-TW/tools/clawhub)。
|
||||
|
||||
| 動作 | 命令 |
|
||||
| ---------------------------------- | -------------------------------------- |
|
||||
| 將 Skills 安裝到工作區 | `openclaw skills install <skill-slug>` |
|
||||
| 更新所有已安裝的 Skills | `openclaw skills update --all` |
|
||||
| 將技能安裝到工作區 | `openclaw skills install <skill-slug>` |
|
||||
| 更新所有已安裝技能 | `openclaw skills update --all` |
|
||||
| 同步（掃描 + 發布更新） | `clawhub sync --all` |
|
||||
|
||||
原生 `openclaw skills install` 會安裝到作用中工作區的
|
||||
`skills/` 目錄。獨立的 `clawhub` CLI 也會安裝到目前工作目錄下的
|
||||
`./skills`（或退回到已設定的 OpenClaw 工作區）。OpenClaw 會在下一個工作階段將其識別為
|
||||
`<workspace>/skills`。
|
||||
已設定的 Skills 根目錄也支援一層分組，例如
|
||||
`skills/<group>/<skill>/SKILL.md`，因此相關的第三方 Skills 可以放在共用資料夾下，而不需要廣泛遞迴掃描。
|
||||
原生 `openclaw skills install` 會安裝到作用中工作區的 `skills/` 目錄。獨立的 `clawhub` CLI 也會安裝到目前工作目錄下的 `./skills`（或退回使用已設定的 OpenClaw 工作區）。OpenClaw 會在下一個工作階段將其視為 `<workspace>/skills`。已設定的技能根目錄也支援一層分組，例如 `skills/<group>/<skill>/SKILL.md`，因此相關的第三方技能可以保留在共享資料夾下，而不需要廣泛遞迴掃描。
|
||||
|
||||
ClawHub Skills 頁面會在安裝前顯示最新的安全掃描狀態，並提供 VirusTotal、ClawScan 和靜態分析的掃描器詳細頁面。
|
||||
`openclaw skills install <slug>` 仍然只是安裝路徑；發布者會透過 ClawHub 儀表板或
|
||||
`clawhub skill rescan <slug>` 處理誤判。
|
||||
ClawHub 技能頁面會在安裝前顯示最新的安全掃描狀態，並提供 VirusTotal、ClawScan 和靜態分析的掃描器詳細頁面。`openclaw skills install <slug>` 仍然只是安裝路徑；發布者會透過 ClawHub 儀表板或 `clawhub skill rescan <slug>` 從誤判中復原。
|
||||
|
||||
## 安全性
|
||||
|
||||
<Warning>
|
||||
將第三方 Skills 視為**不受信任的程式碼**。啟用前請先閱讀。
|
||||
對於不受信任的輸入和有風險的工具，偏好使用沙箱執行。請參閱
|
||||
[沙箱](/zh-TW/gateway/sandboxing) 了解代理端控制項。
|
||||
將第三方技能視為**不受信任的程式碼**。啟用前先閱讀它們。對不受信任的輸入和高風險工具，偏好使用 sandbox 執行。請參閱 [Sandboxing](/zh-TW/gateway/sandboxing) 了解代理端控制項。
|
||||
</Warning>
|
||||
|
||||
- 工作區和額外目錄的 Skills 探索只接受解析後 realpath 仍位於已設定根目錄內的 Skills 根目錄和 `SKILL.md` 檔案。
|
||||
- Gateway 支援的 Skills 相依項安裝（`skills.install`、上手流程，以及 Skills 設定 UI）會在執行安裝器中繼資料前執行內建的危險程式碼掃描器。除非呼叫端明確設定危險覆寫，否則預設會封鎖 `critical` 發現；可疑發現仍只會警告。
|
||||
- `openclaw skills install <slug>` 不同，它會將 ClawHub Skills 資料夾下載到工作區，且不使用上述的安裝器中繼資料路徑。
|
||||
- `skills.entries.*.env` 和 `skills.entries.*.apiKey` 會將祕密注入該代理回合的**主機**程序（不是沙箱）。請避免將祕密放入提示和記錄中。
|
||||
- 工作區和額外目錄的技能探索只接受解析後 realpath 仍位於已設定根目錄內的技能根目錄和 `SKILL.md` 檔案。
|
||||
- Gateway 支援的技能依賴安裝（`skills.install`、onboarding，以及 Skills 設定 UI）會在執行安裝器 metadata 之前執行內建的危險程式碼掃描器。除非呼叫端明確設定危險覆寫，否則 `critical` 發現會預設封鎖；可疑發現仍然只會警告。
|
||||
- `openclaw skills install <slug>` 不同，它會將 ClawHub 技能資料夾下載到工作區，且不使用上述安裝器 metadata 路徑。
|
||||
- `skills.entries.*.env` 和 `skills.entries.*.apiKey` 會將祕密注入該代理回合的**主機**程序（不是 sandbox）。請避免讓祕密出現在提示和日誌中。
|
||||
|
||||
若要了解更完整的威脅模型和檢查清單，請參閱 [安全性](/zh-TW/gateway/security)。
|
||||
如需更完整的威脅模型與檢查清單，請參閱[安全性](/zh-TW/gateway/security)。
|
||||
|
||||
## SKILL.md 格式
|
||||
|
||||
@ -145,33 +131,32 @@ description: Generate or edit images via a provider-backed image workflow
|
||||
---
|
||||
```
|
||||
|
||||
OpenClaw 遵循 AgentSkills 規格的版面/意圖。嵌入式代理使用的剖析器僅支援**單行** frontmatter 鍵；
|
||||
`metadata` 應為**單行 JSON 物件**。在指示中使用 `{baseDir}` 來參照 Skills 資料夾路徑。
|
||||
OpenClaw 遵循 AgentSkills 規格的版面配置/意圖。嵌入式代理使用的剖析器只支援**單行** frontmatter 鍵；`metadata` 應該是**單行 JSON 物件**。在指令中使用 `{baseDir}` 來參照技能資料夾路徑。
|
||||
|
||||
### 選用 frontmatter 鍵
|
||||
|
||||
<ParamField path="homepage" type="string">
|
||||
在 macOS Skills UI 中以「網站」顯示的 URL。也支援透過 `metadata.openclaw.homepage` 設定。
|
||||
在 macOS Skills UI 中顯示為「Website」的 URL。也可透過 `metadata.openclaw.homepage` 支援。
|
||||
</ParamField>
|
||||
<ParamField path="user-invocable" type="boolean" default="true">
|
||||
當為 `true` 時，Skills 會公開為使用者斜線命令。
|
||||
為 `true` 時，技能會作為使用者 slash command 公開。
|
||||
</ParamField>
|
||||
<ParamField path="disable-model-invocation" type="boolean" default="false">
|
||||
當為 `true` 時，Skills 會從模型提示中排除（仍可透過使用者呼叫使用）。
|
||||
為 `true` 時，技能會從模型提示中排除（仍可透過使用者呼叫使用）。
|
||||
</ParamField>
|
||||
<ParamField path="command-dispatch" type='"tool"'>
|
||||
設為 `tool` 時，斜線命令會略過模型並直接分派到工具。
|
||||
設為 `tool` 時，slash command 會略過模型並直接分派到工具。
|
||||
</ParamField>
|
||||
<ParamField path="command-tool" type="string">
|
||||
設定 `command-dispatch: tool` 時要呼叫的工具名稱。
|
||||
</ParamField>
|
||||
<ParamField path="command-arg-mode" type='"raw"' default="raw">
|
||||
對於工具分派，將原始 args 字串轉送到工具（不進行核心剖析）。工具會以 `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }` 呼叫。
|
||||
對於工具分派，會將原始 args 字串轉送給工具（不進行核心剖析）。工具會以 `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }` 呼叫。
|
||||
</ParamField>
|
||||
|
||||
## 門控（載入時篩選器）
|
||||
## 閘控（載入時篩選器）
|
||||
|
||||
OpenClaw 會在載入時使用 `metadata`（單行 JSON）篩選 Skills：
|
||||
OpenClaw 會在載入時使用 `metadata`（單行 JSON）篩選技能：
|
||||
|
||||
```markdown
|
||||
---
|
||||
@ -191,28 +176,28 @@ metadata:
|
||||
`metadata.openclaw` 下的欄位：
|
||||
|
||||
<ParamField path="always" type="boolean">
|
||||
當為 `true` 時，一律包含 Skills（略過其他門控）。
|
||||
為 `true` 時，一律包含該技能（略過其他閘控）。
|
||||
</ParamField>
|
||||
<ParamField path="emoji" type="string">
|
||||
macOS Skills UI 使用的選用 emoji。
|
||||
</ParamField>
|
||||
<ParamField path="homepage" type="string">
|
||||
在 macOS Skills UI 中以「網站」顯示的選用 URL。
|
||||
在 macOS Skills UI 中顯示為「Website」的選用 URL。
|
||||
</ParamField>
|
||||
<ParamField path="os" type='"darwin" | "linux" | "win32"' >
|
||||
選用平台清單。如果設定，Skills 只會在那些 OS 上符合資格。
|
||||
選用平台清單。如果設定，技能只會在這些 OS 上符合資格。
|
||||
</ParamField>
|
||||
<ParamField path="requires.bins" type="string[]">
|
||||
每一項都必須存在於 `PATH` 上。
|
||||
每一項都必須存在於 `PATH`。
|
||||
</ParamField>
|
||||
<ParamField path="requires.anyBins" type="string[]">
|
||||
至少一項必須存在於 `PATH` 上。
|
||||
至少一項必須存在於 `PATH`。
|
||||
</ParamField>
|
||||
<ParamField path="requires.env" type="string[]">
|
||||
環境變數必須存在或由設定提供。
|
||||
環境變數必須存在，或在設定中提供。
|
||||
</ParamField>
|
||||
<ParamField path="requires.config" type="string[]">
|
||||
必須為真值的 `openclaw.json` 路徑清單。
|
||||
必須為 truthy 的 `openclaw.json` 路徑清單。
|
||||
</ParamField>
|
||||
<ParamField path="primaryEnv" type="string">
|
||||
與 `skills.entries.<name>.apiKey` 關聯的環境變數名稱。
|
||||
@ -221,19 +206,17 @@ metadata:
|
||||
macOS Skills UI 使用的選用安裝器規格（brew/node/go/uv/download）。
|
||||
</ParamField>
|
||||
|
||||
如果不存在 `metadata.openclaw`，Skills 一律符合資格（除非在設定中停用，或對內建 Skills 被 `skills.allowBundled` 封鎖）。
|
||||
如果不存在 `metadata.openclaw`，該技能一律符合資格（除非在設定中停用，或對內建技能被 `skills.allowBundled` 封鎖）。
|
||||
|
||||
<Note>
|
||||
舊版 `metadata.clawdbot` 區塊在缺少
|
||||
`metadata.openclaw` 時仍會被接受，因此較舊的已安裝 Skills 會保留其相依項門控和安裝器提示。新的和更新後的 Skills 應使用
|
||||
`metadata.openclaw`。
|
||||
當 `metadata.openclaw` 不存在時，仍會接受舊版 `metadata.clawdbot` 區塊，因此較舊的已安裝技能會保留其依賴閘控和安裝器提示。新的和更新後的技能應使用 `metadata.openclaw`。
|
||||
</Note>
|
||||
|
||||
### 沙箱注意事項
|
||||
### Sandboxing 注意事項
|
||||
|
||||
- `requires.bins` 會在 Skills 載入時於**主機**上檢查。
|
||||
- 如果代理已沙箱化，二進位檔也必須存在於**容器內**。請透過 `agents.defaults.sandbox.docker.setupCommand`（或自訂映像）安裝它。`setupCommand` 會在容器建立後執行一次。套件安裝也需要網路輸出、可寫入的根 FS，以及沙箱中的 root 使用者。
|
||||
- 範例：`summarize` Skills（`skills/summarize/SKILL.md`）需要沙箱容器中的 `summarize` CLI 才能在那裡執行。
|
||||
- `requires.bins` 會在技能載入時於**主機**上檢查。
|
||||
- 如果代理已 sandbox，二進位檔也必須存在於**容器內**。請透過 `agents.defaults.sandbox.docker.setupCommand`（或自訂映像檔）安裝它。`setupCommand` 會在容器建立後執行一次。套件安裝也需要網路輸出、可寫入的根 FS，以及 sandbox 中的 root 使用者。
|
||||
- 範例：`summarize` 技能（`skills/summarize/SKILL.md`）需要 sandbox 容器中有 `summarize` CLI 才能在那裡執行。
|
||||
|
||||
### 安裝器規格
|
||||
|
||||
@ -263,25 +246,26 @@ metadata:
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="安裝程式選擇規則">
|
||||
- 如果列出多個安裝程式，Gateway 會挑選單一偏好的選項（可用時為 brew，否則為 node）。
|
||||
- 如果所有安裝程式都是 `download`，OpenClaw 會列出每個項目，讓你可以查看可用的成品。
|
||||
<Accordion title="Installer selection rules">
|
||||
- 如果列出多個安裝程式，Gateway 會選擇單一偏好的選項（可用時使用 brew，否則使用 node）。
|
||||
- 如果所有安裝程式都是 `download`，OpenClaw 會列出每個項目，讓你查看可用的成品。
|
||||
- 安裝程式規格可以包含 `os: ["darwin"|"linux"|"win32"]`，以依平台篩選選項。
|
||||
- Node 安裝會遵循 `openclaw.json` 中的 `skills.install.nodeManager`（預設：npm；選項：npm/pnpm/yarn/bun）。這只會影響 Skills 安裝；Gateway 執行階段仍應使用 Node — 不建議將 Bun 用於 WhatsApp/Telegram。
|
||||
- Gateway 支援的安裝程式選擇由偏好驅動：當安裝規格混合多種類型時，若啟用 `skills.install.preferBrew` 且 `brew` 存在，OpenClaw 會優先使用 Homebrew，接著是 `uv`，再來是設定的 node manager，然後才是其他後備選項，例如 `go` 或 `download`。
|
||||
- Node 安裝會遵循 `openclaw.json` 中的 `skills.install.nodeManager`（預設：npm；選項：npm/pnpm/yarn/bun）。這只會影響 skill 安裝；Gateway 執行階段仍應使用 Node，WhatsApp/Telegram 不建議使用 Bun。
|
||||
- 由 Gateway 支援的安裝程式選擇是偏好導向的：當安裝規格混合多種類型時，若已啟用 `skills.install.preferBrew` 且 `brew` 存在，OpenClaw 會優先使用 Homebrew，接著是 `uv`，再來是已設定的 node 管理器，最後才是其他備用選項，例如 `go` 或 `download`。
|
||||
- 如果每個安裝規格都是 `download`，OpenClaw 會顯示所有下載選項，而不是收斂成單一偏好的安裝程式。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="各安裝程式詳細資料">
|
||||
- **Go 安裝：**如果缺少 `go` 且 `brew` 可用，Gateway 會先透過 Homebrew 安裝 Go，並在可行時將 `GOBIN` 設為 Homebrew 的 `bin`。
|
||||
- **下載安裝：**`url`（必要）、`archive`（`tar.gz` | `tar.bz2` | `zip`）、`extract`（預設：偵測到封存檔時自動）、`stripComponents`、`targetDir`（預設：`~/.openclaw/tools/<skillKey>`）。
|
||||
<Accordion title="Per-installer details">
|
||||
- **Go 安裝：**如果缺少 `go` 且 `brew` 可用，Gateway 會先透過 Homebrew 安裝 Go，並在可能時將 `GOBIN` 設為 Homebrew 的 `bin`。
|
||||
- **下載安裝：**`url`（必填）、`archive`（`tar.gz` | `tar.bz2` | `zip`）、`extract`（預設：偵測到封存檔時自動）、`stripComponents`、`targetDir`（預設：`~/.openclaw/tools/<skillKey>`）。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 設定覆寫
|
||||
|
||||
可以在 `~/.openclaw/openclaw.json` 的 `skills.entries` 下切換內建與受管理的 Skills，並提供 env 值：
|
||||
內建與受管理的 skills 可以在 `~/.openclaw/openclaw.json` 的
|
||||
`skills.entries` 底下切換，並提供環境值：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -306,34 +290,36 @@ metadata:
|
||||
```
|
||||
|
||||
<ParamField path="enabled" type="boolean">
|
||||
`false` 會停用此 Skill，即使它是內建或已安裝的 Skill。
|
||||
內建的 `coding-agent` Skill 預設不啟用：先設定
|
||||
`skills.entries.coding-agent.enabled: true`，再將其暴露給代理，
|
||||
然後確認 `claude`、`codex`、`opencode` 或 `pi` 其中之一已安裝，
|
||||
且已通過自身 CLI 的驗證。
|
||||
`false` 會停用該 skill，即使它是內建或已安裝的。
|
||||
內建的 `coding-agent` skill 是選擇啟用：先設定
|
||||
`skills.entries.coding-agent.enabled: true`，再將它暴露給代理，
|
||||
然後確認已安裝 `claude`、`codex`、`opencode` 或 `pi` 其中之一，
|
||||
並已針對其自身的 CLI 完成驗證。
|
||||
</ParamField>
|
||||
<ParamField path="apiKey" type='string | { source, provider, id }'>
|
||||
供宣告 `metadata.openclaw.primaryEnv` 的 Skills 使用的便利設定。支援純文字或 SecretRef。
|
||||
供宣告 `metadata.openclaw.primaryEnv` 的 skills 使用的便利設定。支援純文字或 SecretRef。
|
||||
</ParamField>
|
||||
<ParamField path="env" type="Record<string, string>">
|
||||
只有在程序中尚未設定該變數時才會注入。
|
||||
只有在變數尚未於程序中設定時才會注入。
|
||||
</ParamField>
|
||||
<ParamField path="config" type="object">
|
||||
用於自訂各 Skill 欄位的選用容器。自訂鍵必須放在這裡。
|
||||
用於自訂每個 skill 欄位的選用容器。自訂鍵必須放在這裡。
|
||||
</ParamField>
|
||||
<ParamField path="allowBundled" type="string[]">
|
||||
僅適用於**內建** Skills 的選用允許清單。如果設定，只有清單中的內建 Skills 符合資格（不影響受管理/工作區 Skills）。
|
||||
僅適用於**內建** skills 的選用允許清單。如果設定，只有清單中的內建 skills 符合資格（不影響受管理/工作區 skills）。
|
||||
</ParamField>
|
||||
|
||||
如果 Skill 名稱包含連字號，請用引號包住鍵（JSON5 允許帶引號的鍵）。設定鍵預設會比對 **Skill 名稱** — 如果某個 Skill 定義了 `metadata.openclaw.skillKey`，請在 `skills.entries` 下使用該鍵。
|
||||
如果 skill 名稱包含連字號，請為鍵加上引號（JSON5 允許加引號的
|
||||
鍵）。設定鍵預設會符合 **skill 名稱**；如果 skill
|
||||
定義了 `metadata.openclaw.skillKey`，請在 `skills.entries` 底下使用該鍵。
|
||||
|
||||
<Note>
|
||||
若要在 OpenClaw 內進行內建圖片生成/編輯，請使用核心
|
||||
在 OpenClaw 內進行庫存圖片生成/編輯時，請使用核心
|
||||
`image_generate` 工具搭配 `agents.defaults.imageGenerationModel`，
|
||||
而不是內建 Skill。這裡的 Skill 範例適用於自訂或第三方
|
||||
而不是內建 skill。這裡的 skill 範例適用於自訂或第三方
|
||||
工作流程。若要使用原生圖片分析，請使用 `image` 工具搭配
|
||||
`agents.defaults.imageModel`。如果你選擇 `openai/*`、`google/*`、
|
||||
`fal/*` 或其他供應商特定的圖片模型，也請加入該供應商的
|
||||
`fal/*` 或其他供應商特定的圖片模型，也要加入該供應商的
|
||||
驗證/API 金鑰。
|
||||
</Note>
|
||||
|
||||
@ -341,29 +327,35 @@ metadata:
|
||||
|
||||
當代理執行開始時，OpenClaw 會：
|
||||
|
||||
1. 讀取 Skill 中繼資料。
|
||||
1. 讀取 skill 中繼資料。
|
||||
2. 將 `skills.entries.<key>.env` 和 `skills.entries.<key>.apiKey` 套用至 `process.env`。
|
||||
3. 使用**符合資格**的 Skills 建立系統提示。
|
||||
3. 使用**符合資格**的 skills 建立系統提示。
|
||||
4. 在執行結束後還原原始環境。
|
||||
|
||||
環境注入的範圍**限於代理執行**，不是全域 shell 環境。
|
||||
環境注入**僅限於代理執行**，不是全域 shell
|
||||
環境。
|
||||
|
||||
對於內建的 `claude-cli` 後端，OpenClaw 也會將相同的符合資格快照具體化為臨時 Claude Code Plugin，並透過 `--plugin-dir` 傳入。Claude Code 接著可以使用其原生 Skill 解析器，而 OpenClaw 仍掌控優先順序、各代理允許清單、門控，以及 `skills.entries.*` env/API 金鑰注入。其他 CLI 後端只使用提示目錄。
|
||||
對於內建的 `claude-cli` 後端，OpenClaw 也會將同一份
|
||||
符合資格的快照具體化為暫時性的 Claude Code Plugin，並透過
|
||||
`--plugin-dir` 傳遞。Claude Code 接著可以使用其原生 skill 解析器，同時
|
||||
OpenClaw 仍然掌控優先順序、每個代理的允許清單、閘控，以及
|
||||
`skills.entries.*` 環境/API 金鑰注入。其他 CLI 後端只使用
|
||||
提示目錄。
|
||||
|
||||
## 快照與重新整理
|
||||
|
||||
OpenClaw 會在**工作階段開始時**為符合資格的 Skills 建立快照，並在同一工作階段的後續回合重複使用該清單。Skills 或設定的變更會在下一個新工作階段生效。
|
||||
OpenClaw 會在**工作階段開始時**快照符合資格的 skills，並在同一工作階段的後續回合重複使用該清單。對 skills 或設定的變更會在下一個新工作階段生效。
|
||||
|
||||
Skills 可以在工作階段中途於兩種情況下重新整理：
|
||||
Skills 可在兩種情況下於工作階段中途重新整理：
|
||||
|
||||
- Skills 監看器已啟用。
|
||||
- skills 監看器已啟用。
|
||||
- 出現新的符合資格遠端節點。
|
||||
|
||||
可將這視為**熱重新載入**：重新整理後的清單會在下一個代理回合套用。如果該工作階段的有效代理 Skill 允許清單改變，OpenClaw 會重新整理快照，讓可見的 Skills 與目前代理保持一致。
|
||||
把這視為**熱重新載入**：重新整理後的清單會在下一個代理回合被採用。如果該工作階段的有效代理 skill 允許清單發生變更，OpenClaw 會重新整理快照，讓可見的 skills 與目前代理保持一致。
|
||||
|
||||
### Skills 監看器
|
||||
|
||||
預設情況下，OpenClaw 會監看 Skill 資料夾，並在 `SKILL.md` 檔案變更時遞增 Skills 快照。在 `skills.load` 下設定：
|
||||
預設情況下，OpenClaw 會監看 skill 資料夾，並在 `SKILL.md` 檔案變更時提升 skills 快照版本。在 `skills.load` 底下設定：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -378,18 +370,21 @@ Skills 可以在工作階段中途於兩種情況下重新整理：
|
||||
|
||||
### 遠端 macOS 節點（Linux Gateway）
|
||||
|
||||
如果 Gateway 在 Linux 上執行，但有一個允許
|
||||
`system.run` 的 **macOS 節點**已連線（Exec 核准安全性未設為 `deny`），
|
||||
當所需二進位檔存在於該節點上時，OpenClaw 可以將僅限 macOS 的 Skills 視為符合資格。代理應透過 `exec` 工具並搭配 `host=node` 執行這些 Skills。
|
||||
如果 Gateway 在 Linux 上執行，但已連線的 **macOS 節點**允許
|
||||
`system.run`（Exec approvals 安全性未設定為 `deny`），
|
||||
OpenClaw 可以在該節點具備必要二進位檔時，將僅適用於 macOS 的 skills 視為符合資格。代理應透過 `exec` 工具搭配 `host=node` 執行這些 skills。
|
||||
|
||||
這仰賴節點回報其指令支援，以及透過 `system.which` 或 `system.run` 進行 bin 探測。離線節點**不會**讓僅限遠端的 Skills 可見。如果已連線節點停止回應 bin 探測，OpenClaw 會清除其快取的 bin 符合項目，讓代理不再看到目前無法在該處執行的 Skills。
|
||||
這依賴節點回報其命令支援能力，以及透過 `system.which` 或 `system.run` 進行二進位檔探測。離線節點**不會**讓
|
||||
僅限遠端的 skills 可見。如果已連線的節點停止回應二進位檔
|
||||
探測，OpenClaw 會清除其快取的二進位檔符合項目，讓代理不再看到
|
||||
目前無法在那裡執行的 skills。
|
||||
|
||||
## Token 影響
|
||||
|
||||
當 Skills 符合資格時，OpenClaw 會將可用 Skills 的精簡 XML 清單注入系統提示（透過 `pi-coding-agent` 中的 `formatSkillsForPrompt`）。成本是確定性的：
|
||||
當 skills 符合資格時，OpenClaw 會將可用 skills 的精簡 XML 清單注入系統提示（透過 `pi-coding-agent` 中的 `formatSkillsForPrompt`）。成本是確定性的：
|
||||
|
||||
- **基礎開銷**（僅在 ≥1 個 Skill 時）：195 個字元。
|
||||
- **每個 Skill：**97 個字元 + XML 逸出後的 `<name>`、`<description>` 和 `<location>` 值長度。
|
||||
- **基礎開銷**（僅在 ≥1 個 skill 時）：195 個字元。
|
||||
- **每個 skill：**97 個字元 + XML 跳脫後的 `<name>`、`<description>` 和 `<location>` 值長度。
|
||||
|
||||
公式（字元）：
|
||||
|
||||
@ -397,24 +392,27 @@ Skills 可以在工作階段中途於兩種情況下重新整理：
|
||||
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
|
||||
```
|
||||
|
||||
XML 逸出會將 `& < > " '` 展開為實體（`&`、`<` 等），
|
||||
因此增加長度。Token 數量會因模型 tokenizer 而異。粗略的
|
||||
OpenAI 風格估算約為 ~4 字元/token，因此每個 Skill 的 **97 個字元 ≈ 24 個 tokens**，再加上你的實際欄位長度。
|
||||
XML 跳脫會將 `& < > " '` 展開成實體（`&`、`<` 等），
|
||||
增加長度。Token 數量會依模型 tokenizer 而異。粗略的
|
||||
OpenAI 風格估算是約 4 字元/token，因此每個 skill 的 **97 個字元 ≈ 24 個 tokens**，
|
||||
再加上你的實際欄位長度。
|
||||
|
||||
## 受管理 Skills 生命週期
|
||||
## 受管理 skills 生命週期
|
||||
|
||||
OpenClaw 會隨安裝（npm 套件或 OpenClaw.app）提供一組基準 Skills 作為**內建 Skills**。`~/.openclaw/skills` 用於本機覆寫 — 例如，在不變更內建副本的情況下釘選或修補某個 Skill。工作區 Skills 由使用者擁有，並會在名稱衝突時覆寫兩者。
|
||||
OpenClaw 會隨安裝（npm 套件或 OpenClaw.app）提供一組基準 skills 作為**內建 skills**。`~/.openclaw/skills` 用於
|
||||
本機覆寫，例如在不變更內建副本的情況下釘選或修補 skill。
|
||||
工作區 skills 由使用者擁有，且會在名稱衝突時覆寫兩者。
|
||||
|
||||
## 想找更多 Skills？
|
||||
## 想找更多 skills？
|
||||
|
||||
瀏覽 [https://clawhub.ai](https://clawhub.ai)。完整設定
|
||||
結構描述：[Skills 設定](/zh-TW/tools/skills-config)。
|
||||
schema：[Skills 設定](/zh-TW/tools/skills-config)。
|
||||
|
||||
## 相關
|
||||
|
||||
- [ClawHub](/zh-TW/tools/clawhub) — 公共 Skills 登錄庫
|
||||
- [建立 Skills](/zh-TW/tools/creating-skills) — 建立自訂 Skills
|
||||
- [Plugin](/zh-TW/tools/plugin) — Plugin 系統概覽
|
||||
- [Skill Workshop Plugin](/zh-TW/plugins/skill-workshop) — 從代理工作生成 Skills
|
||||
- [Skills 設定](/zh-TW/tools/skills-config) — Skill 設定參考
|
||||
- [斜線指令](/zh-TW/tools/slash-commands) — 所有可用的斜線指令
|
||||
- [ClawHub](/zh-TW/tools/clawhub) — 公開 skills 登錄檔
|
||||
- [建立 skills](/zh-TW/tools/creating-skills) — 建置自訂 skills
|
||||
- [Plugins](/zh-TW/tools/plugin) — plugin 系統概覽
|
||||
- [Skill Workshop plugin](/zh-TW/plugins/skill-workshop) — 從代理工作生成 skills
|
||||
- [Skills 設定](/zh-TW/tools/skills-config) — skill 設定參考
|
||||
- [斜線命令](/zh-TW/tools/slash-commands) — 所有可用的斜線命令
|
||||
|
||||
Loading…
Reference in New Issue
Block a user