Codex CLI#

Codex CLI talks to OpenAI’s Responses API, so it uses Lockpin’s OpenAI route, http://127.0.0.1:8787/openai/v1.

Connect with one command#

lockpin connect codex
codex --profile lockpin

It adds a Lockpin provider to ~/.codex/config.toml and a lockpin profile (~/.codex/lockpin.config.toml, the format Codex reads since 0.134). codex --profile lockpin goes through Lockpin, and plain codex is unchanged.

  • lockpin connect codex -default makes Lockpin the default provider instead. Codex files earlier sessions by provider, so it then lists them only with codex resume --all.

  • Both show the change and ask first, and keep a backup.

  • lockpin disconnect codex takes it out. A Codex session that is already running keeps Lockpin’s address, so restart it after you disconnect.

A company enforces the provider with Codex’s requirements.toml instead.

Set the provider yourself#

Codex no longer reads OPENAI_BASE_URL from the environment, so set the address in ~/.codex/config.toml. Project .codex/config.toml files cannot set it.

model_provider = "lockpin"

[model_providers.lockpin]
name = "Lockpin"
base_url = "http://127.0.0.1:8787/openai/v1"
env_key = "OPENAI_API_KEY"          # the variable Codex reads the key from
wire_api = "responses"
# Sent on every call. It can only lower the budget below -default-budget.
http_headers = { "X-Lockpin-Budget-Usd" = "0.50" }
# Sent only when the variable is set, so each run can name its task.
env_http_headers = { "X-Lockpin-Task" = "LOCKPIN_TASK" }

http_headers and env_http_headers are Codex’s own provider settings for extra headers. Then run:

export OPENAI_API_KEY=...        # your own key; Lockpin passes it on
LOCKPIN_TASK=fix-login-bug codex

$env:OPENAI_API_KEY = "..."      # your own key; Lockpin passes it on
$env:LOCKPIN_TASK = "fix-login-bug"; codex

On a team server, use the server’s URL for base_url, and put your lp_... key in the variable that env_key names. See Set up a team.

Task name and budget#

Each session is its own task, with nothing to set. A call without LOCKPIN_TASK is charged to its Codex session, as a task such as codex-0199ab12 (the first 8 characters of the session id Codex sends). So each session has its own budget, -default-budget ($1.00 unless you change it). -session-tasks=false puts all sessions on the shared default task instead.

With LOCKPIN_TASK set, the call is charged to that task. A new task name is a new budget. The budget header can only lower a budget: for more, start Lockpin with a higher -default-budget, or raise the task in the meter.

For a single run, lockpin run names the task for you:

lockpin run -task nightly-refactor -- codex exec "fix the tests"

When the cap hits#

Lockpin answers HTTP 402 in OpenAI’s error shape, with code budget_exceeded and a message that starts with lockpin:, before the call reaches OpenAI. Codex shows the API error. Raise the task’s budget in the meter, or use a new task name, and run again. If the meter, VS Code or the overlay is open, Lockpin first holds the call and asks there. See Approvals at the cap.

Review prompts before they are sent#

Lockpin can run as Codex’s UserPromptSubmit hook and review each prompt before the model sees it. It blocks a prompt that holds a secret or whose fixes would save at least $0.10 or 20,000 tokens this turn, and warns about smaller findings.

lockpin hooks install -agent codex -model gpt-6.1-sol

It prints the change to ~/.codex/hooks.json as a diff (the project’s .codex/hooks.json with -project, in a trusted project) and writes it only after you answer yes. Review and trust the hook once in Codex with /hooks. lockpin hooks uninstall -agent codex takes it out.

To add it by hand:

{"hooks": {"UserPromptSubmit": [{"hooks": [{"type": "command",
  "command": "lockpin hooks review -hook codex -model gpt-6.1-sol", "timeout": 15}]}]}}

codex exec stops a blocked prompt but prints only “UserPromptSubmit Blocked”, not the reason.

Models#

A model with no price is refused with HTTP 400 unknown_model. Check yours with lockpin providers -models. To add one, see Prices.

Verify#

  • lockpin doctor shows Codex sending its calls through Lockpin.

  • After one prompt with codex --profile lockpin, the meter shows a task named codex- and 8 characters, or the name in LOCKPIN_TASK.