Skip to content

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

Description

@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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    CLIIssues related to the Codex CLIconfigIssues involving config.toml, config keys, config merging, or config updatesenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions