paperclip/docs/adapters/codex-local.md at 2c98c8e1e5a6f6c07face05739df15891ceb5d7f

Files

T

Devin Foley 67ca8287e8 fix(codex-local): seed managed auth into isolated homes (#8403 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The `codex_local` adapter isolates local Codex runs by assigning
managed `CODEX_HOME` state per company and per agent
> - PR #8272 tightened that isolation, but it left a gap: once
`CODEX_HOME` became explicit, the adapter treated it like a user-managed
override and skipped auth seeding
> - That meant newly isolated agents could launch with no usable
`auth.json`, hit OpenAI unauthenticated, and fail with `401 Missing
bearer`
> - Users who had already persisted one of those broken managed homes
could remain stranded even after config changes unless Paperclip
repaired the home itself
> - This pull request teaches Paperclip to seed managed homes correctly,
backfill already-stranded managed homes on startup, and reject
credential-less managed homes before they reach the provider
> - The benefit is that affected managed `codex_local` agents recover
automatically after upgrade and restart, without manual `CODEX_HOME`
surgery

## Linked Issues or Issue Description

- Fixes #497
- Refs #5028
- Related PR: #8272
- Related PR: #8399

## What Changed

- Distinguished Paperclip-managed `CODEX_HOME` paths from genuine
external overrides and always seeded auth into managed homes, even when
`CODEX_HOME` is explicit in config.
- Wrote API-key-backed `auth.json` files for managed homes when
`OPENAI_API_KEY` is configured, otherwise symlinked the shared Codex
auth for subscription/OAuth flows.
- Added a startup reconciliation pass that backfills already-isolated
managed homes created by the broken release so upgrade plus restart
repairs stranded agents automatically.
- Preserved previously resolved API-key auth when the stored
`OPENAI_API_KEY` binding is secret-backed and startup cannot resolve the
secret value directly.
- Hardened the managed-home preflight to require a credential-bearing
`auth.json`, not just file presence, and documented the recovery
behavior.
- Added regression tests covering managed-home seeding, fail-fast
behavior, and server-side startup reconciliation.

## Verification

```bash
pnpm exec vitest run packages/adapters/codex-local/src/server/codex-home.test.ts packages/adapters/codex-local/src/server/execute.auth.test.ts server/src/__tests__/codex-auth-reconciliation.test.ts server/src/__tests__/codex-local-execute.test.ts server/src/__tests__/server-startup-feedback-export.test.ts
pnpm --filter @paperclipai/adapter-codex-local typecheck
pnpm --filter @paperclipai/server typecheck
pnpm check:tokens
pnpm exec vitest run server/src/__tests__/server-startup-feedback-export.test.ts
```

GitHub Actions `PR` workflow is green on latest head `e5b1e08d4`,
including policy, typecheck, test shards, build, e2e, serialized server
suites, and canary dry run. Greptile Review is green on latest head with
0 comments added. No UI changes.

## Risks

- Startup reconciliation now mutates persisted managed Codex homes at
boot. Risk is low because it only touches Paperclip-managed
company/agent home paths and no-ops when a home already has usable auth.
- Genuine external `CODEX_HOME` overrides remain intentionally
self-managed, so those users still own repair steps inside their custom
home.
- Hosts with neither shared Codex auth nor an explicit per-agent API key
now fail earlier with a clearer adapter error instead of surfacing a
downstream `401`, which changes timing but not capability.

## Model Used

- OpenAI Codex, GPT-5-based coding agent in a local Codex session; exact
served model ID/context window were not exposed to the session. Tool use
and code execution were enabled.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change and contains no internal
Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-06-20 16:17:54 -07:00

4.5 KiB

Raw Blame History

title, summary

title	summary
Codex Local	OpenAI Codex local adapter setup and configuration

The codex_local adapter runs OpenAI's Codex CLI locally. It supports session persistence via previous_response_id chaining and skills injection through the global Codex skills directory.

Prerequisites

Codex CLI installed (codex command available)
OPENAI_API_KEY set in the environment or agent config

Configuration Fields

Field	Type	Required	Description
`cwd`	string	Yes	Working directory for the agent process (absolute path; created automatically if missing when permissions allow)
`model`	string	No	Model to use
`promptTemplate`	string	No	Prompt used for all runs
`env`	object	No	Environment variables (supports secret refs)
`timeoutSec`	number	No	Process timeout (0 = no timeout)
`graceSec`	number	No	Grace period before force-kill
`fastMode`	boolean	No	Enables Codex Fast mode. Currently supported on `gpt-5.4` only and burns credits faster
`dangerouslyBypassApprovalsAndSandbox`	boolean	No	Skip safety checks (dev only)

Session Persistence

Codex uses previous_response_id for session continuity. The adapter serializes and restores this across heartbeats, allowing the agent to maintain conversation context.

Skills Injection

The adapter symlinks Paperclip skills into the global Codex skills directory (~/.codex/skills). Existing user skills are not overwritten.

Fast Mode

When fastMode is enabled, Paperclip adds Codex config overrides equivalent to:

-c 'service_tier="fast"' -c 'features.fast_mode=true'

Paperclip currently applies that only when the selected model is gpt-5.4. On other models, the toggle is preserved in config but ignored at execution time to avoid unsupported runs.

Managed `CODEX_HOME`

When Paperclip is running inside a managed worktree instance (PAPERCLIP_IN_WORKTREE=true), the adapter instead uses a worktree-isolated CODEX_HOME under the Paperclip instance so Codex skills, sessions, logs, and other runtime state do not leak across checkouts. It seeds that isolated home from the user's main Codex home for shared auth/config continuity.

Per-agent isolation and auth seeding

For codex_local agents the server isolation guard pins each agent to a per-agent home (<instance>/companies/<companyId>/agents/<agentId>/codex-home) and sets OPENAI_API_KEY="" so an agent can never spend against the host API key or share another agent's Codex state.

A managed home is created empty, so the adapter must provision auth into it before launching Codex — otherwise the agent runs with zero credentials and the provider returns 401 Missing bearer. The seeding contract:

Managed homes (the default home and any configured CODEX_HOME under the company tree) are always seeded: the ChatGPT-subscription auth.json is symlinked from the host Codex home, or, when a per-agent OPENAI_API_KEY is configured, an API-key auth.json is written instead.
Genuine external overrides (a CODEX_HOME outside the Paperclip-managed company tree) are treated as self-managed and are never seeded or overwritten.
Fail-fast guard: if a managed home ends up with no usable auth.json and no configured API key, the run fails with an explicit adapter_failed ("no Codex credentials provisioned for managed home …") rather than emitting an unauthenticated request.

Manual Local CLI

For manual local CLI usage outside heartbeat runs (for example running as codexcoder directly), use:

pnpm paperclipai agent local-cli codexcoder --company-id <company-id>

This installs any missing skills, creates an agent API key, and prints shell exports to run as that agent.

Instructions Resolution

If instructionsFilePath is configured, Paperclip reads that file and prepends it to the stdin prompt sent to codex exec on every run.

This is separate from any workspace-level instruction discovery that Codex itself performs in the run cwd. Paperclip does not disable Codex-native repo instruction files, so a repo-local AGENTS.md may still be loaded by Codex in addition to the Paperclip-managed agent instructions.

Environment Test

The environment test checks:

Codex CLI is installed and accessible
Working directory is absolute and available (auto-created if missing and permitted)
Authentication signal (OPENAI_API_KEY presence)
A live hello probe (codex exec --json - with prompt Respond with hello.) to verify the CLI can actually run

4.5 KiB Raw Blame History