Przejdź do treści
Biblioteka skilli
AI i agenci · Integracja z narzędziem

codex-auth-helper

/codex-auth-helper

Czyta lokalny stan uwierzytelnienia Codex, odświeża tokeny i buduje klientów oraz modele Responses oparte na Codex, podłączane do pydantic-ai, pydantic-acp lub LangChain.

Repozytorium
acpkit ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
30.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
42
Przestarzałość

Brak sygnałów. Repozytorium zmienione 30.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: examples/codex_chat_openai_graph.py, examples/codex_responses_agent.py

Co robi i kiedy

Czyta lokalny stan uwierzytelnienia Codex, odświeża tokeny i buduje klientów oraz modele Responses oparte na Codex, podłączane do pydantic-ai, pydantic-acp lub LangChain.

Oryginalny opis (EN)

Use for `codex-auth-helper` tasks: reading local Codex auth state, refreshing tokens, building Codex-backed Responses clients/models, and wiring them into `pydantic-ai`, `pydantic-acp`, or LangChain.

Jak działa

  1. Start Here
  2. Quick Routing
  3. Package Boundary
  4. Do Not Confuse With
  5. Primary References
  6. Public Surface
  7. Module Guide
  8. What It Does
  9. Common Integration Pattern
  10. Common Workflows
Sekcje z nagłówków SKILL.md, w oryginale · 248 linii, 1 207 słów
Podgląd SKILL.md
---
name: "codex-auth-helper"
description: "Use for `codex-auth-helper` tasks: reading local Codex auth state, refreshing tokens, building Codex-backed Responses clients/models, and wiring them into `pydantic-ai`, `pydantic-acp`, or LangChain."
---

# codex-auth-helper Skill

Use this skill when the task is centered on the `codex-auth-helper` package.

This package exists so the repo does not re-implement Codex auth and Responses wiring ad hoc in
examples, adapters, or one-off scripts.

It is intentionally narrow:

- read existing Codex auth state
- refresh tokens when needed
- derive account-scoped request headers
- build a Codex-specific async OpenAI client
- build a `pydantic-ai` Responses model on top of that client
- build a LangChain `ChatOpenAI` model on top of the same auth/session flow

## Start Here

If you only need the shortest high-signal path:

1. read `Quick Routing`
2. open the [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py) for public constructor behavior
3. open the [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py) for refresh logic
4. open the [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py) and the [auth-store module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py) for auth payload shape and persistence

## Quick Routing

| If the task is about... | Use this skill? | Open first |
| --- | --- | --- |
| `~/.codex/auth.json` parsing | Yes | [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py), [auth-store module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py) |
| token refresh timing or refresh requests | Yes | [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py), [auth-config module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/config.py) |
| Codex-specific request headers or account id | Yes | [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py), [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py) |
| building a `CodexResponsesModel` | Yes | [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py), [model module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/model.py) |
| building a LangChain `ChatOpenAI` | Yes | [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py), [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py) |
| exposing that model through ACP | Pair with `pydantic-acp` | [Pydantic adapter package](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/pydantic-acp) |
| exposing a Codex-backed LangChain graph through ACP | Pair with `langchain-acp` | [LangChain adapter package](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/langchain-acp) |
| outbound Codex Responses WebSocket | Yes, Pydantic and async LangChain | [model module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/model.py), [LangChain module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/langchain.py), [WebSocket module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/_responses_websocket.py) |
| exposing an ACP runtime over WebSocket | No, pair with `acpremote` | [remote transport package](https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote) |

## Package Boundary

This package is not:

- an ACP adapter
- a CLI package
- an ACP transport package

It is a helper for turning a local Codex login into a reusable `pydantic-ai` Responses model.

That means it owns:

- auth file parsing
- token refresh timing
- account-id extraction
- Codex request header shaping
- Responses-model construction
- optional outbound Responses connection/session ownership

## Do Not Confuse With

- `codex-auth-helper` vs `pydantic-acp`
  this package builds the model/client; `pydantic-acp` exposes the runtime through ACP
