Support and document external editing of `.codex/environments/environment.toml`

What variant of Codex are you using?

Codex App on macOS, version 26.820.80927 (build 7271; bundled CLI 0.150.0-alpha.8).

What feature would you like to see?

Please make .codex/environments/environment.toml a supported, documented declarative project configuration that users and coding agents can edit outside the Environment settings UI.

The settings UI can remain the primary editor and generator. For valid external edits, Codex should:

• reload the edited configuration reliably;
• preserve or predictably normalize all documented fields when the file is later opened and saved in the UI;
• report actionable errors for invalid TOML, unsupported versions, unknown fields, or invalid values instead of silently discarding or replacing them; and
• replace the generated DO NOT EDIT MANUALLY warning with wording that links to the supported editing and reference documentation.

Please also add an environment.toml reference to the official Local environments documentation covering:

• the exact path and discovery rules, including whether multiple environment files are supported;
• the versioning and schema for all supported setup, action, cleanup, and platform fields;
• valid platform identifiers and default-versus-platform-specific precedence;
• quoting, escaping, and multiline command behavior;
• when Codex regenerates, normalizes, or overwrites the file;
• the recommended Git workflow for a checked-in environment configuration; and
• complete macOS/Linux/Windows examples.

A published JSON Schema/Taplo schema and/or a command such as codex environment validate would make external authoring safer, but either is optional if the app provides equivalent validation.

Because setup and action entries execute commands, externally edited executable fields should retain Codex's existing trust, review, and confirmation safeguards. This request is not asking Codex to silently execute newly changed commands.

Why this matters

The official Local environments documentation says that environments are configured through the desktop settings pane, that their generated project configuration can be checked into Git and shared, and that platform-specific action scripts can be defined. However, it does not document the environment.toml schema, whether external editing is supported, or the regeneration/round-trip contract.

At the same time, generated files begin with:

# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY

This creates friction for a file that is intentionally stored in the repository and reviewed through Git. It also prevents coding agents from safely maintaining the configuration as part of repository work.

Grounded cross-platform example

An all-platform Windows-style action checked into a project contained:

[[actions]]
name = "Run"
icon = "run"
command = ".\\run_chain.cmd"

Invoking it from the Codex action on macOS exited with status 127 (command not found). Changing the action through the Environment settings UI generated:

[[actions]]
name = "Run"
icon = "run"
command = "./run_chain"
platform = "darwin"

The generated macOS command then completed successfully in a dry-run and removed the prior shell-syntax failure. The required configuration change is small and easy to review, but the generated warning and missing schema mean users and agents are explicitly discouraged from making it directly.

Suggested acceptance criteria

1. A valid externally authored or edited environment.toml is loaded without requiring it to be recreated in Settings.
2. Opening and saving that environment in Settings preserves all documented values or applies documented normalization.
3. Invalid configuration produces a clear file/field-level diagnostic.
4. Official documentation publishes the supported schema, platform behavior, regeneration rules, and cross-platform examples.
5. The file header accurately describes the supported editing and trust contract.

Related context

• Local environments documentation
• The openai/codex repository's own checked-in generated environment file
• #12722 — Can't edit a Run-Configuration after it's created is closed and covers editing through Settings, not external file editing.
• #15768 — Support configurable base_branch in environment.toml requests one additional key, not an external-editing or schema contract.

I found these and other related reports while searching open and closed issues, but none that covers both supported external editing and the schema/regeneration documentation contract.

Start with the generated .codex/environments/environment.toml and the linked Local environments documentation, then trace how the Environment settings UI loads, saves, and regenerates that file. Define the supported schema, validation and round-trip behavior across the listed platforms, and update the documentation and header so the acceptance criteria can be tested.