Skip to content

feat: add Codex hosted web search#93446

Merged
fuller-stack-dev merged 21 commits into
openclaw:mainfrom
fuller-stack-dev:codex/codex-hosted-web-search
Jun 16, 2026
Merged

feat: add Codex hosted web search#93446
fuller-stack-dev merged 21 commits into
openclaw:mainfrom
fuller-stack-dev:codex/codex-hosted-web-search

Conversation

@fuller-stack-dev

@fuller-stack-dev fuller-stack-dev commented Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

  • Adds a Codex app-server web-search planner that prefers Codex hosted web_search when the provider reports support, while keeping OpenClaw's managed web_search tool as the fallback for unsupported providers.
  • Registers the Codex plugin as an explicit managed web-search provider selectable with tools.web.search.provider: "codex", so any parent model/runtime can delegate a search to a bounded Codex worker without removing an existing provider preset.
  • Runs explicit-provider searches in an ephemeral, isolated Codex thread with shell environments, dynamic tools, apps, plugins, image generation, multi-agent, and code mode disabled; it fails closed unless Codex emits a native hosted-search item.
  • Keeps native hosted search and managed search mutually exclusive, applies domain/context/location restrictions to Codex thread config, and carries /btw side-question policy context into Codex side forks.
  • Reuses the bounded Codex lifecycle for media understanding and documents the hosted-search/provider/config boundaries.

Verification

  • pnpm test extensions/codex/src/app-server/side-question.test.ts extensions/codex/src/app-server/provider-capabilities.test.ts extensions/codex/src/app-server/web-search.test.ts extensions/codex/src/app-server/dynamic-tool-build.test.ts extensions/codex/src/app-server/dynamic-tools.test.ts extensions/codex/src/app-server/thread-lifecycle.binding.test.ts extensions/codex/src/app-server/thread-lifecycle.test.ts extensions/codex/src/app-server/attempt-startup.test.ts extensions/codex/src/app-server/event-projector.test.ts src/agents/btw.test.ts src/auto-reply/reply/commands-btw.test.ts src/agents/harness/selection.test.ts -- --reporter=dot - passed 388 tests across 3 Vitest shards.
  • pnpm test extensions/codex/src/web-search-provider.test.ts extensions/codex/media-understanding-provider.test.ts extensions/codex/index.test.ts extensions/codex/src/app-server/web-search.test.ts - passed 31 tests across 4 files.
  • pnpm test src/plugins/web-provider-public-artifacts.test.ts src/plugins/contracts/registry.contract.test.ts src/plugins/contracts/loader.contract.test.ts - passed 26 tests across 3 files and 2 shards.
  • pnpm tsgo:core - passed.
  • pnpm tsgo:extensions - passed after the explicit-provider change.
  • pnpm tsgo:test:src - passed.
  • pnpm build - passed after the explicit-provider change; emitted the Codex web-search contract artifact and registered manifest provider.
  • git diff --cached --check before commit - passed.

Real behavior proof

Behavior addressed: Codex app-server runs use Codex native hosted web_search when supported. OpenClaw users can also explicitly select tools.web.search.provider: "codex" while using a different parent model/runtime; that managed tool delegates only the search to an isolated Codex worker.

Real environment tested: Local Rosita OpenClaw agent with isolated config/state and live network access. The explicit-provider proof used parent model a non-Codex parent model, OpenClaw runtime, tools.web.search.provider: "codex", and Codex model gpt-5.5 for the bounded search worker. A separate native-path proof used the Codex app-server harness with codex/gpt-5.5.

Exact steps or command run after this patch:

OPENCLAW_CONFIG_PATH="[isolated Rosita config with tools.web.search.provider=codex]" \
OPENCLAW_STATE_DIR="[isolated Rosita state]" \
node dist/index.js agent --local --agent main \
  --session-id rosita-codex-provider-cross-model-20260615T185223 \
  --model [non-Codex-parent-model] \
  --thinking low \
  --timeout 420 \
  --json \
  --message 'Actually invoke the managed web_search tool now; do not merely state intent. Use web_search exactly once and do not use web_fetch or browser. Find two currently operating plumbing service providers serving Edmonton, Alberta. Return each provider name and source URL, then exact marker ROSITA_CODEX_PROVIDER_CROSS_MODEL_OK.'

Evidence after fix: The cross-model run reported parent provider/model/harness a non-Codex provider/model using the openclaw runtime, exactly one web_search call, and zero tool failures. Its persisted tool result reported provider: "codex", model: "gpt-5.5", one hosted search action, and isError: false. The earlier native-path Rosita run persisted one Codex web_search_call response item and returned its exact marker.

