Määritä ympäristösi ja AGENTS.md
Tällä sivulla
Päivitetty 3. marraskuuta 2026 Codex-dokumentaation perusteella (Codex CLI, Authentication, Codex IDE extension, Custom instructions with AGENTS.md): pakettia
@openai/codex-clija komentoacodex auth loginei ole olemassa (käytänpm install -g @openai/codexjacodex login); laajennuksen tunniste onopenai.chatgpt; osoite codex.openai.com sekä “Team, Enterprise tai API” -suunnitelmat on korvattu nykyisillä käyttötavoilla; ja AGENTS.md:n lukujärjestys on selkeytetty (projektin juuri → nykyinen hakemisto). Lähteet: Codex CLI · Authentication · AGENTS.md · Pricing.
Valmistele projektisi Codexia varten
Ennen ensimmäistä tehtävääsi kahden asian on oltava kunnossa: Codex-käyttöoikeutesi (tilisi ja GitHub-yhteys) sekä itse projektisi, joka määritellään agenttia ohjaavan AGENTS.md-tiedoston avulla. Ensimmäinen vaihe vie noin 15 minuuttia ja tehdään vain kerran. Toinen vaihe ratkaisee kaiken Codexista saamasi laadun; se erottaa tyytyväiset tiimit niihin, jotka pettyvät työkaluun.
Vaihe 1: Codex-käyttöoikeutesi
Voit käyttää Codexia joko ChatGPT-tilillä tai API-avaimella. Free- ja Go-suunnitelmat tarjoavat pääsyn (nykyisestä käyttöönotosta riippuen) GPT-6 Lunaan työpöytäsovelluksessa. Plus-suunnitelmasta alkaen Codex on käytettävissä verkossa, komentorivillä, editorin laajennuksena ja iOS:ssä, ja siihen sisältyy pilvi-integraatioita kuten automatisoitu koodin tarkastus. API-avain toimii automaatiossa jaetuissa ympäristöissä kuten CI:ssä käyttäen CLI:tä, SDK:ta tai laajennusta, vaikka jotkin ominaisuudet eivät olisi käytettävissä. Yksityiskohdat ja käyttörajat löytyvät Codexin hinnoittelusivulta.
Työskennelläksesi pilvessä varastojesi (repositories) parissa, yhdistä GitHub luodessasi ensimmäisen Codex Cloud -ympäristösi (oppitunti 2). Myöntäessäsi oikeuksia pidä ne minimaalisina: rajoita pääsy vain niihin varastoihin, joita todella tarvitset.
Vaihe 2: Asenna editorin laajennus
Asenna Codex-laajennus markkinapaikalta VS Codeen ja sen johdannaisiin (Cursor, Windsurf). Sen tunniste on openai.chatgpt:
code --install-extension openai.chatgpt
Avaa sen jälkeen Codex sen kuvakkeesta tai komentovalikosta valinnalla Codex: Open Codex Sidebar ja kirjaudu sisään. Xcodella ja JetBrains IDE:illä on omat integraationsa: avaa JetBrainsissä AI Chat ja valitse Codex.
Vaihe 3: Asenna CLI
# Asennus (macOS ja Linux), tai npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Varmista asennus
codex --version
# Kirjaudu sisään (selaimessa), tai tarkista yhteystila
codex login
codex login status
codex login avaa kirjautumisprosessin selaimessasi. Jos käytät API-avainta, syötä se vakiosyötteen kautta (printenv OPENAI_API_KEY | codex login --with-api-key). Codex välimuistaa tunnistetiedot joko pelkkänä tekstinä tiedostoon ~/.codex/auth.json tai järjestelmän avainnippuun riippuen asetuksen cli_auth_credentials_store arvosta (file, keyring, auto tai ephemeral). Jos tiedostoa käytetään, kohtele sitä kuin salasanaa: se sisältää pääsytunnuksia, äläkä koskaan commitoi sitä. CLI ja laajennus käyttävät samaa välimuistia.
AGENTS.md-tiedosto – projektisi opas
AGENTS.md on keskeinen tehokkaalle Codexin käytölle. Se on yksinkertainen Markdown-tiedosto, joka sijoitetaan varaston juureen ja joka kokoaa projektillesi erityiset ohjeet, käytännöt ja komennot. Kun Codex kloonaa varaston, se lukee tämän tiedoston ensimmäisenä: ajattele sitä agentin automaattisena perehdytyksenä, aivan kuten selittäisit suullisesti uudelle tiimin jäsenelle.
Vaikutus on välitön. Ilman AGENTS.md-tiedostoa, jos pyydät yksikkötestiä Vitestiä käyttävään projektiin, on suuri todennäköisyys, että Codex tuottaa Jestin, koska se on ekosysteemin yleisin valinta. Yksi rivi käytäntöä riittää varmistamaan, että Vitest toimii oikein heti alusta, säästäen sinut toistamasta samaa korjausta sata kertaa. Tässä on perusrakenne tiedostolle SaaS-laskutushallintaprojektia varten.
# AGENTS.md
## Project context
SaaS invoice management application.
Stack: Next.js 15, TypeScript, Prisma, PostgreSQL.
## Code conventions
- Use React functional components (no classes)
- Name files in kebab-case
- TypeScript types in separate .types.ts files
- Tests with Vitest, .test.ts files next to code
## Useful commands
- `npm run dev` — development server
- `npm run test` — run tests
- `npm run lint` — check linting
- `npm run build` — production build
## Project structure
src/
app/ → Next.js pages (App Router)
components/ → Reusable React components
lib/ → Business logic and utilities
prisma/ → DB schema and migrations
## Strict rules
- NEVER modify Prisma schema without a migration
- NEVER commit .env files
- Always use Server Actions for mutations
Miten Codex löytää AGENTS.md-tiedostot
Yksi juuritiedosto muuttuu nopeasti liian yleiseksi. Codex antaa sinun pinota ohjeita tarkassa järjestyksessä, joka sinun on tunnettava:
- Globaali taso: Codex-kansiossasi (
~/.codex, elleiCODEX_HOMEylikirjoita sitä), Codex lukeeAGENTS.override.md:n jos se on olemassa, muutenAGENTS.md:n. - Projektitaso: Alkaen projektin juuresta (yleensä Git-juuri), Codex laskeutuu nykyiseen hakemistoon ja lukee jokaisessa läpikäydyssä kansiossa
AGENTS.override.md:n tai, jos sitä ei ole,AGENTS.md:n. - Yhdistäminen: Tiedostot ketjutetaan juuresta alaspäin nykyiseen hakemistoon; nykyistä hakemistoa lähimpänä olevat tulevat viimeisinä ja siksi ylikirjoittavat yleisemmät ohjeet.
my-project/
AGENTS.md → Projektin ohjeet
src/
api/
AGENTS.md → "API-reitit käyttävät Zodia validointiin"
Käytännön seuraus: src/api/AGENTS.md luetaan vain, jos Codex työskentelee hakemistosta src/api tai sen alihakemistosta, ei kun se käynnistetään juuresta. Tyhjät tiedostot jätetään huomiotta, ja ketjutus pysähtyy oletusarvoisesti 32 KiB:n kohdalla (project_doc_max_bytes). Jos varastosi käyttää jo toista nimeä, kuten TEAM_GUIDE.md, lisää se kohtaan project_doc_fallback_filenames tiedostossa ~/.codex/config.toml.
Varmistaaksesi, mitä Codex on todella ladannut, kysy vain: codex --ask-for-approval never "Summarize the current instructions.". Codex rakentaa ohjeketjun uudelleen jokaisessa käynnistyksessä: jos epäilet, käynnistä se uudelleen oikeassa hakemistossa.
Parhaat käytännöt AGENTS.md:lle
Ohjaava periaate on eksplisiittisyys. “Käytä Vitestiä, älä Jestiä” on parempi kuin “Käytä testikehystämme”, mikä olettaa tietoa, jota agentilla ei ole. Sisällytä aina komennot: ilman niitä Codex ei tiedä, miten ajaa testejäsi, linteriäsi tai buildia, ja se toimittaa koodia, jota se ei ole voinut varmistaa. Dokumentoi rakenne hakemistopuuna, mikä estää sitä seikkailemasta sokkona ja luomasta tiedostoja väärään paikkaan.
Listaa lopuksi kiellot. Säännöt, jotka on kirjoitettu muodossa “NEVER” (EI KOSKAAN), ovat tiedostossa kustannustehokkaimpia, koska ne estävät kalliita virheitä, joita on vaikea korjata: .env-tiedoston commitoiminen tai skeeman muuttaminen ilman migraatiota. Vaikein kurinpitovaatimus on pitää tiedosto ajan tasalla. AGENTS.md, joka kuvailee viime vuoden projektia, ohjaa Codexia aktiivisesti hylättyihin käytäntöihin – mikä on paljon pahempaa kuin tiedoston puuttuminen kokonaan, sillä silloin virheestä tulee systemaattinen.
Keskeiset asiat
- Alkuasetus vaatii OpenAI-tilin ja GitHub-yhteyden
- IDE-laajennus ja CLI asennetaan muutamassa minuutissa
- AGENTS.md on tärkein tiedosto tehokkaalle Codexin käytölle
- Se sisältää projektillesi erityiset käytännöt, komennot ja säännöt
- Alihakemistojen AGENTS.md-tiedostot mahdollistavat kontekstuaaliset ohjeet