Codex harness
原生 Codex Plugin
原生 Codex plugin 支援讓 Codex 模式的 OpenClaw agent 可以在處理 OpenClaw 回合的同一個 Codex thread 內，使用 Codex app-server 自身的 app 與 plugin 能力。
OpenClaw 不會把 Codex plugins 轉譯成合成的 codex_plugin_*
OpenClaw dynamic tools。Plugin 呼叫會保留在原生 Codex transcript 中，而
Codex app-server 負責 app-backed MCP 執行。
請在基礎 Codex harness 可運作後使用本頁。
需求
- 選取的 OpenClaw agent runtime 必須是原生 Codex harness。
plugins.entries.codex.enabled必須為 true。plugins.entries.codex.config.codexPlugins.enabled必須為 true。- V1 僅支援 migration 觀察到在來源 Codex home 中以 source-installed 狀態存在的
openai-curatedplugins。 - 目標 Codex app-server 必須能看到預期的 marketplace、plugin 與 app inventory。
codexPlugins 對 PI runs、一般 OpenAI provider runs、ACP
conversation bindings 或其他 harnesses 沒有作用，因為這些路徑不會建立帶有原生
apps config 的 Codex app-server threads。
快速開始
從來源 Codex home 預覽 migration：
openclaw migrate codex --dry-run
當你希望 migration 在規劃原生 plugin 啟用前檢查來源 app 可存取性時，請使用嚴格的來源 app 驗證：
openclaw migrate codex --dry-run --verify-plugin-apps
當計畫看起來正確時套用 migration：
openclaw migrate apply codex --yes
Migration 會為符合資格的 plugins 寫入明確的 codexPlugins entries，並為選取的
plugins 呼叫 Codex app-server plugin/install。典型的 migrated config
如下：
{
plugins: {
entries: {
codex: {
enabled: true,
config: {
codexPlugins: {
enabled: true,
allow_destructive_actions: true,
plugins: {
"google-calendar": {
enabled: true,
marketplaceName: "openai-curated",
pluginName: "google-calendar",
},
},
},
},
},
},
},
}
變更 codexPlugins 後，請使用 /new、/reset，或重新啟動 gateway，讓後續的
Codex harness sessions 以更新後的 app set 啟動。
原生 plugin 設定如何運作
整合有三種獨立狀態：
- 已安裝：Codex 在目標 app-server runtime 中有本機 plugin bundle。
- 已啟用：OpenClaw config 願意讓該 plugin 可供 Codex harness 回合使用。
- 可存取：Codex app-server 確認該 plugin 的 app entries 可供作用中帳號使用，並且可對應到 migrated plugin identity。
Migration 是持久化的安裝/資格步驟。規劃期間，OpenClaw 會讀取來源 Codex
plugin/read details，並檢查來源 Codex app-server account response
是否為 ChatGPT subscription account。非 ChatGPT 或缺少 account responses
時，app-backed plugins 會以 codex_subscription_required 跳過。預設情況下，
migration 不會呼叫來源 app/list；通過 account gate 的 app-backed source plugins
會在沒有來源 app 可存取性驗證的情況下被規劃，而 account lookup transport
失敗會以 codex_account_unavailable 跳過。使用 --verify-plugin-apps 時，
migration 會取得新的來源 app/list snapshot，並要求每個 owned app
都必須存在、已啟用且可存取，才會規劃原生啟用。在該模式中，account lookup
transport 失敗會落到來源 app-inventory gate。Runtime app inventory
是 migration 後的目標 session 可存取性檢查。接著 Codex harness session setup
會為已啟用且可存取的 plugin apps 計算限制性的 thread app config。
Thread app config 會在 OpenClaw 建立 Codex harness session 或替換過期的 Codex thread binding 時進行計算。它不會在每個回合重新計算。
V1 支援邊界
V1 有意保持狹窄：
- 只有已在來源 Codex app-server inventory 中安裝的
openai-curatedplugins 符合 migration 資格。 - App-backed source plugins 必須通過 migration 時的 subscription gate。
--verify-plugin-apps會加入來源 app-inventory gate。受 subscription gate 限制的 accounts，以及在驗證模式中無法存取、已停用、缺少來源 apps，或來源 app-inventory refresh 失敗，都會回報為 skipped manual items，而不是啟用的 config entries。無法讀取的 plugin details 會在來源 app-inventory gate 前被跳過。 - Migration 會寫入包含
marketplaceName與pluginName的明確 plugin identities；它不會寫入本機marketplacePathcache paths。 codexPlugins.enabled是全域啟用開關。- 沒有
plugins["*"]萬用字元，也沒有可授予任意安裝權限的 config key。 - 不支援的 marketplaces、cached plugin bundles、hooks 與 Codex config files 會保留在 migration report 中，以供手動檢閱。
App inventory 與擁有權
OpenClaw 會透過 app-server app/list 讀取 Codex app inventory，快取一小時，
並非同步重新整理過期或缺少的 entries。快取僅存在於記憶體中；重新啟動 CLI
或 gateway 會清除它，OpenClaw 會從下一次 app/list 讀取重新建立。
Migration 與 runtime 使用不同的 cache keys：
- 來源 migration verification 使用來源 Codex home 與來源 app-server start options。
這只會在設定
--verify-plugin-apps時執行，並且會針對該次 planning run 強制進行新的來源app/listtraversal。 - 目標 runtime setup 在建置 Codex thread app config 時，會使用目標 agent 的
Codex app-server identity。Plugin activation 會使該目標 cache key
失效，然後在
plugin/install後強制重新整理。
只有在 OpenClaw 可透過穩定擁有權將 plugin app 對應回 migrated plugin 時， 才會公開該 plugin app：
- 來自 plugin detail 的精確 app id
- 已知 MCP server name
- 唯一的穩定 metadata
僅 display name 符合或擁有權模糊的項目會被排除，直到下一次 inventory refresh 證明擁有權為止。
Thread app config
OpenClaw 會為 Codex thread 注入限制性的 config.apps patch：
_default 會被停用，且只有由已啟用 migrated plugins 擁有的 apps 會被啟用。
OpenClaw 會根據有效的全域或 per-plugin allow_destructive_actions
政策設定 app-level destructive_enabled，並讓 Codex 依其原生 app tool annotations
強制執行 destructive tool metadata。_default app config 會以
open_world_enabled: false 停用。已啟用的 plugin apps 會以
open_world_enabled: true 輸出；OpenClaw 不會公開獨立的 plugin open-world
policy knob，也不會維護 per-plugin destructive tool-name deny lists。
Plugin apps 的 tool approval mode 預設為 automatic，因此非破壞性的 read tools
可以在沒有同一 thread approval UI 的情況下執行。Destructive tools
仍由各 app 的 destructive_enabled 政策控制。
破壞性動作政策
對 migrated Codex plugins 的破壞性 plugin elicitations 預設允許，而 unsafe schemas 與模糊的擁有權仍會 fail closed：
- 全域
allow_destructive_actions預設為true。 - Per-plugin
allow_destructive_actions會為該 plugin 覆寫全域政策。 - 當政策為
false時，OpenClaw 會回傳確定性的拒絕。 - 當政策為
true時，OpenClaw 只會自動接受它可以對應到 approval response 的 safe schemas，例如 boolean approve field。 - 缺少 plugin identity、擁有權模糊、缺少 turn id、錯誤的 turn id，或 unsafe elicitation schema 都會拒絕，而不是提示。
疑難排解
auth_required： migration 已安裝 plugin，但其中一個 apps 仍需要驗證。
明確的 plugin entry 會以停用狀態寫入，直到你重新授權並啟用它。
app_inaccessible、app_disabled 或 app_missing：
migration 未安裝 plugin，因為在設定 --verify-plugin-apps 時，來源 Codex
app inventory 未顯示所有 owned apps 都存在、已啟用且可存取。請在 Codex
中重新授權或啟用 app，然後使用 --verify-plugin-apps 重新執行 migration。
app_inventory_unavailable： migration 未安裝 plugin，因為已要求嚴格的來源
app 驗證，但來源 Codex app inventory refresh 失敗。請修正來源 Codex app-server
存取，或若你接受較快的 account-gated plan，請不使用 --verify-plugin-apps
重試。
codex_subscription_required： migration 未安裝 app-backed plugin，因為來源
Codex app-server account 未以 ChatGPT subscription account 登入。請使用
subscription auth 登入 Codex app，然後重新執行 migration。
codex_account_unavailable： migration 未安裝 app-backed plugin，因為無法讀取來源
Codex app-server account。請修正來源 Codex app-server auth，或若你希望在 account
lookup 失敗時由來源 app inventory 判定資格，請使用 --verify-plugin-apps
重新執行。
marketplace_missing 或 plugin_missing： 目標 Codex app-server
無法看到預期的 openai-curated marketplace 或 plugin。請針對目標 runtime
重新執行 migration，或檢查 Codex app-server plugin 狀態。
app_inventory_missing 或 app_inventory_stale： app readiness 來自空白或過期的 cache。
OpenClaw 會排程 async refresh，並在擁有權與 readiness 已知前排除 plugin
apps。
app_ownership_ambiguous： app inventory 只透過 display name 符合，因此該 app
不會公開給 Codex thread。
Config 已變更但 agent 看不到 plugin： 請使用 /new、/reset，或重新啟動
gateway。既有的 Codex thread bindings 會保留啟動時使用的 app config，直到
OpenClaw 建立新的 harness session 或替換過期 binding。
破壞性動作遭拒： 請檢查全域與 per-plugin allow_destructive_actions
值。即使政策為 true，unsafe elicitation schemas 與模糊的 plugin identity
仍會 fail closed。