Z.AI GLM-4.7 Integration Issue Summary

[jscraik]

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: [Bug] Custom role maps agno-agi/agno#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: [Bug] Custom role maps agno-agi/agno#3261

Date

2026-01-21

What steps can reproduce the bug?

1. Set up Z.AI API key:

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

2. Configure custom provider in ~/.codex/config.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"

3. Add Z_AI_API_KEY to shell environment whitelist:

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

4. Launch Codex with the GLM profile:

   codex --profile glm

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

   > hello
   

6. Observe the error:

   {"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

[etraut-openai]

Thanks for the bug report. This sounds like a limitation of the Z.AI endpoint. Please report the incompatbility to the Z.AI maintainers.

[cornellsh]

Fixed, use this https://github.com/cornellsh/codex-proxy

[JakkuSakura]

https://github.com/JakkuSakura/codex-proxy
A fork of @cornellsh 's awesome work. It's easier to setup with uv and more intuiative. Also ported a few features back to upstream as PR now