Codex++ with OpenCode Go Throwing Errors? A Five-Step Troubleshooting Guide

Background: Why Are Errors Spiking Recently?

Many users running Codex++ with OpenCode Go have been hitting a wave of connection errors lately. Based on hands-on analysis by Bilibili creator Yuze, two root causes are driving this surge:

First, starting September 6th, OpenCode Go began enforcing a server-side requirement that all requests include an X-OpenCode-Session header — a response to a prior incident where a flood of uncached requests hammered their servers. Any request missing this header is now rejected outright.

Second, Codex++ version 26.9 merged portions of the Codex CLI codebase and dropped support for Chat mode. If your config file still uses the old Chat protocol or local routing, you'll get 502 errors.

In short, this wave of issues is the combined result of tighter server-side policies and a client-side protocol upgrade landing at the same time. Let's walk through the fixes step by step.

Finding Your Config File: Locating the .codex Directory

All changes happen inside Codex++'s configuration file. To get there: open Codex++, select the OpenCode border node, navigate to the Configure Page, then find the config file inside the .codex folder on your C drive.

You can open the file however you like — double-clicking it in VSCode works fine, or you can use plain Notepad. Once you have it open, here are the five key changes to make.

Five-Step Fix

Step 1: Add the Session Header (Fixes "Missing Session" Errors)

For Missing X-OpenCode-Session errors, you need to add a session header to the custom headers section of your config file.

This Session value isn't a fixed string — you generate it locally. The approach demonstrated by the creator involves running a command in PowerShell to generate the session string, then pasting it into the appropriate header field in your config. Once the server sees a valid session header, this error goes away.

X-OpenCode-Session is a custom HTTP request header used to establish a session identity between the client and server. The server checks this header to verify that a request is coming from a legitimate, initialized client rather than an unauthorized bare request. This kind of mechanism is common in API services that need to guard against large-scale unauthenticated traffic — when the server detects that a request lacks a session identifier, it rejects it at the gateway layer to protect backend resources.

A common way to generate a session string in PowerShell is with a command like [System.Guid]::NewGuid().ToString(), which produces a unique identifier, or by using a dedicated script provided by the OpenCode Go client that generates a token in a specific format. The resulting string goes into the custom headers section of your config, typically as "X-OpenCode-Session": "<generated string>". The value is generated locally — there's no registration step with the server; it just checks that the header exists and is properly formatted.

Step 2: Update the BaseURL (Fixes 502 Direct-Connection Errors)

The core of the 502 error is a wrong BaseURL. Since the new version requires Response mode and local routing is no longer supported, you need to change the BaseURL from your old local address to OpenCode Go's official service endpoint.

This step goes hand-in-hand with Step 3 — the protocol changed, so the routing target has to change with it. Otherwise your requests never reach the server correctly.

Step 3: Switch to Response Mode

Change the response protocol in your config from chat to response. In the latest version this defaults to Response, but if you upgraded from an older version you likely still have chat set and will need to change it manually. This is one of the most critical fixes for 502 and reconnection errors.

Chat mode (corresponding to OpenAI's /v1/chat/completions endpoint) takes a list of conversational messages as input and has historically been the go-to protocol for AI coding assistants. Response mode (corresponding to the newer /v1/responses endpoint) is a standard OpenAI introduced in 2025 that supports richer tool calling, state management, and streaming output control — and it's what Codex CLI has fully migrated to in recent versions.

The two modes differ in request body structure, response field naming, and streaming event formats, which means downstream services and model providers need to explicitly support Response mode to work correctly. This is why certain models (like GLM and Qwen3) throw reconnection errors after the protocol switch — their API gateways haven't yet implemented full compatibility with the Response protocol. That's a gateway compatibility issue, not a limitation of the models themselves.

Step 4: Remove ComputerUse from the Notify Section

If your config's notify section includes anything related to ComputerUse, delete it. As the creator points out, leaving this in can cause a cascade of problems when restarting Codex++ — things like Windows Sandbox failures or initialization errors.

ComputerUse is a capability Anthropic introduced with the Claude 3.5 series, allowing AI models to directly control a computer's interface (mouse clicks, keyboard input, screenshot recognition, etc.). Tools like Codex++ integrate it as an optional notification/plugin module. Since this feature requires a system-level sandbox or virtualized environment (typically Windows Sandbox on Windows), keeping this config entry in place will trigger sandbox creation failures at startup whenever the runtime environment doesn't meet the prerequisites or the relevant services aren't properly initialized — causing the entire client to fail to start. Removing the entry prevents Codex++ from attempting to spin up the ComputerUse sandbox at all, sidestepping this bottleneck entirely.

Step 5: Clean Up Node Environment Variables

Finally, remove any leftover node-related environment variables from your config. These can interfere with the initialization process. Don't worry about deleting them — Codex will automatically reconfigure this environment on restart, so there's nothing you need to maintain manually.

Saving and Applying Changes: Make Sure to Fully Restart

Once you've made all five changes, do a quick sanity check: is the BaseURL correct, is the session header present, is the protocol set to Response? If everything looks good, save the file.

There's one easy-to-miss gotcha here: simply deleting the node in the UI is not enough to fully apply your config changes. Testing by the creator confirmed that even after deleting and navigating back in OpenCode, some old config values persist. The correct approach is to fully quit the Codex++ process and relaunch it — otherwise your changes may not be loaded.

After restarting, send a quick test message. If it responds quickly and normally, you're all set.

Model Compatibility Note: Not All Models Work

Because of the switch to Response mode, not all models will work correctly — this is worth paying close attention to. Based on the creator's testing:

• Working: DeepSeek is confirmed to work; MiniMax is also reported to work.
• Not yet working: The GLM series (e.g., GLM-4.5/4.6) and Qwen3 series (e.g., Qwen3 Flash) are currently unsupported and will throw reconnection errors when called.

This is fundamentally a Response vs. Chat protocol compatibility issue. If you rely on GLM or Qwen3, your best option for now is to switch to DeepSeek and wait for the Codex author to expand model compatibility in a future update.

Summary

This wave of Codex++ and OpenCode Go errors, while it looks messy on the surface, really comes down to one core story: the server now requires a session header, and the client now enforces Response protocol. Master the five-step fix — add the session header, update the BaseURL, switch to Response mode, remove ComputerUse, and clear node environment variables — then do a full restart, and you'll resolve the vast majority of issues. Just remember to factor in model-level compatibility and stick to models that currently support Response mode.