Tool call protocol validation errors with strict third-party OpenAI-compatible providers

[k-l-lambda]

What version of Codex is running?

codex-tui 0.0.0

What subscription do you have?

Pro

Which model were you using?

gpt-5.1

What platform is your computer?

Microsoft Windows NT 10.0.22631.0 x64

What issue are you seeing?

When using Codex with certain third-party OpenAI-compatible API providers (like OpenRouter), requests fail with 400 Bad Request errors related to tool call protocol violations:

{
"message": "An assistant message with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'.",
"type": "invalid_request_error"
}

These providers strictly validate the OpenAI Chat Completions protocol and reject requests where:

1. Assistant messages with tool_calls have no matching tool response messages
2. Other messages interrupt the sequence between assistant+tool_calls and tool responses

The same providers work fine with official OpenAI API, suggesting OpenAI may be more lenient or automatically correct these protocol violations.

Example invalid message sequence:
[assistant + tool_calls] ← Makes tool call
[assistant] ← Interrupting message (VIOLATION!)
[tool] ← Tool response

This triggers repeated errors and reconnection cycles, making these providers unusable.

What steps can reproduce the bug?

1. Configure Codex to use a third-party OpenAI-compatible provider that strictly validates protocol
2. Use Codex for normal coding tasks that involve tool calls (file reads, edits, etc.)
3. Observe 400 errors related to tool call protocol, especially after:
   • API streaming interruptions (network timeouts, rate limits)
   • Retry attempts that replay partial conversation history

Configuration example:

[model_providers.custom]
name = "Third Party Provider"
base_url = "https://api.example.com/v1"

Error logs:
[ERROR] Turn error: unexpected status 400 Bad Request
[ERROR] Response body: {"message": "An assistant message with 'tool_calls' must be followed by tool messages..."}

What is the expected behavior?

• Requests should comply with OpenAI Chat Completions protocol
• Tool calls should always have matching tool responses
• No messages should interrupt the tool_call → tool_response sequence
• Stable streaming without protocol validation errors

Additional information

Root cause analysis:

According to https://platform.openai.com/docs/api-reference/chat/create, the protocol requires:

An assistant message with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'. No other messages are allowed between them.

Codex's conversation history can violate this in two ways:

1. Incomplete tool calls: When API streaming is interrupted mid-request (network timeout, 429 rate limit), the assistant message with tool_calls gets recorded, but
   tool execution never completes. On retry, this incomplete tool call remains in the history without matching responses.
2. Sequence violations: During streaming, Codex may record an assistant text message between the tool_calls message and tool responses, breaking the required
   sequence.

Why some providers fail while others work:

• Official OpenAI API: Appears to be lenient or automatically fixes protocol violations
• Strict third-party providers: Enforce protocol exactly per specification and reject violations with 400 errors

The strict validation is actually correct per the OpenAI specification, but Codex's conversation history management doesn't guarantee protocol compliance.

Impact:

• Some third-party providers become completely unusable
• Frequent reconnection cycles
• Poor user experience with protocol-strict providers

Affected component: codex-rs/core/src/chat_completions.rs - Message construction for Chat Completions API

Environment:

• Codex CLI version: Latest main branch
• Platform: Windows/Linux/macOS (all affected)
• Multiple third-party OpenAI-compatible providers affected

[github-actions]

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

• Add codespell support (config, workflow to detect/not fix) and make it fix some typos #903

Powered by Codex Action

[ben-h-a]

Im having the same issue when developing an MCP. it is persistent even when reinstalling codex, deleting my ~/.codex dir and resetting my config.toml.

as soon as codex tries to call any tool:

> list the files in this dir


■ unexpected status 400 Bad Request: {
  "error": {
    "message": "An assistant message with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'. The following tool_call_ids did not have response messages: call_xhLrDUQ07mPH3N5vrkSBwKLY",
    "type": "invalid_request_error",
    "param": "messages.[4].role",
    "code": null
  }
}

[k-l-lambda]

Im having the same issue when developing an MCP. it is persistent even when reinstalling codex, deleting my ~/.codex dir and resetting my config.toml.

as soon as codex tries to call any tool:

> list the files in this dir


■ unexpected status 400 Bad Request: {
  "error": {
    "message": "An assistant message with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'. The following tool_call_ids did not have response messages: call_xhLrDUQ07mPH3N5vrkSBwKLY",
    "type": "invalid_request_error",
    "param": "messages.[4].role",
    "code": null
  }
}

Try my PR. The official repo rejected my PR, and I'm considering to publish a forked npm package. Togather with some other bug fixes.

[jxy]

This is a dup of #7051