Observed result after fix: The explicit-provider run returned Capital Plumbing & Heating (https://capitalplumbing.ca/) and EZ Plumbing (https://www.ezplumbinginc.ca/) plus ROSITA_CODEX_PROVIDER_CROSS_MODEL_OK. This proves a non-Codex parent model can use Codex as the configured OpenClaw web-search provider without removing another preset to trigger implicit behavior.

What was not tested: Full pnpm check and cross-OS Crabbox/Testbox lanes were not run. Final autoreview was intentionally skipped at maintainer request so the local Rosita implementation and live proof could proceed directly.

Current-main rebase proof

  • Rebased the three PR commits onto current upstream main (a447f9a43d) with zero commits behind at push time; all merge conflicts were resolved against current runtime, plugin SDK, provider, and test contracts.
  • Exact-head focused proof: 338 tests passed across five Vitest projects covering Codex hosted search, explicit provider registration, thread lifecycle, side questions, media understanding, harness selection, and plugin contracts.
  • Exact-head pnpm tsgo:core, pnpm tsgo:extensions, branch-wide pnpm format:check, and git diff --check passed.
  • pnpm build passed after the current-main reconciliation commit.

Crabbox live proof

  • Date: June 15, 2026
  • Successful run: run_6f65751b4c39
  • Lease/environment: Azure Linux Standard_D4ads_v6, lease cbx_da57866db36d
  • Source synced from branch head: dcbdfcb74a76e3ad4c969abde38edb4d64a5f0b2
  • Native path: parent openai/gpt-5.5, runtime codex, native Codex hosted search, one recorded web_search call, zero tool failures, and two grounded source URLs from www.petetheplumber.com and mrmikesplumbing.ca.
  • Explicit-provider path: parent openai/gpt-5.4, runtime openclaw, tools.web.search.provider: "codex", successful web_search execution with zero tool failures, and two grounded source URLs from prontoinc.ca and prostarplumbing.ca.
  • Result: both requested live scenarios passed in one isolated Crabbox run. The OpenClaw parent remained on the OpenClaw runtime while the configured Codex provider handled web search.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation agents Agent runtime and tooling extensions: codex size: XL maintainer Maintainer-authored PR labels Jun 16, 2026
@fuller-stack-dev
fuller-stack-dev force-pushed the codex/codex-hosted-web-search branch 2 times, most recently from 7450a03 to dcbdfcb Compare June 16, 2026 01:28
@fuller-stack-dev
fuller-stack-dev force-pushed the codex/codex-hosted-web-search branch from dcbdfcb to 5e18e4b Compare June 16, 2026 02:15
@openclaw-barnacle openclaw-barnacle Bot added the commands Command implementations label Jun 16, 2026
@fuller-stack-dev fuller-stack-dev mentioned this pull request Jun 16, 2026
Merged
@fuller-stack-dev fuller-stack-dev self-assigned this Jun 16, 2026
@fuller-stack-dev

fuller-stack-dev commented Jun 16, 2026

Copy link
Copy Markdown
Member Author

@clawsweeper re-review

@openclaw-barnacle openclaw-barnacle Bot removed the commands Command implementations label Jun 16, 2026
@clawsweeper

clawsweeper Bot commented Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

@clawsweeper

clawsweeper Bot commented Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed June 15, 2026, 11:52 PM ET / 03:52 UTC.

Summary
Adds Codex hosted web_search planning, registers Codex as a managed web-search provider, adds bounded Codex search worker tests, carries /btw tool-policy context, and updates Codex search docs/help/snapshots.

PR surface: Source +871, Tests +1596, Docs +78. Total +2545 across 45 files.

Reproducibility: not applicable. as a feature PR; the PR body includes live local and Crabbox proof for native and explicit-provider search paths.

Review metrics: 1 noteworthy metric.

  • Codex web-search surfaces: 1 provider added, 1 default path changed, 0 schema keys added. The diff adds a managed provider and changes Codex's default search route, which affects upgrades even without a new config field.

Stored data model
Persistent data-model change detected: migration/backfill/repair: extensions/codex/src/web-search-provider.test.ts, serialized state: extensions/codex/src/app-server/session-binding.ts, serialized state: extensions/codex/src/app-server/thread-lifecycle.binding.test.ts, vector/embedding metadata: docs/plugins/sdk-entrypoints.md, vector/embedding metadata: docs/plugins/tool-plugins.md. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Get explicit maintainer signoff on hosted Codex search as the unpinned default path, or narrow the branch to explicit opt-in behavior.

Risk before merge

  • [P1] Existing Codex users with unpinned web search can move from the OpenClaw managed provider path to Codex hosted web_search by default, which is an intentional compatibility/auth-provider change rather than a pure bug fix.
  • [P1] Registering codex as a credentialless managed web-search provider broadens provider routing and account-selection behavior; maintainers should explicitly accept the sign-in/source-of-truth change before merge.

Maintainer options:

  1. Accept the hosted-search default (recommended)
    Land with the documented default switch if maintainers want Codex hosted search to own unpinned Codex web-search behavior.
  2. Require explicit opt-in
    Change the branch so Codex hosted search runs only when the user explicitly enables openaiCodex hosted search or selects provider codex.
  3. Pause behind provider-routing work
    Hold this PR until adjacent explicit-provider routing work is settled if maintainers want one combined decision on web-search provider precedence.

Next step before merge

  • [P2] Human maintainer review should decide the hosted-search default and provider/auth routing behavior; there is no narrow automation repair to apply.

Security
Cleared: The diff introduces no concrete security or supply-chain concern; the bounded Codex search worker disables broader native tools and denies approval requests while enabling hosted web_search.

Review details

Best possible solution:

Land only if maintainers want Codex hosted search to be the default unpinned Codex search path; otherwise narrow hosted search to an explicit opt-in or pinned provider path.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a feature PR; the PR body includes live local and Crabbox proof for native and explicit-provider search paths.

Is this the best way to solve the issue?

Likely yes on owner boundary because Codex-specific hosted search stays in the Codex plugin and uses the existing web-search provider seam, but the default-routing choice needs maintainer acceptance.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 6ffa0fb34897.

Label changes

Label changes:

  • add P2: This is a normal-priority feature/default-routing change with bounded but real compatibility impact.
  • add merge-risk: 🚨 compatibility: The PR changes the default Codex web-search path for unpinned setups, which can alter existing upgrade behavior.
  • add merge-risk: 🚨 auth-provider: The new codex managed provider uses Codex/OpenAI sign-in rather than a separate search-provider credential, changing provider/auth routing semantics.
  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This maintainer/member PR includes live local and Crabbox proof, and the external-contributor proof gate is not applicable.

Label justifications:

  • P2: This is a normal-priority feature/default-routing change with bounded but real compatibility impact.
  • merge-risk: 🚨 compatibility: The PR changes the default Codex web-search path for unpinned setups, which can alter existing upgrade behavior.
  • merge-risk: 🚨 auth-provider: The new codex managed provider uses Codex/OpenAI sign-in rather than a separate search-provider credential, changing provider/auth routing semantics.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This maintainer/member PR includes live local and Crabbox proof, and the external-contributor proof gate is not applicable.
Evidence reviewed

PR surface:

Source +871, Tests +1596, Docs +78. Total +2545 across 45 files.

View PR surface stats
Area Files Added Removed Net
Source 24 1262 391 +871
Tests 17 1646 50 +1596
Docs 4 91 13 +78
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 45 2999 454 +2545

Acceptance criteria:

  • [P1] Review provider-resolution behavior for explicit and unpinned web search.
  • [P1] Confirm fresh-install and upgrade behavior for Codex turns with no tools.web.search.provider set.
  • [P1] Confirm explicit provider: codex behavior with Codex/OpenAI sign-in and disabled openaiCodex config.

What I checked:

  • AGENTS policy applied: Root and scoped policy were inspected during review; the relevant guidance requires direct Codex source inspection, plugin-boundary review, and explicit compatibility treatment for provider routing/config/default changes. (AGENTS.md:1)
  • Codex web-search planner defaults hosted search: The PR-head planner returns native-hosted search with managed web search suppressed by default when native provider web_search support is not explicitly false, which is the central default-routing change under review. (extensions/codex/src/app-server/web-search.ts:80, e6abe1f5a7e9)
  • Thread lifecycle applies search plan: The PR-head thread lifecycle computes a Codex web-search plan, tracks its fingerprint, starts fresh transient threads for search-policy changes, and passes webSearchAllowed/nativeProviderWebSearchSupported into thread start/resume config. (extensions/codex/src/app-server/thread-lifecycle.ts:328, e6abe1f5a7e9)
  • Managed provider is registered without its own credential: The PR-head Codex web-search provider advertises selectionPluginId codex, requires no separate credential, and uses the Codex/OpenAI sign-in path, so merging changes the available managed provider/auth source. (extensions/codex/src/web-search-provider.shared.ts:8, e6abe1f5a7e9)
  • Existing provider resolution supports auto and explicit providers: Current main sorts provider candidates by autoDetectOrder and resolves an explicit configured provider by id, so adding a credentialless codex provider affects the provider candidate surface even when no schema key is added. (src/plugins/web-provider-resolution-shared.ts:84)
  • Current web-search tool uses the provider seam: Current main resolves the provider through createWebSearchProviderTool and executes the selected provider tool, confirming the PR uses the existing managed web-search plugin boundary rather than adding a new core tool path. (src/agents/tools/web-search.ts:116)

Likely related people:

  • steipete: Recent history shows repeated merged work across Codex app-server runtime, provider/tooling, docs, and OpenClaw plugin surfaces that this PR extends. (role: recent area contributor; confidence: medium; commits: 4c33aaa, 9153aab, a09f6b1; files: extensions/codex/src/app-server/thread-lifecycle.ts, extensions/codex/src/app-server/dynamic-tool-build.ts, docs/tools/web.md)
  • joshavant: Recent commits touched Codex app-server lifecycle/context behavior and /btw/session-adjacent agent paths affected by the branch. (role: recent area contributor; confidence: medium; commits: a8d33f23; files: extensions/codex/src/app-server/thread-lifecycle.ts, src/agents/btw.ts, src/auto-reply/reply/commands-btw.ts)
  • vincentkoc: Recent Codex provider and dynamic-tool policy work overlaps with native tool selection and provider-routing behavior reviewed here. (role: adjacent owner; confidence: medium; commits: b4cdd921, edc0a221; files: extensions/codex/src/app-server/dynamic-tool-build.ts, extensions/codex/src/app-server/provider-capabilities.ts)
  • bek91: Recent Codex bounded/app-server and media-understanding provider work is adjacent to the bounded Codex worker pattern introduced by this PR. (role: adjacent contributor; confidence: low; commits: 46a5a5ee; files: extensions/codex/media-understanding-provider.ts, extensions/codex/src/app-server/bounded-turn.ts)
  • amknight: History/blame ties the existing openaiCodex web-search config surface to this contributor, and the PR changes behavior around that existing config family. (role: config surface contributor; confidence: low; commits: 2365a137d8; files: src/config/types.tools.ts, src/config/schema.help.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. labels Jun 16, 2026
@fuller-stack-dev
fuller-stack-dev merged commit 1e0062b into openclaw:main Jun 16, 2026
26 checks passed
@fuller-stack-dev

fuller-stack-dev commented Jun 16, 2026

Copy link
Copy Markdown
Member Author

Merged as 1e0062b44a515ed0ef8a5088ff96ba21f3badcc5 from source head 23824af49accd7bbaa86d5d99b8a720a31f8412c.

Maintainer decision: accepted the Codex hosted-search default and provider/auth routing behavior described in the ClawSweeper review.

Final focused verification on the exact source head after merging latest upstream/main:

  • git diff --check
  • focused Codex hosted-search and /btw policy regression suite: 202/202 tests passed

The final blocker fixes preserve narrow tool policies for Codex /btw side questions and strip configured tool/startup overrides from private hosted-search workers.

@clawsweeper clawsweeper Bot mentioned this pull request Jun 16, 2026
Merged
@github-actions github-actions Bot mentioned this pull request Jun 16, 2026
Open
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jun 17, 2026
@fuller-stack-dev
feat: add Codex hosted web search (openclaw#93446)
57d50e2 
Adds Codex as a selectable hosted web-search provider, routes native Codex search safely across model overrides, and isolates bounded hosted-search workers from configured tools.\n\nVerification: focused post-merge regression suite passed 202/202 tests on exact head 23824af.
crh-code pushed a commit to crh-code/openclaw that referenced this pull request Jun 18, 2026
@fuller-stack-dev @crh-code
feat: add Codex hosted web search (openclaw#93446)
0ec8b87 
Adds Codex as a selectable hosted web-search provider, routes native Codex search safely across model overrides, and isolates bounded hosted-search workers from configured tools.\n\nVerification: focused post-merge regression suite passed 202/202 tests on exact head 23824af.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@fuller-stack-dev fuller-stack-dev

Labels

agents Agent runtime and tooling docs Improvements or additions to documentation extensions: codex maintainer Maintainer-authored PR merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. P2 Normal backlog priority with limited blast radius. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: XL status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@fuller-stack-dev