Z.AI GLM-4.7 Integration Issue Summary

What version of Codex is running?

codex-cli 0.88.0-alpha.17

What subscription do you have?

Pro

Which model were you using?

_No response_

What platform is your computer?

arwin 25.3.0 arm64 arm

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

Ghostty

What issue are you seeing?

Z.AI GLM-4.7 Integration Issue Summary

Current Status: BLOCKED - Codex Bug

Issue Description

When using Z.AI's GLM-4.7 model with Codex CLI, getting error:

{"error":{"code":"1214","message":"Incorrect role information"}}

Root Cause

Codex is sending messages with the developer role (used in OpenAI's Responses API and newer models), but Z.AI's Chat Completions endpoint only accepts:

• system
• user
• assistant

What We've Tried

✅ Fixed Issues

1. API Key: Changed env_key from ZAI_API_KEY to Z_AI_API_KEY (with underscore)
2. Endpoint: Set wire_api = "chat" so Codex calls /chat/completions instead of /responses
3. MCP Servers: Fixed "Bearer Bearer" bug using env_http_headers workaround

❌ Current Blocker

Codex is not converting developer role to system role when using wire_api = "chat" with custom providers.

Current Configuration

[model_providers.zai]
name = "Z.AI Coding Plan"
base_url = "https://api.z.ai/api/coding/paas/v4"
env_key = "Z_AI_API_KEY"
wire_api = "chat"  # Should trigger role conversion, but doesn't

[profiles.glm]
model_provider = "zai"
model = "GLM-4.7"
sandbox_mode = "danger-full-access"
approval_policy = "never"
forced_login_method = "api"

Missing Configuration Option

Codex does NOT have a documented configuration option for role mapping like:

• role_map (doesn't exist)
• supports_developer_role (doesn't exist)
• use_system_role (doesn't exist)

Evidence

• Z.AI API docs show they support standard OpenAI Chat Completions format with system, user, assistant roles
• Other tools (agno-agi) have encountered the same issue: <https://github.com/agno-agi/agno/issues/3261>
• OpenAI's newer models use developer role, but Chat Completions API uses system role
• Codex should auto-convert when wire_api = "chat" but appears not to for custom providers

References

• Z.AI API Docs: <https://docs.z.ai/api-reference/llm/chat-completion>
• Z.AI Coding Plan: <https://docs.z.ai/guides/llm/glm-4.7>
• Codex Config Reference: <https://developers.openai.com/codex/config-reference>
• Similar issue in agno: <https://github.com/agno-agi/agno/issues/3261>

Date

2026-01-21

What steps can reproduce the bug?

1. Set up Z.AI API key:

``bash
export Z_AI_API_KEY="your-api-key-here"
``

1. Configure custom provider in ~/.codex/config.toml:

```toml
[model_providers.zai]
name = "Z.AI Coding Plan"
base_url = "https://api.z.ai/api/coding/paas/v4"
env_key = "Z_AI_API_KEY"
wire_api = "chat" # Explicitly set to use Chat Completions format

[profiles.glm]
model_provider = "zai"
model = "GLM-4.7"
sandbox_mode = "danger-full-access"
approval_policy = "never"
forced_login_method = "api"
```

1. Add Z_AI_API_KEY to shell environment whitelist:

``toml
[shell_environment_policy]
inherit = "none"
include_only = [
"PATH",
"HOME",
"Z_AI_API_KEY",
# ... other vars
]
``

1. Launch Codex with the GLM profile:

``bash
codex --profile glm
``

1. Send any message (even a simple "hello"):

``
> hello
``

1. Observe the error:

``json
{"error":{"code":"1214","message":"Incorrect role information"}}
``

Expected Behavior

When wire_api = "chat" is set, Codex should:

1. Convert internal developer role messages to system role
2. Send standard Chat Completions format to Z.AI
3. Successfully receive responses from GLM-4.7

Actual Behavior

Codex sends messages with developer role to Z.AI's Chat Completions endpoint, which only accepts system, user, and assistant roles, resulting in error code 1214.

Environment

• Codex Version: (run codex --version)
• OS: macOS (darwin)
• Shell: zsh
• Z.AI API: <https://api.z.ai/api/coding/paas/v4>
• Z.AI Model: GLM-4.7

What is the expected behavior?

When wire_api = "chat" is set in the model provider configuration, Codex should:

Automatically convert role names from Codex's internal format to the Chat Completions API format:

developer role → system role
Keep user and assistant roles as-is
Send standard OpenAI Chat Completions format to Z.AI's endpoint at https://api.z.ai/api/coding/paas/v4/chat/completions

Successfully receive responses from the GLM-4.7 model without role-related errors

Work seamlessly with custom providers that implement the OpenAI Chat Completions API standard

Why This Should Work
The wire_api = "chat" setting exists specifically to tell Codex: "This provider uses the Chat Completions API format"
OpenAI's Chat Completions API uses system, user, and assistant roles
OpenAI's newer Responses API (and GPT-5+ models) use the developer role
Codex should handle this translation automatically when switching between API formats
Current Actual Behavior
Instead, Codex is:

Sending messages with the developer role directly to Z.AI
Not performing the role conversion despite wire_api = "chat" being set
Causing Z.AI to reject the request with error code 1214: "Incorrect role information"
This appears to be a bug where the role conversion logic works for OpenAI's own endpoints but doesn't work for custom providers, even when they're explicitly configured to use the Chat Completions format.

Additional information

_No response_