From c4965ad80b0baebdcf1406202931b76c0e7a6fea Mon Sep 17 00:00:00 2001 From: Ingwannu Date: Mon, 17 Aug 2026 00:42:49 +0000 Subject: [PATCH 1/2] docs(codex): explain deferred tool search boundary --- .../content/docs/guides/codex-integration.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs-site/src/content/docs/guides/codex-integration.md b/docs-site/src/content/docs/guides/codex-integration.md index 39e33fc0c4..81f8eb43cf 100644 --- a/docs-site/src/content/docs/guides/codex-integration.md +++ b/docs-site/src/content/docs/guides/codex-integration.md @@ -279,6 +279,45 @@ enabled, also pass `x-opencodex-api-key` from `OPENCODEX_API_AUTH_TOKEN`, matchi provider form above. To let OpenCodex inject routing directly, first switch Codex back to its built-in `openai` provider and remove any user-owned root `openai_base_url`, then rerun `ocx start`. +### Deferred `tool_search` troubleshooting + +`tool_search` is a client-executed Codex discovery tool for loading deferred MCP/app tools. It is +not an OpenCodex feature flag, and an upstream `tool_choice: "auto"` value does not create or enable +it. OpenCodex can relay the tool only when Codex already included a declaration like this in the +incoming Responses request: + +```json +{ + "tools": [ + { "type": "tool_search", "description": "Load deferred tools" } + ] +} +``` + +For routed chat/local models, OpenCodex exposes that declaration as a normal function named +`tool_search`. If the model calls it, OpenCodex converts the call back to a Responses +`tool_search_call`; Codex executes the search and supplies the resulting tool definitions in a +later `tool_search_output`. Definitions loaded that way are then available on the next model turn. + +Check the failure boundary before changing provider settings: + +1. **No `type: "tool_search"` in the incoming request:** the active Codex client/session did not + advertise deferred discovery. OpenCodex cannot invent the tool. Update/restart Codex and verify + the client's MCP/app configuration and feature availability. +2. **The incoming declaration exists, but no `tool_search` function reaches the routed request:** + capture only the redacted tool-type/name list and open an OpenCodex bug. Never attach the bearer, + account id, conversation input, full headers, or complete request body. +3. **The routed request contains `tool_search`, but the local model never calls it:** the relay is + working. Use a model/template with reliable function calling and instructions that explicitly + tell it to search for a needed deferred tool. LM Studio's `tool_choice: "auto"` permits tool use; + it does not force the model to call this function. +4. **A call is emitted repeatedly or loaded tools never become usable:** capture the redacted + `tool_search_call` / `tool_search_output` item types and call ids. OpenCodex preserves both in + history so the model should see the completed search instead of issuing it forever. + +See [The parser and bridge](/reference/architecture/#the-parser) for the wire mapping. There is no +provider-level setting that can compensate for a missing client declaration. + ### Catalog troubleshooting If a model is missing from Codex, or the catalog order/visibility looks wrong, check in order: From b3eda11c5aaea7e6ece5f24c0c3171ac60d27b01 Mon Sep 17 00:00:00 2001 From: Ingwannu Date: Tue, 18 Aug 2026 12:32:45 +0000 Subject: [PATCH 2/2] docs(codex): separate code-mode and tool search discovery --- .../content/docs/guides/codex-integration.md | 26 ++++++++++++------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/docs-site/src/content/docs/guides/codex-integration.md b/docs-site/src/content/docs/guides/codex-integration.md index 81f8eb43cf..c0a4217953 100644 --- a/docs-site/src/content/docs/guides/codex-integration.md +++ b/docs-site/src/content/docs/guides/codex-integration.md @@ -279,12 +279,16 @@ enabled, also pass `x-opencodex-api-key` from `OPENCODEX_API_AUTH_TOKEN`, matchi provider form above. To let OpenCodex inject routing directly, first switch Codex back to its built-in `openai` provider and remove any user-owned root `openai_base_url`, then rerun `ocx start`. -### Deferred `tool_search` troubleshooting +### Explicit `tool_search` troubleshooting -`tool_search` is a client-executed Codex discovery tool for loading deferred MCP/app tools. It is -not an OpenCodex feature flag, and an upstream `tool_choice: "auto"` value does not create or enable -it. OpenCodex can relay the tool only when Codex already included a declaration like this in the -incoming Responses request: +Routed local tooling has two distinct discovery paths. In normal routed code mode, Codex can expose +deferred MCP/app tools through the official `exec` tool's `tools` global and `ALL_TOOLS`; that path +does not require the model to see or call `tool_search`. + +Separately, `tool_search` is a client-executed Codex discovery surface. It is not an OpenCodex +feature flag, and an upstream `tool_choice: "auto"` value does not create or enable it. OpenCodex can +relay the explicit surface only when Codex already included a declaration like this in the incoming +Responses request: ```json { @@ -302,21 +306,23 @@ later `tool_search_output`. Definitions loaded that way are then available on th Check the failure boundary before changing provider settings: 1. **No `type: "tool_search"` in the incoming request:** the active Codex client/session did not - advertise deferred discovery. OpenCodex cannot invent the tool. Update/restart Codex and verify - the client's MCP/app configuration and feature availability. + advertise the explicit `tool_search` surface. OpenCodex cannot invent that declaration. This + does not mean normal code-mode tools are unavailable: check whether the routed model can use + `exec` and discover the needed nested tool through `tools` / `ALL_TOOLS` first. 2. **The incoming declaration exists, but no `tool_search` function reaches the routed request:** capture only the redacted tool-type/name list and open an OpenCodex bug. Never attach the bearer, account id, conversation input, full headers, or complete request body. 3. **The routed request contains `tool_search`, but the local model never calls it:** the relay is working. Use a model/template with reliable function calling and instructions that explicitly - tell it to search for a needed deferred tool. LM Studio's `tool_choice: "auto"` permits tool use; + tell it to search for a deferred tool it needs. LM Studio's `tool_choice: "auto"` permits tool use; it does not force the model to call this function. 4. **A call is emitted repeatedly or loaded tools never become usable:** capture the redacted `tool_search_call` / `tool_search_output` item types and call ids. OpenCodex preserves both in history so the model should see the completed search instead of issuing it forever. -See [The parser and bridge](/reference/architecture/#the-parser) for the wire mapping. There is no -provider-level setting that can compensate for a missing client declaration. +See [The parser and bridge](/reference/architecture/#the-parser) for the explicit wire mapping. +There is no provider-level setting that can add a missing `tool_search` declaration; ordinary +code-mode discovery remains a separate path. ### Catalog troubleshooting