Codex Auth Tools Missing? Preflight Before Browser Work

If Codex says a plugin can use a secret manager or owner-authentication tool but that tool is absent from the live session, stop before opening the login flow. Do not paste a password, token, recovery code, or cookie into chat. First prove that one exact authentication path is callable. Use a connected, schema-inspected Aident Loadout Action for supported SaaS work; otherwise keep the login in an owner-controlled browser surface or report the workflow as blocked.

This guide is for the narrow failure where a skill, plugin, or policy describes authentication help, but the current Codex tool inventory does not contain the named tool. It is not a workaround for CAPTCHA, a provider outage, or a website that forbids automation.

Treat the Live Tool Inventory as the Boundary

A declared capability is not the same as a callable capability. A skill can describe what a workflow expects, while the current task exposes a smaller runtime tool set because of product support, account state, platform, policy, or session configuration.

Before any login attempt, require these four facts:

If the first answer is no, do not let the agent improvise a credential path. A missing tool does not become available because the prompt says it should exist.

Run a Read-Only Aident Loadout Preflight

Start by checking the installed public CLI without printing provider secrets:

aident account auth status
aident vault vault --action status

Expected result: the account command reports an authenticated Aident session, and Vault reports only connection readiness and metadata. If the intended provider is disconnected, connect it through the supported Vault flow. Do not substitute a token pasted into chat.

Next, search by the job rather than guessing an Action name:

aident capabilities search \
  --query 'read one GitHub issue' \
  --types '["action"]' \
  --limit 5

Copy the exact canonical Action name from the result. Inspect its contract before execution:

aident capabilities get \
  --name 'composio:github_tools:github_get_an_issue' \
  --parts '["description","inputSchema"]'

Then validate one bounded, read-only request:

aident capabilities preflight \
  --name 'composio:github_tools:github_get_an_issue' \
  --input '{"owner":"openai","repo":"codex","issue_number":37695}'

Expected result: the input is valid and the preflight returns a cost or approval boundary without dispatching the provider operation. If the canonical name changes, search again and use the returned name. If preflight reports invalid input, missing authentication, unavailable pricing, or an approval requirement you do not accept, stop there.

This probe proves the safe broker path, not the original browser login. It also avoids turning a troubleshooting session into a provider write.

Decide Which Authentication Path You Actually Have

Use the narrowest path that matches the job.

A connected SaaS Action exists

Use the Action contract. Keep provider credentials in Vault, pass only the documented business inputs, preflight the exact request, and review any write or approval boundary before execution.

This is the best fit for tasks such as reading an issue, listing a calendar, or fetching an analytics report when the corresponding integration is connected. The agent needs the operation inputs, not the underlying provider token.

If you still need to choose the provider contract, compare the operational boundaries in MCP API Keys vs OAuth before connecting it.

The website already has an owner-controlled session

Let the owner authenticate in the supported browser surface. Keep passwords, passkeys, recovery codes, CAPTCHA, and MFA in the owner's hands. After authentication, ask the agent to verify only the intended account and page before it acts.

Do not claim that a browser session gives Codex access to a password manager. A logged-in browser and a callable secret-consumption tool are different capabilities.

No supported Action or owner handoff exists

Report the workflow as blocked. Record the missing tool name, current Codex version, surface, operating system, plugin version, and non-secret connection state. That is safer and more useful than repeated short login windows that expire.

Separate Four Similar Failure Classes

Do not merge these into one generic "authentication failed" diagnosis. Each boundary has a different safe recovery.

Why Repeated Login Windows Do Not Fix the Problem

A short login window can prove that the browser surface opens. It cannot create a missing runtime tool, confirm a provider connection, or turn a local password manager into an agent-callable interface.

A current Codex issue reports exactly this mismatch: a custom plugin declared owner-authentication and secret-manager assistance, while the live task exposed none of the named tools. The report asks for either a scoped credential-consumption interface or a deterministic preflight. That is a user report, not confirmation of a universal Codex defect, but the safety conclusion is durable: tool availability must be proven before a secret-bearing step begins.

OpenAI's current Codex documentation supports the same boundary from several directions:

• cached Codex credentials belong in the operating-system credential store or protected auth file, not chat;

• shell environment policy can exclude secret-bearing variables from spawned commands;

• sandbox and approval settings define action boundaries but do not make absent tools appear; and

• agent-friendly CLIs should fail clearly when authentication is missing.

Avoid Credential-Recovery Shortcuts

Do not use any of these as a fix:

• paste a password, API key, cookie, recovery code, or full environment dump into chat;

• ask Codex to scrape a browser password store or operating-system keychain;

• grant Full Access so a missing authentication tool can search the machine;

• install an unreviewed helper that prints a secret to standard output;

• weaken CAPTCHA, MFA, passkey, or device-approval controls;

• repeatedly relaunch expiring login windows without changing the capability state; or

• assume a plugin description proves its advertised tools are live.

If a secret was exposed during diagnosis, revoke or rotate it through the provider before continuing.

Verify One Safe End-to-End Result

After account status, Vault status, schema inspection, and preflight succeed, execute only the bounded read operation you reviewed. For the GitHub example, success means one issue record returns with its number, state, title, updated time, and canonical URL. It should create no comment, reaction, label, edit, or other provider write.

Then inspect the recent Aident audit record if your environment exposes it. The operation, connection, timing, and cost boundary should match the request you approved. Stop if the output contains an unexpected account, scope, side effect, or credential-shaped value.

Reusable Preflight Prompt

Give Codex this bounded request before browser work:

Check my Aident Loadout account and Vault status. Search for one Action that completes the requested SaaS job, inspect the exact current schema, and preflight the smallest valid input. Return the canonical Action name, connection readiness, input validity, cost estimate, approval requirement, and whether the operation is read-only or write-capable. Do not execute, open a browser, start OAuth, request a password, inspect a local credential store, print environment variables, or broaden permissions.

Success is measurable: the response identifies one callable path or says that none exists before any credential-bearing step begins.

Follow https://aident.ai/SETUP.md

Set up Aident Loadout and preflight a safe authentication path.

Sources

• OpenAI Codex issue 37695: declared owner-auth and secret-manager capabilities absent at runtime

• OpenAI: Codex authentication and credential storage

• OpenAI: advanced Codex configuration and shell environment policy

• OpenAI: Codex sandbox and approval boundaries

• OpenAI: create an agent-friendly CLI

• Aident Loadout setup

Refresh this guide when issue 37695 changes state, Codex documents runtime owner-assistance tools, or Aident Loadout changes its account, Vault, capability inspection, or preflight contract.