mirror of
https://github.com/openai/codex.git
synced 2026-10-19 17:28:46 +00:00
rreichel3-oai
0f54c3a97b
Allow requirements.toml and cloud requirements to specify forced_chatgpt_workspace_id using the same single string or array shape as config.toml. Prefer the requirements value during config resolution, expose it through configRequirements/read, and regenerate app-server schema fixtures. Document requirements precedence and add targeted coverage for requirements parsing, config resolution, API mapping, and cloud requirements fixtures.
129 lines
5.2 KiB
Markdown
129 lines
5.2 KiB
Markdown
# Configuration
|
|
|
|
For basic configuration instructions, see [this documentation](https://developers.openai.com/codex/config-basic).
|
|
|
|
For advanced configuration instructions, see [this documentation](https://developers.openai.com/codex/config-advanced).
|
|
|
|
For a full configuration reference, see [this documentation](https://developers.openai.com/codex/config-reference).
|
|
|
|
## Connecting to MCP servers
|
|
|
|
Codex can connect to MCP servers configured in `~/.codex/config.toml`. See the configuration reference for the latest MCP server options:
|
|
|
|
- https://developers.openai.com/codex/config-reference
|
|
|
|
MCP tools default to serialized calls. To mark every tool exposed by one server
|
|
as eligible for parallel tool calls, set `supports_parallel_tool_calls` on that
|
|
server:
|
|
|
|
```toml
|
|
[mcp_servers.docs]
|
|
command = "docs-server"
|
|
supports_parallel_tool_calls = true
|
|
```
|
|
|
|
Only enable parallel calls for MCP servers whose tools are safe to run at the
|
|
same time. If tools read and write shared state, files, databases, or external
|
|
resources, review those read/write race conditions before enabling this setting.
|
|
|
|
## MCP tool approvals
|
|
|
|
Codex stores per-tool approval overrides for custom MCP servers under
|
|
`mcp_servers` in `~/.codex/config.toml`:
|
|
|
|
```toml
|
|
[mcp_servers.docs.tools.search]
|
|
approval_mode = "approve"
|
|
```
|
|
|
|
## Apps (Connectors)
|
|
|
|
Use `$` in the composer to insert a ChatGPT connector; the popover lists accessible
|
|
apps. The `/apps` command lists available and installed apps. Connected apps appear first
|
|
and are labeled as connected; others are marked as can be installed.
|
|
|
|
## Notify
|
|
|
|
Codex can run a notification hook when the agent finishes a turn. See the configuration reference for the latest notification settings:
|
|
|
|
- https://developers.openai.com/codex/config-reference
|
|
|
|
When Codex knows which client started the turn, the legacy notify JSON payload also includes a top-level `client` field. The TUI reports `codex-tui`, and the app server reports the `clientInfo.name` value from `initialize`.
|
|
|
|
## JSON Schema
|
|
|
|
The generated JSON Schema for `config.toml` lives at `codex-rs/core/config.schema.json`.
|
|
|
|
## Managed ChatGPT Workspace Restrictions
|
|
|
|
Managed deployments can restrict ChatGPT login to one or more workspace IDs with
|
|
`forced_chatgpt_workspace_id` in either `config.toml` or `requirements.toml`.
|
|
Existing single-workspace configurations remain valid:
|
|
|
|
```toml
|
|
forced_chatgpt_workspace_id = "workspace_id"
|
|
```
|
|
|
|
To allow any of several workspaces, set the same key to a list:
|
|
|
|
```toml
|
|
forced_chatgpt_workspace_id = ["workspace_id_a", "workspace_id_b"]
|
|
```
|
|
|
|
Codex trims whitespace from configured workspace IDs and ignores empty entries.
|
|
An empty list remains an active allowlist and allows no ChatGPT workspace. If
|
|
this setting is present, ChatGPT credentials whose token workspace ID is not in
|
|
the configured allowlist are rejected and logged out. A value from
|
|
`requirements.toml` takes precedence over ordinary config because requirements
|
|
are managed policy.
|
|
|
|
## SQLite State DB
|
|
|
|
Codex stores the SQLite-backed state DB under `sqlite_home` (config key) or the
|
|
`CODEX_SQLITE_HOME` environment variable. When unset, WorkspaceWrite sandbox
|
|
sessions default to a temp directory; other modes default to `CODEX_HOME`.
|
|
|
|
## Custom CA Certificates
|
|
|
|
Codex can trust a custom root CA bundle for outbound HTTPS and secure websocket
|
|
connections when enterprise proxies or gateways intercept TLS. This applies to
|
|
login flows and to Codex's other external connections, including Codex
|
|
components that build reqwest clients or secure websocket clients through the
|
|
shared `codex-client` CA-loading path and remote MCP connections that use it.
|
|
|
|
Set `CODEX_CA_CERTIFICATE` to the path of a PEM file containing one or more
|
|
certificate blocks to use a Codex-specific CA bundle. If
|
|
`CODEX_CA_CERTIFICATE` is unset, Codex falls back to `SSL_CERT_FILE`. If
|
|
neither variable is set, Codex uses the system root certificates.
|
|
|
|
`CODEX_CA_CERTIFICATE` takes precedence over `SSL_CERT_FILE`. Empty values are
|
|
treated as unset.
|
|
|
|
The PEM file may contain multiple certificates. Codex also tolerates OpenSSL
|
|
`TRUSTED CERTIFICATE` labels and ignores well-formed `X509 CRL` sections in the
|
|
same bundle. If the file is empty, unreadable, or malformed, the affected Codex
|
|
HTTP or secure websocket connection reports a user-facing error that points
|
|
back to these environment variables.
|
|
|
|
## Notices
|
|
|
|
Codex stores "do not show again" flags for some UI prompts under the `[notice]` table.
|
|
|
|
## Plan mode defaults
|
|
|
|
`plan_mode_reasoning_effort` lets you set a Plan-mode-specific default reasoning
|
|
effort override. When unset, Plan mode uses the built-in Plan preset default
|
|
(currently `medium`). When explicitly set (including `none`), it overrides the
|
|
Plan preset. The string value `none` means "no reasoning" (an explicit Plan
|
|
override), not "inherit the global default". There is currently no separate
|
|
config value for "follow the global default in Plan mode".
|
|
|
|
## Realtime start instructions
|
|
|
|
`experimental_realtime_start_instructions` lets you replace the built-in
|
|
developer message Codex inserts when realtime becomes active. It only affects
|
|
the realtime start message in prompt history and does not change websocket
|
|
backend prompt settings or the realtime end/inactive message.
|
|
|
|
Ctrl+C/Ctrl+D quitting uses a ~1 second double-press hint (`ctrl + c again to quit`).
|