This guide shows how to configure Codex CLI so it uses LM Studio by default.

Prerequisites

Install and configure:

  • Codex CLI
  • LM Studio
  • A local model loaded in LM Studio, for example openai/gpt-oss-20b

Start the LM Studio local server and confirm it is available at:

http://localhost:1234/v1

You can verify the models endpoint:

curl http://localhost:1234/v1/models

Example response:

{
  "data": [
    {
      "id": "google/gemma-4-e4b",
      "object": "model",
      "owned_by": "ashish"
    },
    {
      "id": "openai/gpt-oss-20b",
      "object": "model",
      "owned_by": "ashish"
    },
    {
      "id": "qwen/qwen3-8b",
      "object": "model",
      "owned_by": "ashish"
    }
  ],
  "object": "list"
}

Required Files

This setup needs two Codex config files:

  1. ~/.codex/config.toml
  2. ~/.codex/lmstudio-models.json

Configure Codex

Create or update: ~/.codex/config.toml

model_provider = "lmstudio"
oss_provider = "lmstudio"
model = "openai/gpt-oss-20b"
model_catalog_json = "/Users/ashish.doneriya/.codex/lmstudio-models.json"

[features]
apps = false
tool_suggest = false
plugins = false
multi_agent = false
image_generation = false
browser_use = false
browser_use_external = false
computer_use = false

If you want a portable path, replace the absolute path with your own user path:

model_catalog_json = "/Users/YOUR_USERNAME/.codex/lmstudio-models.json"

Add Local Model Metadata

Create: ~/.codex/lmstudio-models.json

{
  "models": [
    {
      "slug": "openai/gpt-oss-20b",
      "display_name": "GPT OSS 20B",
      "description": "Local LM Studio model",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [],
      "shell_type": "shell_command",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 99,
      "additional_speed_tiers": [],
      "service_tiers": [],
      "availability_nux": null,
      "upgrade": null,
      "base_instructions": "You are Codex, a coding assistant running locally. Be concise, practical, and use tools only when needed.",
      "supports_reasoning_summaries": false,
      "default_reasoning_summary": "none",
      "support_verbosity": false,
      "default_verbosity": "low",
      "apply_patch_tool_type": "freeform",
      "web_search_tool_type": "text",
      "truncation_policy": {
        "mode": "tokens",
        "limit": 8000
      },
      "supports_parallel_tool_calls": false,
      "supports_image_detail_original": false,
      "context_window": 131072,
      "max_context_window": 131072,
      "effective_context_window_percent": 75,
      "experimental_supported_tools": [],
      "input_modalities": [
        "text"
      ],
      "supports_search_tool": false
    }
  ]
}

Why This File Is Needed

Codex may not have built-in metadata for LM Studio model IDs such as openai/gpt-oss-20b. Without local metadata, Codex can fall back to metadata for a hosted OpenAI model. That can cause errors like:

{
  "error": {
    "message": "Invalid",
    "type": "invalid_request_error",
    "param": "tools.11.type",
    "code": "invalid_string"
  }
}

The local model catalog tells Codex to use safer settings for LM Studio:

  • Text-only input
  • No web search tool
  • No image generation
  • No browser tools
  • No plugin/app tools
  • No parallel tool calls

Verify the Setup

Run:

codex doctor

You should see Codex load your config successfully.

To test with a simple prompt:

codex exec --ephemeral --skip-git-repo-check "Reply with exactly: ok"

Expected output should show:

model: openai/gpt-oss-20b
provider: lmstudio

Now you can simply run:

codex

Optional: Use a Faster Model

If openai/gpt-oss-20b feels slow, try a smaller model exposed by LM Studio, for example:

  • qwen/qwen3-8b
  • google/gemma-4-e4b

Update both files.

In config.toml:

model = "qwen/qwen3-8b"

In lmstudio-models.json:

"slug": "qwen/qwen3-8b",
"display_name": "Qwen3 8B"

Common Issues

LM Studio is not running

If Codex cannot connect, verify:

curl http://localhost:1234/v1/models

If that fails, start the LM Studio server.

Wrong provider is being used

Check:

codex doctor

Look for:

model provider: lmstudio

If it says openai, make sure this is present in ~/.codex/config.toml:

model_provider = "lmstudio"

Invalid tool type error

If you see:

tools.11.type invalid_string

disable unsupported feature tools in config.toml`:

[features]
apps = false
tool_suggest = false
plugins = false
multi_agent = false
image_generation = false
browser_use = false
browser_use_external = false
computer_use = false

Also make sure model_catalog_json points to your local model catalog.

Final Result

After this setup:

codex

will start Codex using LM Studio as the default provider with your local model.