Configurați mediul și fișierul AGENTS.md
Pe această pagină
Actualizat la 3 noiembrie 2026 pe baza documentației Codex (Codex CLI, Autentificare, Extensia Codex pentru IDE, Instrucțiuni personalizate cu AGENTS.md): pachetul
@openai/codex-cliși comandacodex auth loginnu există (utilizaținpm install -g @openai/codexșicodex login); identificatorul extensiei esteopenai.chatgpt; adresa codex.openai.com și planurile „Team, Enterprise sau API“ sunt înlocuite cu metodele actuale de acces; iar ordinea de citire a AGENTS.md este clarificată (rădăcina proiectului → directorul curent). Surse: Codex CLI · Autentificare · AGENTS.md · Prețuri.
Pregătiți proiectul pentru Codex
Înainte de prima sarcină, două elemente trebuie să fie în place: accesul dumneavoastră la Codex—contul și conexiunea GitHub—și proiectul propriu-zis, definit prin fișierul AGENTS.md care va ghida agentul. Prima parte durează aproximativ 15 minute și se face o singură dată. A doua parte determină calitatea a tot ceea ce obțineți de la Codex, făcând diferența dintre echipele mulțumite de Codex și cele dezamăgite.
Pasul 1: Accesul dumneavoastră la Codex
Puteți utiliza Codex cu un cont ChatGPT sau o cheie API. Planurile Free și Go oferă acces, în funcție de implementarea curentă, la GPT-6 Luna în aplicația desktop. Începând cu Plus, Codex este disponibil pe web, în CLI, în extensia pentru editor și pe iOS, cu integrări cloud precum revizuirea automată a codului. O cheie API funcționează pentru automatizare în medii partajate precum CI, folosind CLI, SDK sau extensia—deși unele funcționalități pot fi indisponibile. Detaliile și limitele de utilizare se găsesc pe pagina de prețuri Codex.
Pentru a lucra în cloud pe repository-urile dumneavoastră, conectați GitHub atunci când creați primul mediu Codex Cloud (Lecția 2). La acordarea permisiunilor, mențineți-le la minim: limitați accesul doar la repository-urile de care aveți efectiv nevoie.
Pasul 2: Instalarea extensiei pentru editor
În VS Code și derivatele sale (Cursor, Windsurf), instalați extensia Codex din marketplace—identificatorul său este openai.chatgpt:
code --install-extension openai.chatgpt
Apoi deschideți Codex prin iconița sa sau prin paleta de comenzi cu Codex: Open Codex Sidebar și autentificați-vă. Xcode și IDE-urile JetBrains au propriile integrări: în JetBrains, deschideți AI Chat și selectați Codex.
Pasul 3: Instalarea CLI
# Instalare (macOS și Linux), sau npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Verificare instalare
codex --version
# Autentificare (browser), sau verificare stare conexiune
codex login
codex login status
codex login deschide fluxul de autentificare în browser. Pentru o cheie API, transmiteți-o prin intrarea standard (printenv OPENAI_API_KEY | codex login --with-api-key). Codex stochează credențialele fie într-un fișier text simplu, ~/.codex/auth.json, fie în keychain-ul sistemului, în funcție de setarea cli_auth_credentials_store (file, keyring, auto sau ephemeral). Dacă se utilizează fișierul, tratați-l ca pe o parolă: conține token-uri de acces, deci nu îl commit-ați niciodată. CLI și extensia partajează acest cache.
Fișierul AGENTS.md—ghidul proiectului dumneavoastră
AGENTS.md este central pentru utilizarea eficientă a Codex. Este un fișier Markdown simplu, plasat în rădăcina repository-ului, care reunește instrucțiuni, convenții și comenzi specifice proiectului dumneavoastră. Când Codex clonează repo-ul, citește acest fișier primul: gândiți-vă la el ca la o integrare automată pentru agent, exact ceea ce i-ați explica oral unui nou membru al echipei.
Impactul este imediat. Fără AGENTS.md, dacă cereți un test unitar pentru un proiect care folosește Vitest, există o șansă mare ca Codex să vă ofere Jest, deoarece aceasta este cea mai comună alegere în ecosistem. O singură linie de convenție este suficientă pentru a obține Vitest corect din prima, scutindu-vă de a face aceeași corectură de o sută de ori. Iată structura unui fișier de bază pentru un proiect SaaS de gestionare a facturilor.
# AGENTS.md
## Contextul proiectului
Aplicație SaaS de gestionare a facturilor.
Stack: Next.js 15, TypeScript, Prisma, PostgreSQL.
## Convenții de cod
- Utilizați componente funcționale React (fără clase)
- Denumiți fișierele în kebab-case
- Tipuri TypeScript în fișiere separate .types.ts
- Teste cu Vitest, fișiere .test.ts lângă cod
## Comenzi utile
- `npm run dev` — server de dezvoltare
- `npm run test` — rularea testelor
- `npm run lint` — verificare linting
- `npm run build` — build de producție
## Structura proiectului
src/
app/ → Pagini Next.js (App Router)
components/ → Componente React reutilizabile
lib/ → Logică de business și utilitare
prisma/ → Schema DB și migrări
## Reguli stricte
- NU modificați niciodată schema Prisma fără o migrare
- NU commit-ați niciodată fișiere .env
- Utilizați întotdeauna Server Actions pentru mutații
Cum găsește Codex fișierele AGENTS.md
Un singur fișier în rădăcină devine rapid prea generic. Codex vă permite să stivuiți instrucțiuni într-o ordine precisă pe care trebuie să o cunoașteți:
- Nivel global: În folderul dumneavoastră Codex (
~/.codex, dacăCODEX_HOMEnu îl suprascrie), Codex citeșteAGENTS.override.mddacă există, altfelAGENTS.md. - Nivel de proiect: Începând de la rădăcina proiectului (de obicei rădăcina Git), Codex coboară până la directorul curent și citește, în fiecare folder traversat,
AGENTS.override.mdsau, în lipsa acestuia,AGENTS.md. - Fuzionare: Fișierele sunt concatenate de la rădăcină până la directorul curent; cele mai apropiate de directorul curent vin ultimele și, prin urmare, suprascriu instrucțiunile mai generale.
my-project/
AGENTS.md → Instrucțiuni proiect
src/
api/
AGENTS.md → „Rutele API folosesc Zod pentru validare“
Consecință practică: src/api/AGENTS.md este citit doar dacă Codex lucrează din src/api sau unul dintre subdirectoarele sale, nu când este lansat din rădăcină. Fișierele goale sunt ignorate, iar concatenarea se oprește la 32 KiB implicit (project_doc_max_bytes). Dacă repo-ul dumneavoastră folosește deja un alt nume, precum TEAM_GUIDE.md, adăugați-l la project_doc_fallback_filenames în ~/.codex/config.toml.
Pentru a verifica ce a încărcat efectiv Codex, întrebați-l simplu: codex --ask-for-approval never "Summarize the current instructions.". Codex reconstruiește lanțul de instrucțiuni la fiecare lansare: dacă aveți dubii, reporniți-l în directorul corect.
Cele mai bune practici pentru AGENTS.md
Principiul director este explicitarea. „Folosiți Vitest, nu Jest“ este mai bun decât „Folosiți framework-ul nostru de testare“, care presupune cunoștințe pe care agentul nu le are. Includeți întotdeauna comenzile: fără ele, Codex nu va ști cum să ruleze testele, linter-ul sau build-ul și va livra cod pe care nu l-a putut verifica. Documentați structura sub forma unui arbore de directoare, ceea ce îl împiedică să exploreze orbește și să creeze fișiere în locul greșit.
În final, listați interdicțiile. Regulile formulate ca „NICIODATĂ“ sunt cele mai rentabile din fișier, deoarece blochează greșeli costisitoare și greu de reparat: commit-area unui fișier .env, modificarea unei scheme fără o migrare. Cea mai grea disciplină este menținerea fișierului la zi. Un AGENTS.md care descrie proiectul de anul trecut îndreaptă activ Codex către convenții abandonate—mult mai rău decât absența oricărui fișier, deoarece eroarea devine atunci sistematică.
Puncte cheie
- Configurarea inițială necesită un cont OpenAI și o conexiune GitHub
- Extensia IDE și CLI se instalează în câteva minute
- AGENTS.md este cel mai important fișier pentru o utilizare eficientă a Codex
- Acesta conține convenții, comenzi și reguli specifice proiectului dumneavoastră
- Fișierele AGENTS.md din subdirectoare permit instrucțiuni contextuale