Codex CLI with Azure OpenAI gpt-5.6-sol fails due to Codex-specific tools / collaboration namespace

Open 💬 6 comments Opened Jul 9, 2026 by Soorma718

💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What version of Codex CLI is running?

0.144.0

What subscription do you have?

Azure API

Which model were you using?

gpt-5.6-sol

What platform is your computer?

Linux / WSL

What terminal emulator and version are you using (if applicable)?

Ghostty

Codex doctor report

What issue are you seeing?

Azure deployment:

``text gpt-5.6-sol``

Model version:

``text 2026-07-09``

Deployment type:

``text Global Standard``

Azure portal target URI:

``text https://************.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview``

Relevant Codex config

```toml
model = "gpt-5.6-sol"
model_provider = "azure"
model_reasoning_effort = "max"
web_search = "disabled"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "************.cognitiveservices.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses"
query_params = { "api-version" = "2025-04-01-preview" }
```

I also tested with:

``toml base_url = "https://************.cognitiveservices.azure.com/openai/v1" wire_api = "responses"``

### What works

A direct Azure Responses API call to the portal-provided endpoint works successfully.

Example request:

``http POST https:/***************.azure.com/openai/responses?api-version=2025-04-01-preview api-key: <redacted> Content-Type: application/json``

Payload:

``json { "model": "gpt-5.6-sol", "input": "Reply exactly: OK", "max_output_tokens": 64, "store": false, "reasoning": { "effort": "high", "summary": "auto" } }``

Response succeeds and returns:

``text OK``

I also tested Azure-supported reasoning efforts:

``text none works low works medium works high works xhigh works max works ultra rejected by Azure``

So the Azure deployment, endpoint, key, and model are valid.

### What fails in Codex

Running Codex CLI against the same Azure deployment fails before the model can answer.

Example:

``bash codex exec \ --ephemeral \ --skip-git-repo-check \ -c 'model_provider="azure"' \ -c 'model_providers.azure.name="Azure OpenAI"' \ -c 'model_providers.azure.base_url="**********.cognitiveservices.azure.com/openai"' \ -c 'model_providers.azure.env_key="AZURE_OPENAI_API_KEY"' \ -c 'model_providers.azure.wire_api="responses"' \ -c 'model_providers.azure.query_params={"api-version"="2025-04-01-preview"}' \ -c 'web_search="disabled"' \ -c 'model_reasoning_effort="high"' \ "Reply exactly: OK"``

Error:

``json { "error": { "message": "X-OpenAI-Internal-Codex-Responses-Lite only supports function tools, custom tools, and client-executed tool search.", "type": "invalid_request_error", "param": "tools", "code": "unsupported_value" } }``

### Additional debugging

I put a localhost proxy between Codex and Azure to inspect the outgoing request.

Codex sends a Responses API payload containing input items of type:

``json { "type": "additional_tools", "role": "developer", "tools": [...] }``

The included additional tools were:

``text exec wait request_user_input collaboration``

The collaboration entry is a namespace tool:

``json { "type": "namespace", "name": "collaboration", "description": "Tools for spawning and managing sub-agents." }``

When forwarding this request to Azure after stripping Codex-only headers, Azure rejects it with:

``json { "error": { "message": "Invalid Value: 'tools'. Namespace 'collaboration' is reserved for encrypted tool use by this model.", "type": "invalid_request_error", "param": "tools", "code": null } }``

If the proxy removes only the collaboration namespace tool and forwards the rest of the request to Azure, Codex works successfully, including normal
shell tool use.

For example, after stripping the collaboration namespace, this works:

``bash codex exec "Use shell to run pwd, then reply with only the resulting path."``

Codex successfully runs:

``bash pwd``

and returns the expected path.

### Expected behavior

Codex should support Azure OpenAI Responses deployments such as gpt-5.6-sol without sending Azure-incompatible internal headers or unsupported tool
namespace declarations.

At minimum, when model_provider is a custom/Azure provider, Codex should either:

avoid sending X-OpenAI-Internal-Codex-Responses-Lite, or
avoid sending hosted/internal Codex-only tool formats to Azure, or
feature-detect / config-gate the collaboration namespace tool, or
provide a config option to disable collaboration/multi-agent tool injection for providers that reject it.

### Actual behavior

Codex sends provider-incompatible internal/tool metadata, causing Azure to reject the request even though the same model/deployment works through the
Azure Responses API directly.

### Workaround

A local proxy can make it work by:

forwarding requests to:

``text https://*********************.azure.com/openai/responses?api-version=2025-04-01-preview``

forwarding only minimal auth/content headers,
removing the collaboration namespace from additional_tools.

With that workaround, Codex works with:

``text gpt-5.6-sol reasoning.effort = max``

but native Codex subagents / collaboration cannot work because the rejected namespace has to be stripped.

### Request

Could Codex add proper Azure OpenAI Responses support for current GPT-5.6 Azure deployments, especially:

no X-OpenAI-Internal-Codex-Responses-Lite behavior for Azure/custom providers,
no Azure-incompatible collaboration namespace tool unless supported,
a config flag to disable collaboration/multi-agent additional tools,
support for Azure preview Responses endpoint format:

``text /openai/responses?api-version=2025-04-01-preview``

support for model_reasoning_effort = "max" for models that accept it.

Direct Azure API calls confirm that gpt-5.6-sol itself works and accepts max; the failure appears to be Codex request-shaping/tooling compatibility, not
the Azure deployment.

What steps can reproduce the bug?

Running Codex CLI against the same Azure deployment fails before the model can answer.

Example:

Error:

What is the expected behavior?

_No response_

Additional information

_No response_

View original on GitHub ↗

6 Comments

github-actions[bot] contributor · 1 month ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

#31870
#31864

Powered by Codex Action

thiagoperes · 1 month ago

I used this gpt-5.6-sol-xhigh to make a one-liner fix. Use at your own discretion:

python3 -c 'import json,os,re,shutil,subprocess,tempfile; from pathlib import Path; d=Path.home()/".codex"; d.mkdir(parents=True,exist_ok=True); exe=shutil.which("codex") or (_ for _ in ()).throw(SystemExit("codex not found in PATH")); td=tempfile.TemporaryDirectory(); env=os.environ.copy(); env["CODEX_HOME"]=td.name; data=json.loads(subprocess.check_output([exe,"debug","models"],env=env,text=True)); td.cleanup(); model=next((x for x in data.get("models",[]) if x.get("slug")=="gpt-5.6-sol"),None); model is not None or (_ for _ in ()).throw(SystemExit("gpt-5.6-sol not found in Codex model catalog")); model["use_responses_lite"]=False; model["multi_agent_version"]="v1"; catalog=d/"models.azure.json"; tmp=d/"models.azure.json.tmp"; tmp.write_text(json.dumps(data,indent=2)+"\n"); os.replace(tmp,catalog); cfg=d/"config.toml"; old=cfg.read_text() if cfg.exists() else ""; cfg.exists() and shutil.copy2(cfg,str(cfg)+".bak"); first=re.search(r"(?m)^[ \t]*\[",old); head=old[:first.start()] if first else old; tail=old[first.start():] if first else ""; head=re.sub(r"(?m)^[ \t]*(?:model|model_catalog_json)[ \t]*=.*(?:\n|$)","",head); text="model = \"gpt-5.6-sol\"\nmodel_catalog_json = "+json.dumps(str(catalog))+"\n"+head+tail; text+="" if text.endswith("\n") else "\n"; settings="multi_agent = true\nmulti_agent_v2 = false\n"; section=re.compile(r"(?ms)^([ \t]*\[features\][ \t]*(?:#.*)?\n)(.*?)(?=^[ \t]*\[|\Z)"); text=section.sub(lambda m:m.group(1)+settings+re.sub(r"(?m)^[ \t]*multi_agent(?:_v2)?[ \t]*=.*(?:\n|$)","",m.group(2)),text,count=1) if section.search(text) else text+"\n[features]\n"+settings; ctmp=d/"config.toml.tmp"; ctmp.write_text(text); os.replace(ctmp,cfg); print("Codex Azure workaround installed; fully restart Codex/VS Code and start a new conversation.")'

kenny7869 · 1 month ago

It looks like Azure has resolved this issue, as I haven't encountered the same problem again today(2026-07-13 09:56 UTC+8).

Hyacehila · 1 month ago

It looks as though the Azure-specific behavior behind this class of failures has been addressed upstream, so I do not want to present a local workaround as a replacement for updating to the official fix.

I am maintaining Codex Provider Compatibility for a narrower remaining use case: users of other third-party OpenAI-compatible providers who still see text responses work while Codex tool calls, such as shell, functions, MCP, or collaboration-related tools, disappear or are described only in text.

The tool only considers gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna. It begins with a read-only doctor check and refuses to make changes unless the local catalog, configuration, version state, and safety checks indicate that the case is applicable. When appropriate, it can create a reversible local catalog override that uses the standard Responses tool shape; rollback removes only the changes owned by the tool.

This is not an official fix and may not address every collaboration-namespace or provider-specific failure. It does not modify provider settings, read credentials or auth.json, send requests to the configured provider, or automatically select a Codex version when multiple surfaces conflict.

I am sharing it as a diagnostic aid and possible temporary mitigation for users whose issue remains after applying the relevant upstream updates. If anyone tests it with another third-party provider, a redacted doctor result, Codex version, provider category, and observed tool-call behavior would be helpful. Please keep endpoints, credentials, raw requests, usernames, and private paths out of the thread.

absolutegravitas · 18 days ago

I can reproduce this on Codex CLI 0.147.0 with Azure Foundry deployment gpt-5.6-sol (also affecting the gpt-5.6-terra/luna profile setup). The documented Azure v1 profile is valid and direct Azure Responses calls work, but Codex fails before model execution with:

Invalid 'input[0].tools[0].description': empty string

I also tested the /openai + api-version form, /openai/v1, disabled all MCP servers, and disabled features.shell_tool; the same validation error remains. This appears to be Codex-injected built-in/additional tool metadata that Azure rejects. Native Azure Codex is currently unusable for review/tool workflows without a proxy that strips the incompatible Codex tool payload.

Microsoft Azure Foundry is a piece of dogshit for shipping this kind of incompatibility.

absolutegravitas · 18 days ago

Update: the workaround from this issue is applicable to Codex CLI 0.147.0.

For the Azure profile, I created a profile-local model catalog override for gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna:

"use_responses_lite": false,
"multi_agent_version": "v1"

with multi_agent_v2 = false in the Azure profile. The global model catalog remains unchanged.

After applying this override, an ephemeral Azure run completed successfully and returned OK; the previous Invalid input[0].tools[0].description: empty string error no longer occurs. This confirms the failure was Codex model-catalog/tool-mode selection, not the Azure deployment or API key.