settings and memory

where do instructions and settings go?

the configuration gets easier to follow when each file has a job:

thing you want to preserve	place it belongs
repository conventions and verification commands	AGENTS.md
personal runtime defaults	~/.codex/config.toml
supported settings shared by a trusted project	.codex/config.toml
a procedure used for a particular kind of task	a skill
the current bug, desired change, and finish line	the task prompt

AGENTS.md gives the model instructions. config files select runtime behavior. writing “ask before using the network” in a paragraph and configuring network restrictions have different effects: one guides the agent; the other constrains commands.

which setting wins?

as of September 7, 2026, the documented configuration order is command line overrides, trusted project configuration, a selected profile, user configuration, system defaults, then built in defaults. project settings closer to the working directory take precedence over those higher up the tree. managed requirements can restrict the values a session may use.

Codex skips project .codex/ layers until the project is trusted. review the repository’s config, hooks, and rules before granting that trust. some settings, including provider and authentication choices, are reserved for configuration outside the project. use the reference when a repository setting appears to be ignored.

try a temporary setting

for a local inspection session, start from the repository root:

codex --sandbox read-only --ask-for-approval on-request

copy

this sets the sandbox and approval policy for that invocation. it leaves the saved config alone. ask Codex to locate the relevant code and explain its verification path before deciding whether to start an editing session.

when several defaults belong together, a profile can collect them. the current format uses a sibling file such as ~/.codex/inspect.config.toml, selected with codex --profile inspect:

sandbox_mode = "read-only"
approval_policy = "on-request"

copy

trusted project config can override profile values. the explicit command line flags above take higher precedence. inspect the active session after switching profiles, especially when the app and CLI use different installed versions.

instructions or memory?

project instructions should explain what applies now. memory can supply useful context from earlier work: a failed approach, a preference, or a pointer to an investigation. local Codex memories are generated from eligible previous chats when enabled, and updates can arrive later.

check remembered facts against the current checkout and the user’s latest instructions. a memory saying a test uses one command can become stale when the project changes package managers. update the canonical project instruction so every new task can find the correction.

when will Codex ask for approval?

the sandbox controls filesystem and network reach for commands. approval policy controls when execution needs a decision. never means Codex cannot ask for a new approval; restricted commands can still fail. it does not grant extra access. the approval guide explains these combinations.

named permission profiles provide another way to describe filesystem and network policy. they are separate from the config profiles above. follow one supported permission configuration format, and check the active policy before assuming a directory or destination is reachable.

why is a command failing?

when an operation fails, check which host ran it, the working directory, the loaded config layer, and the service identity. a missing executable on a remote machine needs an environment fix. a request to a service under the wrong account needs an identity fix. changing permissions would leave either cause unresolved.

keep credentials in the service’s authentication flow or an appropriate secret store. use config to name the connection and its scope. verify a harmless read before depending on it for a write.