paperclip/docs/adapters/codex-local.md at 31c947bf7fb1ef6aa6517098b73dc8732518976d

Files

Dotta 654463c28f feat(cli): add agent local-cli command for skill install and env export

New subcommand to install Paperclip skills for Claude/Codex agents and
print the required PAPERCLIP_* environment variables for local CLI
usage outside heartbeat runs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-07 08:59:45 -06:00

2.0 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
`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.

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.

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

2.0 KiB Raw Blame History