- `codex-auth-helper` vs `acpkit-sdk`
  this package has no CLI target-loading role
- `codex-auth-helper` vs `acpremote`
  this package can select the model's outbound Responses connection; it does
  not expose an ACP runtime over a remote transport

It does not own:

- ACP session lifecycle
- approvals
- ACP transport
- CLI dispatch

## Primary References

Package references:

- [Raw skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/codex-auth-helper/SKILL.md)
- [Raw helpers docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/helpers.md)
- [Raw API docs page](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/api/codex_auth_helper.md)
- [Rendered helper docs](https://vcoderun.github.io/acpkit/helpers/)
- [Source tree](https://github.com/vcoderun/acpkit/tree/main/packages/helpers/codex-auth-helper)

Cross-skill reference:

- [Pydantic adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md)

## Public Surface

High-value public seams:

- `create_codex_responses_model(...)`
- `create_codex_async_openai(...)`
- `create_codex_openai(...)`
- `create_codex_chat_openai(...)`
- `CodexAsyncOpenAI`
- `CodexOpenAI`
- `CodexResponsesModel`
- `CodexResponsesConnection`
- `CodexResponsesFallback`
- `CodexResponsesSessionInfo`
- `CodexResponsesConnectionError`
- `CodexResponsesProtocolError`
- `CodexResponsesTransportEvent`
- `CodexResponsesTransportObserver`
- `CodexAuthConfig`
- `CodexAuthState`
- `CodexAuthStore`
- `CodexTokenManager`

Package entrypoint:

- [Package entrypoint](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/__init__.py)

## Module Guide

| Subsystem | Key files | Use them for |
| --- | --- | --- |
| top-level constructors and model surface | [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py), [model module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/model.py), [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py) | building public client/model objects and default request behavior |
| Responses WebSocket | [WebSocket module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/_responses_websocket.py), [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py) | outbound connection lifecycle, event mapping, and continuation safety |
| auth state and persistence | [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py), [auth-store module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py), [auth-config module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/config.py) | parsing auth payloads, persistence, path config |
| token refresh | [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py) | deciding whether refresh is needed and performing refresh |

## What It Does

It:

- reads an existing Codex auth file
- refreshes tokens when needed
- derives `ChatGPT-Account-Id`
- builds a Codex-specific Responses client
- returns a `pydantic-ai` model configured for Codex usage
- returns a LangChain `ChatOpenAI` configured for the Responses API
- optionally keeps one outbound Responses WebSocket for a Pydantic logical run

It does not:

- perform `codex login`
- create a login session from nothing
- support unrelated OpenAI Chat Completions flows
- adapt a runtime to ACP
- expose an ACP runtime over WebSocket

## Common Integration Pattern

The most important package combinations are:

- `codex-auth-helper` + `pydantic-acp`
- `codex-auth-helper` + `langchain-acp`

Normal flow:

1. call `create_codex_responses_model(...)`
2. construct a `pydantic_ai.Agent`
3. expose that agent through `pydantic-acp`

This helper is usually upstream of the adapter, not a replacement for it.

## Common Workflows

### Build a Codex-backed `pydantic-ai` model

Use `create_codex_responses_model(...)` and pass explicit `instructions=...`.
Use `Agent.run_stream(...)` when the caller needs incremental text; `CodexResponsesModel` forwards
Responses API deltas as they arrive instead of buffering the completed response.

### Build a lower-level client first

Use `create_codex_async_openai(...)` when you need the transport/client object explicitly.

### Keep one Responses connection for a Pydantic run

Install the `websocket` extra, pass `connection="websocket"`, and wrap the
whole async agent run in `model.responses_session()`. Keep strict fallback for
measurements. Non-streaming responses recover transient failures with bounded
reconnects; opt-in HTTP fallback follows exhaustion. Exposed streams are not replayed.

### Build a LangChain model

Use `create_codex_chat_openai(...)` when the upstream runtime is LangChain or LangGraph and you
want the Responses API path instead of hand-wiring `langchain-openai`. Pass explicit
`instructions=...` here too. WebSocket factories leave stream selection automatic:
ordinary `ainvoke` buffers the response for recovery and `astream` receives live
chunks. Explicit streaming settings/callbacks can bypass response recovery.
HTTP factories retain their `streaming=True` default.

### Debug refresh behavior

Start from the [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py), then inspect the [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py) and the [auth-config module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/config.py).

## Skill-Bundled Example

Skill-local example:

- [Codex-backed agent example](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/codex-auth-helper/examples/codex_responses_agent.py)
- [Codex-backed LangChain graph example](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/codex-auth-helper/examples/codex_chat_openai_graph.py)
- [Example notes](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/codex-auth-helper/examples/README.md)

This example demonstrates:

- creating the Codex-backed model
- constructing a Pydantic agent
- exposing that agent through `pydantic-acp`
- constructing a LangChain graph with `ChatOpenAI`

## Handoff Rules

Pair or switch to:

- `pydantic-acp`
  when the Codex-backed model is being exposed through ACP
- `langchain-acp`
  when the Codex-backed LangChain graph is being exposed through ACP
- `acpkit-sdk`
  only when that Pydantic agent is invoked through `acpkit run ...` or `acpkit serve ...`

Stay in this skill when the main issue is:

- auth parsing
- refresh behavior
- client header behavior
- model construction

## Guardrails

- Do not call this package an adapter.
- Do not claim it supports generic Chat Completions if it does not.
- Do not describe auth refresh logic that is not present in the package source.
- If the task shifts into ACP adapter runtime behavior, move to `pydantic-acp`.

## Production Baseline

- Require explicit `instructions=` for Codex-backed Pydantic AI and LangChain factories.
- Never log access tokens, refresh tokens, account ids, or the contents of `auth.json`.
- Keep auth-file replacement atomic and private, and serialize sync and async refreshes that share
  one auth store.
- Preserve the enforced Responses settings, including disabled server-side storage and streaming
  behavior.
- Keep `request()` and `request_stream()` distinct: `request()` may collect a required SSE response,
  while `request_stream()` must expose deltas before the terminal response event.
- Keep HTTP as the default; WebSocket continuation must be explicitly selected and scoped to one
  logical run.
- Treat local Codex auth as machine-local user state; do not bake it into images, artifacts, CI
  logs, or shared volumes.
Pliki w paczce (5)
  • SKILL.md 13 KB
  • agents/openai.yaml 1 KB
  • examples/README.md 1 KB
  • examples/codex_chat_openai_graph.py 1 KB
  • examples/codex_responses_agent.py 1 KB

Wersje

W bazie nie ma innych skilli o nazwie codex-auth-helper.

Migawka bazy z 13.11.2026 · wersja paczki 011138595890 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95pydantic-acp
    Udostępnia agenta pydantic_ai przez ACP: konfigurację, uprawnienia, plany, hooki i narzędzia hosta.
  • 100langchain-acp
    Obsługuje langchain-acp: udostępnianie grafów LangChain, LangGraph i DeepAgents przez ACP, budowa grafów i sesji, plany, mosty, projekcje i przykłady.
  • 100migrating-deep-agents-to-pydantic-ai-harness
    Migruje aplikacje Python LangChain Deep Agents do Pydantic AI i Pydantic AI Harness, odtwarzając middleware, backendy, skille, pamięć, subagentów i piaskownicę.
  • 100migrating-langchain-to-pydantic-ai
    Przenosi aplikacje w Pythonie z LangChain, LangGraph i Deep Agents na Pydantic AI, razem z trwałym stanem, przerwaniami, streamingiem, subagentami i zatwierdzaniem akcji.
  • 100acp-service
    Zarządza sesjami ACP i wtyczkami DSH przez @1agents/acp-service: wywołuje role, zleca zadania i zbiera wyniki.
  • 100pydanticai-docs
    Wspiera pracę z frameworkiem Pydantic AI: agenci, ustrukturyzowane wyjście, narzędzia, dostawcy modeli, zależności, streaming i debugowanie uruchomień agenta.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.