Configure coding agents
Coding agents such as OpenCode and Codex CLI run on your workstation, where they can read files, edit code, and run commands. You can route their model requests through the ConfidentialMind Model Gateway and give them access to gateway-hosted RAG tools.
This guide configures OpenCode with two gateway surfaces:
- The OpenAI-compatible API at
https://api.YOUR_DOMAIN/v1for model calls. - The remote MCP endpoint at
https://api.YOUR_DOMAIN/mcp/for RAG and other gateway-hosted tools.
OpenCode remains the agent loop. It executes local tools itself and calls the gateway's MCP endpoint when the model selects a gateway-hosted tool. Steps 1 to 4 are for OpenCode. For Codex CLI, see Configure Codex CLI.
Before you begin
To configure OpenCode, you need:
- OpenCode installed on your workstation.
- Your Model Gateway domain — shown as API URL at the bottom of the portal sidebar, next to a button that copies it.
- A personal API key with
invokegranted on the model you want to use. - For RAG tools, an API key with
readgranted on each RAG the agent may search. - A chat model that supports tool calling and is suitable for coding tasks.
A single key can carry both model and RAG grants. You can also use separate keys so model and RAG access can be rotated or revoked independently.
1. Export your API keys
Set the keys in the shell from which you will start OpenCode:
export CM_MODEL_API_KEY='cm_api_…'
export CM_RAG_API_KEY='cm_api_…'
If one key has both grants, export the same value for both variables. Keep the keys out of opencode.json and version
control.
2. Find the model ID
List the chat models the model key is allowed to invoke:
curl -sS "https://api.YOUR_DOMAIN/v1/models" \
-H "Authorization: Bearer $CM_MODEL_API_KEY"
Choose the exact id of a coding-capable model from the response. The display name is not interchangeable with the
ID.
3. Configure OpenCode
Create opencode.json in the root of your project. To use the provider for every project, put the same configuration
in ~/.config/opencode/opencode.json instead.
Replace YOUR_DOMAIN and MODEL_ID. The limits in these examples are the tested values for Qwen3.6 27B; use the served
model's limits when configuring a different model. For a model deployed on the platform, set limit.context to the
Context length shown on its page under Models in the portal. Consult the model's official page or model card
for its supported inputs, tool calling, reasoning options, and output limit, and confirm the limits configured on your
deployment. See
OpenCode's v1 model settings or
v2 model settings for how to express those settings in your config.
Choose the example for your installed version. If you are upgrading, follow OpenCode's Migrate from V1 guide.
OpenCode v1
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"cmgw": {
"npm": "@ai-sdk/openai-compatible",
"name": "CM Gateway",
"options": {
"baseURL": "https://api.YOUR_DOMAIN/v1",
"apiKey": "{env:CM_MODEL_API_KEY}"
},
"models": {
"MODEL_ID": {
"name": "Qwen3.6 27B via CM Gateway",
"limit": {
"context": 262144,
"output": 32768
}
}
}
}
},
"mcp": {
"cm-gateway": {
"type": "remote",
"url": "https://api.YOUR_DOMAIN/mcp/",
"enabled": true,
"oauth": false,
"headers": {
"Authorization": "Bearer {env:CM_RAG_API_KEY}"
}
}
}
}
OpenCode v2
V2 uses providers, package, settings, and mcp.servers. The aisdk: prefix retains the same AI SDK adapter as
in the v1 example. MCP servers connect by default, so the v1 enabled field is omitted.
{
"$schema": "https://opencode.ai/config.json",
"providers": {
"cmgw": {
"package": "aisdk:@ai-sdk/openai-compatible",
"name": "CM Gateway",
"settings": {
"baseURL": "https://api.YOUR_DOMAIN/v1",
"apiKey": "{env:CM_MODEL_API_KEY}"
},
"models": {
"MODEL_ID": {
"name": "Qwen3.6 27B via CM Gateway",
"limit": {
"context": 262144,
"output": 32768
}
}
}
}
},
"mcp": {
"servers": {
"cm-gateway": {
"type": "remote",
"url": "https://api.YOUR_DOMAIN/mcp/",
"oauth": false,
"headers": {
"Authorization": "Bearer {env:CM_RAG_API_KEY}"
}
}
}
}
}
In both examples, cmgw/MODEL_ID combines the local provider name with the model ID sent to the gateway.
@ai-sdk/openai-compatible uses /v1/chat/completions, including streaming and client-driven tool calls.
The cm-gateway MCP server exposes only the tools the RAG key is authorized to use. To expose RAG tools only and hide
other gateway-hosted MCP tools, change its URL to https://api.YOUR_DOMAIN/mcp/?kind=rag.
4. Verify the connections
Check that OpenCode loads the model. With v1, filter by provider:
opencode models cmgw
With v2, list models and look for cmgw/MODEL_ID:
opencode models
Check the MCP connection:
opencode mcp list
The output should show cm-gateway as connected.
Run a model-only check:
opencode run --model cmgw/MODEL_ID \
"Reply with: ConfidentialMind gateway reached"
Then verify a gateway-hosted RAG call:
opencode run --model cmgw/MODEL_ID \
"Use an available cm-gateway RAG search tool to answer a question about the indexed documents."
In interactive OpenCode, run opencode and use /models to select the model under CM Gateway.
How tool calls are routed
- OpenCode sends the conversation and available tool declarations to
/v1/chat/completions. - The model returns a tool call.
- OpenCode executes local tools on your workstation.
- For a
cm-gatewayMCP tool, OpenCode calls/mcp/; the gateway authorizes and executes the RAG call. - OpenCode returns the tool result to the model for the next step.
The model API key and RAG API key are checked independently. Giving the model key invoke does not grant RAG access,
and giving the RAG key read does not grant model access.
Configure Codex CLI
Codex CLI calls models through the gateway's Responses API. These steps were tested with Codex CLI 0.167.0.
Export your model API key in the shell from which you will start Codex:
export CM_MODEL_API_KEY='cm_api_…'
Add the gateway as a model provider in ~/.codex/config.toml. Replace MODEL_ID with the exact id returned by
GET /v1/models (see Find the model ID) and YOUR_DOMAIN with your Model Gateway domain:
model_provider = "cmgw"
model = "MODEL_ID"
web_search = "disabled"
[model_providers.cmgw]
name = "CM Gateway"
base_url = "https://api.YOUR_DOMAIN/v1"
env_key = "CM_MODEL_API_KEY"
wire_api = "responses"
If you already have a config.toml, merge these settings into it: keep the three root keys above the first table, and
do not add a second [model_providers.cmgw] table. Do not set name to "OpenAI"; Codex treats a provider with that
name as its built-in OpenAI provider.
For gpt-5.5 and for model IDs it has no built-in metadata for, Codex declares OpenAI-hosted web search unless
web_search = "disabled" is set, and the gateway rejects that tool with HTTP 400. Keep "disabled" for those models.
For the gpt-6.x model IDs, Codex 0.167.0 sends no hosted web search tool; to let Codex search the web on them, see
Web search on gpt-6.x models.
Check the connection:
codex exec --skip-git-repo-check --ephemeral "Reply with: gateway reached"
This command checks the connection only; it does not test tool use.
Codex CLI 0.167.0 was tested with the public model IDs gpt-6-astra, gpt-6.1-sol and gpt-6-luna-openai, using
codex exec and the Codex app server against a local deployment, with Codex's shell tools, goals, multi-agent, apps and
plugins switched off. Other Codex settings have not been tested. For these models Codex sends its tools in an
additional_tools input item, which the gateway accepts for direct models provided by OpenAI when the request sets
store: false (see Use tools); Codex already sends store: false. Resuming or
compacting a Codex session and image tool results have not been tested. Codex has not been tested with the gateway's MCP
endpoint, so this configuration adds no MCP server.
For gpt-5.5, Codex declares custom (apply_patch) and client tool_search tools instead. The gateway accepts these
on the same terms, but this has not been tested with Codex against a deployed gateway. For a model ID it has no
built-in metadata for, Codex declares its MCP tools as namespace tools, which the gateway accepts on the same terms. A
request that declares these tool types to a model from another provider returns HTTP 400.
Web search on gpt-6.x models
On the gpt-6.x model IDs, Codex searches the web with its own web.run tool. Codex runs the tool itself and sends each
search to the provider's /v1/alpha/search endpoint, which the gateway forwards to OpenAI. Codex only offers this tool
to a custom provider that opts in. To turn it on, set web_search to "live" and add
supports_standalone_web_search to the provider table:
model_provider = "cmgw"
model = "gpt-6-astra"
web_search = "live"
[model_providers.cmgw]
name = "CM Gateway"
base_url = "https://api.YOUR_DOMAIN/v1"
env_key = "CM_MODEL_API_KEY"
wire_api = "responses"
supports_standalone_web_search = true
Use this only with gpt-6.x model IDs; for gpt-5.5, keep web_search = "disabled". Codex recognizes a model by the
start of its ID, so this applies to IDs that begin with a gpt-6.x model name, such as gpt-6-astra or
gpt-6-luna-openai. With web_search = "cached", or with
no web_search key, Codex asks OpenAI not to fetch live pages (external_web_access: false); only "live" was tested.
Keep in mind:
/v1/alpha/searchis an undocumented OpenAI endpoint that Codex uses. OpenAI can change it without notice.- The gateway forwards it only to models provided by OpenAI directly, or aliases that resolve to one. Any caller who
may use the model may search. The gateway forwards the members
id,model,input,commands,settings,reasoningandmax_output_tokens, withmodelchanged to the provider's model ID, and drops any others. - OpenAI bills searches to the account behind the model's connector. Searches are not recorded in platform usage, and token quotas do not limit them.
- Codex retries a search that fails with a server error up to four times, so a search that reaches the gateway's timeout (2 minutes by default) can hold a Codex turn for about 10 minutes.
Configure another coding agent
An agent must support both a custom OpenAI-compatible model provider and a remote streamable-HTTP MCP server:
| Integration | URL | Authentication | Selection |
|---|---|---|---|
| Model provider | https://api.YOUR_DOMAIN/v1 | API key with model invoke | Exact ID from GET /v1/models |
| Gateway tools | https://api.YOUR_DOMAIN/mcp/ | Bearer API key with RAG read | Tools are filtered by grants |
The coding agent remains responsible for the agent loop. The gateway routes model calls, federates authorized RAG tools, executes gateway-hosted tool calls, and records usage and audit events.
For Codex CLI, see Configure Codex CLI.
Claude Code is not supported. Claude Code 2.1.319 sends a context_management setting in every Messages API request,
and the gateway rejects it with HTTP 400 (context_management is not supported) before any model is called.
For VS Code agent mode, see Configure VS Code agent mode. VS Code uses the Custom Endpoint language model provider and manages the conversation on your machine.
Troubleshooting
| Symptom | Check |
|---|---|
Model request returns 401 | Key is exported as CM_MODEL_API_KEY, unexpired, and neither revoked nor disabled. |
Model request returns 403 | The model key has invoke granted on the configured model. |
| Model not found | MODEL_ID exactly matches an id returned by GET /v1/models, and the model is ready. |
cm-gateway is disconnected | The MCP URL ends in /mcp/ and the authorization header includes Bearer. |
| No RAG tools appear | The RAG is ready and the RAG key has read granted on it. |
| The model writes tool calls as text | Select a coding or instruction model with tool-calling support. |
| Context is truncated too early | Set limit.context to the model's Context length in the portal and limit.output to the output limit configured on your deployment. |
Codex request returns 400 with unsupported tool type "web_search" | Set web_search = "disabled" in the Codex configuration. Codex declares this tool for gpt-5.5 and for model IDs it has no built-in metadata for. |
| Codex on a gpt-6.x model never searches the web | supports_standalone_web_search = true is in the [model_providers.cmgw] table and web_search is not "disabled"; "live" is the tested mode. See Web search on gpt-6.x models. |
Codex search returns 400 with does not support /v1/alpha/search | Choose a model the platform calls at OpenAI directly, or an alias that resolves to one. |
Codex search returns an error starting with http 401 or http 403 and OpenAI's message | The OpenAI key or account behind the model's connector was rejected, not your platform API key. Ask the platform administrator to check the connector. |
Codex request returns 400 with additional tools are supported only for OpenAI models | Choose a model the platform calls at OpenAI directly, or an alias that resolves to one, not an Azure OpenAI model, a model from another provider or a preset agent. Codex 0.167.0 already sends store: false. See Use tools. |
A disabled key can be enabled again from the API Keys page. Enabling preserves expiry dates and grants; the secret must still be unexpired and have the required permissions.
For the complete configuration schema, see the OpenCode docs for your version:
- v1: Providers and MCP servers.
- v2: Providers and MCP servers.