Inspect the delivery path before the value
A 401 response after launching an agent does not by itself identify the problem. Check the project, the protected name and the route first. Phantom's why command explains whether a key is protected and how phantom exec delivers it without displaying the credential value.
1. Confirm the project and exact name
Run these checks in the repository you initialized. Secret names are case-sensitive. A missing entry can mean you are in another project, used a different name or initialized the vault on another machine. Use the JSON why report for value-free delivery diagnostics, and report only names and metadata; persistent mappings are not public identifiers.
phantom status
phantom list
phantom why OPENAI_API_KEY --json2. Distinguish a missing route from a rejected credential
If delivery reports no_route, no built-in proxy route injects that protected key. The child receives a session placeholder that the provider will not accept. Replacing it with the real key in an agent-visible file defeats the intended workflow; stop and evaluate a supported path instead.
phantom exec refuses custom routes from repository configuration. A person can review custom routes for foreground phantom start, but that is a separate operator workflow, not an automatic fix for agent execution.
3. Treat a locked vault as unavailable, not empty
A locked encrypted-file vault causes inventory tools to refuse an answer rather than report an empty alternate backend. The MCP error is -32600. Have the operator follow the vault-specific unlock guidance outside agent context and retry or restart the MCP server. Do not delete the vault or recreate its entries based on an unavailable inventory.
4. Retry only the intended supported request
For supported clients, phantom exec sets implemented SDK base-URL overrides and starts an authenticated loopback proxy. Do not hardcode a proxy port; the operating system selects a free port for each launch. Run a bounded, authorized non-production request and record its result separately from local configuration checks.
phantom agent doctor
phantom exec -- codexKnow what the diagnosis does not prove
Local readiness and metadata do not establish provider permission, hosted-service availability or deployment acceptance. Phantom does not erase credentials previously exposed in logs or history. If disclosure occurred, use the provider's revocation or rotation process and update the vault from a trusted terminal.