Skip to main content
Version: 3.6.1-rc.2

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/v1 for 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 invoke granted on the model you want to use.
  • For RAG tools, an API key with read granted 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​

  1. OpenCode sends the conversation and available tool declarations to /v1/chat/completions.
  2. The model returns a tool call.
  3. OpenCode executes local tools on your workstation.
  4. For a cm-gateway MCP tool, OpenCode calls /mcp/; the gateway authorizes and executes the RAG call.
  5. 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/search is 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, reasoning and max_output_tokens, with model changed 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:

IntegrationURLAuthenticationSelection
Model providerhttps://api.YOUR_DOMAIN/v1API key with model invokeExact ID from GET /v1/models
Gateway toolshttps://api.YOUR_DOMAIN/mcp/Bearer API key with RAG readTools 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​

SymptomCheck
Model request returns 401Key is exported as CM_MODEL_API_KEY, unexpired, and neither revoked nor disabled.
Model request returns 403The model key has invoke granted on the configured model.
Model not foundMODEL_ID exactly matches an id returned by GET /v1/models, and the model is ready.
cm-gateway is disconnectedThe MCP URL ends in /mcp/ and the authorization header includes Bearer.
No RAG tools appearThe RAG is ready and the RAG key has read granted on it.
The model writes tool calls as textSelect a coding or instruction model with tool-calling support.
Context is truncated too earlySet 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 websupports_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/searchChoose 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 messageThe 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 modelsChoose 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: