[TypeScript SDK] Support raw config overrides for dotted map keys

Open 💬 0 comments Opened Jul 30, 2026 by thibaultsoubeste

What feature would you like to see?

Expose raw --config overrides in @openai/codex-sdk, alongside the existing structured
config object.

The TypeScript SDK currently recursively flattens every object key into a dotted path:

new Codex({
  config: {
    permissions: {
      andromede: {
        filesystem: {
          ":root": "read",
          "/tmp/sdk-path.with-dot": "deny",
        },
      },
    },
  },
});

This produces an override equivalent to:

--config permissions.andromede.filesystem./tmp/sdk-path.with-dot="deny"

The path is then interpreted as multiple key segments, so the SDK cannot represent this
filesystem map entry. This affects any config map keyed by user-controlled strings containing
periods, including ordinary paths such as .worktrees, .env, or .taskgen3.

The CLI's quoted-key limitation is already tracked in #34261 and #35780. Even if quoted key
segments are fixed there, the TypeScript serializer currently does not quote or escape object-key
segments. The working CLI form today is to pass the map as an inline TOML table:

--config 'permissions.andromede.filesystem={":root"="read","/tmp/sdk-path.with-dot"="deny"}'

A small provider-neutral API could be:

new Codex({
  config: {
    model_reasoning_effort: "high",
  },
  configOverrides: [
    'permissions.andromede.filesystem={":root"="read","/tmp/sdk-path.with-dot"="deny"}',
  ],
});

The exact option name is flexible. Each string should be passed unchanged as a separate
--config argument, without shell interpretation. Existing structured config behavior can
remain unchanged.

The Python SDK already exposes this escape hatch as CodexConfig.config_overrides and appends each
value directly as ["--config", value]:

https://github.com/openai/codex/blob/main/sdk/python/src/openai_codex/client.py#L201-L204

https://github.com/openai/codex/blob/main/sdk/python/src/openai_codex/client.py#L242-L252

Related: #5779 requested arbitrary -c support before the structured TypeScript config option
existed, but was closed for inactivity.

Why is this useful?

Multi-agent services need different permission profiles for concurrent Codex processes. Mutating a
shared CODEX_HOME/config.toml introduces a race where one process can start with another process's
permissions. Per-process raw arguments avoid shared mutable configuration while preserving the
normal TypeScript SDK execution and resume paths.

This also provides a general escape hatch when new Codex configuration shapes cannot be represented
losslessly by the SDK's recursive object flattener, without requiring a new typed SDK option for
each CLI setting.

View original on GitHub ↗