This document provides a comprehensive analysis of how codex-cli communicates with ChatGPT API endpoints, including exact endpoints, headers, authentication, request schemas, and implementation details.
-**Purpose**: MCP (Model Context Protocol) server communication
**Important Note**: When using ChatGPT OAuth authentication, the base instructions field in the request is **required** and should reference "Codex" specifically. The example from the blog post shows:
```json
{
"instructions":"You are Codex, based on GPT-5. You are running as a coding agent ..."
}
```
This appears to be a requirement for the ChatGPT backend API to accept requests properly.
When using the ChatGPT OAuth API, requests often include a `developer` role message in the input array. This is distinct from the `instructions` field:
-**`instructions` field**: Base system instructions (e.g., "You are Codex, based on GPT-5...")
-**`developer` role message**: Additional contextual instructions injected as a message in the conversation
Example from the blog post:
```json
{
"input":[
{
"type":"message",
"role":"developer",
"content":[
{
"type":"input_text",
"text":"You are a helpful assistant. Respond directly to the user request without running tools or shell commands."
}
]
},
{
"type":"message",
"role":"user",
"content":[
{
"type":"input_text",
"text":"Generate an SVG of a pelican riding a bicycle"
## Message Conversion Between OpenAI and Codex Formats
### Overview
Codex uses the OpenAI Responses API format which is more structured than the traditional Chat Completions API. Understanding how to convert between standard OpenAI message formats and Codex's internal format is essential for implementing compatible clients.
### Key Type Definitions
#### Codex Internal Types (`ResponseInputItem` and `ResponseItem`)
Codex uses two main types for messages:
1. **`ResponseInputItem`** - Messages sent TO the API
2. **`ResponseItem`** - Messages received FROM the API
A session represents an entire conversation from start to finish. Understanding the flow of requests and how conversation state is maintained is essential for implementing a compatible client.