OpenClaw で OpenAI 系モデルを使うとき、「普通の OpenClaw runtime と何が違うのか」「Codex app-server に任せる部分と Gateway 側で持つ部分はどこか」で迷いやすいです。ここを曖昧にしたまま設定を増やすと、approval が二重になったり、compaction の責任者が分からなくなったり、transcript と native thread の状態がずれて調査しにくくなります。
この記事では、2026年8月13日時点の OpenClaw docs と OpenAI の Codex App Server 記事を前提に、OpenClaw Codex harness の責務境界に絞って整理します。OpenClaw 全体の入口は OpenClaw の使い方入門、workspace / memory / backup の置き方は OpenClaw workspace 設計ガイド、agentId / accountId / binding の分離は OpenClaw multi-agent routing 設計ガイド、Codex App Server 自体の接続面は Codex App Server ガイド に分けています。
今回は「OpenClaw に Codex をつなげる手順」ではなく、どちらの runtime が何を所有するかの話です。
先に結論: Codex は native agent loop、OpenClaw は運用面を持つ
OpenClaw Codex harness を安全に扱うコツは、次の表を先に固定することです。
| 領域 | 所有者 | 実務上の意味 |
|---|---|---|
| native thread resume | Codex app-server | Codex 側の thread を canonical として扱う |
| native tool continuation | Codex app-server | tool call の継続は Codex の agent loop に従う |
| native compaction | Codex app-server | OpenClaw が独自要約で置き換えない |
| app-server execution | Codex app-server | rich event / approval / diff を Codex protocol で受ける |
| chat channel | OpenClaw Gateway | WebChat / Discord / Telegram などの配送を持つ |
| session file | OpenClaw Gateway | Gateway 側の session state と監査導線を持つ |
| dynamic tools | OpenClaw Gateway | OpenClaw tool / plugin middleware を adapter 経由で実行する |
| approvals | OpenClaw Gateway + Codex | native request を Gateway approval flow に写像する |
| transcript mirror | OpenClaw Gateway | 検索、/new、/reset、runtime切替のために見える履歴を保つ |
つまり、OpenClaw Codex harness は「OpenClaw が Codex をただの model provider として呼ぶ」構造ではありません。Codex の native agent loop を使いながら、OpenClaw が channel、approval、tool policy、media delivery、diagnostics の運用面を包む構造です。
この線引きをしないと、設定や障害調査で次のような判断を間違えます。
- compaction が詰まったときに Gateway 側の要約設定を疑う
- approval が出ないときに Codex policy だけを見る
- transcript に見える履歴を Codex native thread の完全な代替だと思う
- OpenClaw dynamic tool を Codex native tool と同じ並列実行モデルで扱う
Codex harness は便利ですが、責務を混ぜるほど運用は壊れやすくなります。
OpenClaw runtime ではなく Codex app-server runtime として見る
OpenClaw docs では、Codex harness は built-in OpenClaw harness の代わりに Codex app-server を通して embedded OpenAI agent turn を動かすものとして説明されています。ここで重要なのは、Codex が model call だけを持つのではなく、thread、tool continuation、compaction、execution まで持つことです。
OpenAI の Codex App Server 記事でも、App Server は JSON-RPC protocol であると同時に、Codex core thread を host する long-lived process として説明されています。1つの user request から複数の event update が流れ、approval のように server 側から client へ入力を求める request も発生します。
実務では、この理解にすると設定が短くなります。
runtime_boundary:
codex_app_server:
owns:
- native_thread
- native_tool_continuation
- native_compaction
- app_server_events
openclaw_gateway:
owns:
- source_channel
- session_file
- visible_transcript
- plugin_approval
- media_delivery
- diagnostics_exportCodex を「OpenClaw の中の別モデル」だと思うと、OpenClaw 側で thread lifecycle を全部再現したくなります。逆に、OpenClaw を「Codex の薄いUI」だと思うと、Gateway が持つ channel routing や plugin approval を軽視します。どちらも違います。
approval は二重化ではなく写像として扱う
Codex harness で最も事故りやすいのは approval です。Codex app-server は native permission request や MCP tool approval elicitation を出せます。一方、OpenClaw には plugin approval flow と Control UI があります。
ここでやるべきことは、両方を独立に表示することではありません。Codex の native request を OpenClaw の approval record に写像し、最終判断を Codex 側へ返すことです。
approval_mapping:
native_event:
- PermissionRequest
- mcp_tool_call_elicitation
gateway_record:
owner: openclaw
visible_in:
- control_ui
- source_channel_buttons_when_safe
decision:
allow: return native allow
deny: return native deny
no_decision: fall through, not implicit allow重要なのは、no decision を allow と扱わないことです。OpenClaw docs でも、policy が明示的に allow / deny するときだけ decision を返し、判断なしは Codex 側の guardian や user approval path に落ちるとされています。
この設計にすると、監査ログで「誰がどの channel で何を許可したか」を追えます。逆に、Codex の approval と OpenClaw の approval を別々に出すと、片方が allow、片方が deny のような壊れた状態を作ります。
dynamic tools は Codex native tool と同じに見ない
OpenClaw dynamic tools は、Codex が tool call を求めたあと、OpenClaw adapter 側で実行されます。つまり、Codex native tool と同じ実行モデルではありません。
実務では、次の制約を前提にします。
| tool 種別 | 実行境界 | 注意点 |
|---|---|---|
| Codex native tool | Codex app-server runtime | native policy と sandbox に従う |
| OpenClaw dynamic tool | OpenClaw harness adapter | plugin / middleware / approval flow を通る |
| MCP tool elicitation | Codex request + Gateway approval | _meta の approval kind を見て Gateway record に写像する |
OpenClaw dynamic tool の結果は generic text として Codex Code Mode に返るため、JSON っぽい結果を厳密な structured output として信じすぎない方がよいです。並列実行も、Codex native tool の感覚で Promise.all 的に期待しない方が安全です。
私は dynamic tools を次の3段階に分けます。
codex_dynamic_tools_policy:
direct:
use_for:
- read_only_project_metadata
- short_inspection_tools
searchable:
use_for:
- many_tools
- tools_with_side_effect_risk
excluded:
use_for:
- secrets_access
- production_write
- deploy_or_billing_actions最初は searchable か excluded を多めにします。Codex harness に乗せた瞬間に tool を広げるのではなく、OpenClaw 側で「どの tool を Codex context に見せるか」を絞る方が事故りにくいです。
compaction は Codex に任せ、transcript mirror は OpenClaw が保つ
Codex harness を使う session では、native thread compaction は Codex app-server の仕事です。OpenClaw が preflight compaction を走らせたり、独自の context-engine compaction で置き換えたりしない前提で設計します。
一方で、OpenClaw は transcript mirror を保ちます。これは Codex native thread の代替ではなく、Gateway 側の visible history です。
history_boundary:
codex_native_thread:
purpose:
- resume
- tool_continuation
- native_compaction
openclaw_transcript_mirror:
purpose:
- channel_history
- search
- new_or_reset_flow
- future_runtime_switching
- diagnostics_contextこの区別は障害対応で効きます。「見えている transcript にあるから Codex native thread にもあるはず」と考えると、compaction 後や remote connection 退避後の調査を誤ります。逆に、「Codex が canonical だから transcript は不要」と考えると、channel delivery、検索、runtime 切替、ユーザー向け履歴が弱くなります。
remote app-server は workspace root と attachment を疑う
remote Codex app-server を使う場合、Gateway と Codex app-server が別マシンにいることがあります。このとき、shared filesystem がある前提で attachment path を扱うと危険です。
OpenClaw docs では、remoteWorkspaceRoot による remote workspace attachment path の検証、authoritative attachment bytes の転送、symlink 拒否、size limit、Gateway-managed media staging などの境界が説明されています。
実務の checklist はこれで足ります。
remote_codex_harness_checklist:
workspace:
- remoteWorkspaceRoot is explicit
- local path and remote path are not assumed identical
attachments:
- reject symlinks
- enforce file size before allocation
- enforce response size before allocation
- stage immutable gateway-managed media
diagnostics:
- record OpenClaw session id
- record Codex thread id
- include local codex resume command when available特に media と attachment は、AI agent の便利機能というより data boundary です。どの bytes が authoritative で、どの runtime が読み、どの channel に配送したかを追える形にしておくべきです。
いつ OpenClaw Codex harness を選ぶか
OpenClaw の中で Codex harness を使うべき場面は、単に「OpenAI モデルを使いたい」だけではありません。Codex native agent loop の価値があるときです。
| やりたいこと | 選ぶ runtime |
|---|---|
| OpenClaw 標準の Gateway / channel / plugin を中心に使う | built-in OpenClaw runtime |
| Codex native thread / compaction / approval event を使いたい | Codex harness |
| Claude Code CLI など外部 CLI をそのまま動かしたい | CLI backend / ACP 系 |
| 複数 provider を共通最小APIで抽象化したい | cross-provider harness protocol |
Codex harness を選ぶ理由は、OpenClaw の機能を捨てることではありません。Codex の native agent loop を使いながら、OpenClaw の channel、approval、diagnostics、tool policy を残すことです。
導入時の最小設定レビュー
私なら、最初の review checklist はこのくらいにします。
## OpenClaw Codex harness review
- [ ] `openai/*` model refs が Codex runtime を選ぶ意図になっている
- [ ] legacy whole-agent runtime pin を `openclaw doctor --fix` で掃除した
- [ ] Codex app-server mode と auth profile を記録した
- [ ] dynamic tools は direct ではなく searchable から始めた
- [ ] production write / secrets / deploy 系 dynamic tools を除外した
- [ ] PermissionRequest の no decision を allow と扱っていない
- [ ] MCP tool approval elicitation が Gateway approval record に写像される
- [ ] transcript mirror と native thread を同一視していない
- [ ] remote app-server では `remoteWorkspaceRoot` と attachment size limit を確認した
- [ ] diagnostics export と Codex feedback upload の違いを運用手順に書いたこの checklist を通せないなら、まだ Codex harness を本番運用に入れない方がよいです。設定が動くことと、障害時に説明できることは別です。
まとめ
OpenClaw Codex harness は、OpenClaw の裏側で Codex を呼ぶだけの薄い接続ではありません。Codex app-server が native thread、tool continuation、compaction、execution を持ち、OpenClaw Gateway が channel routing、dynamic tools、approvals、media delivery、transcript mirror、diagnostics を持つ二層構造です。
最初に決めるべきことは、model 名ではなく責務境界です。Codex が持つもの、OpenClaw が持つもの、両者を写像するものを分ける。特に approval、dynamic tools、compaction、transcript mirror、remote attachment は、設定より先に運用ルールとして固定するべきです。
この境界を明文化しておくと、OpenClaw は「複数チャネルから Codex を呼べるUI」ではなく、Codex native runtime を組織運用に載せるための Gateway として扱えます。