Współpraca zespołowa i wspólna konfiguracja w Codeksie

Poziom 3 Poradnik Zaktualizowano 2026-10-12

Wspólna konfiguracja Codeksa w zespole to cztery artefakty w repozytorium: AGENTS.md z konwencjami, .codex/config.toml z ustawieniami domyślnymi (sandbox, polityka zatwierdzeń, serwery MCP), .codex/rules/*.rules z poleceniami dozwolonymi poza sandboksem oraz .agents/skills/ z powtarzalnymi procedurami. Codex ładuje warstwę projektu tylko w zaufanym katalogu, a zadanie w CI dowodzi, że pliki nadal działają.

Ta strona jest dla tech leada, który ma sprawić, że Codex zachowuje się tak samo u ośmiu osób, i dla programisty, któremu przypadło to skonfigurować. Objaw znasz: jedna osoba pracuje z --dangerously-bypass-approvals-and-sandbox, druga ręcznie zatwierdza każde ls, trzecia ma pięć serwerów MCP, których nikt inny nie używa. Wspólny prompt daje wtedy trzy różne wyniki i nikt nie wie, czy zawinił prompt, czy konfiguracja. Polecenia i klucze poniżej sprawdziliśmy na Codex CLI 0.157.1 w dniu 2026-09-26.

Co daje wspólna konfiguracja Codeksa w zespole

Warstwę projektu w repozytorium, która nadpisuje osobiste ustawienia domyślne, i jasną granicę między tym, co zespół współdzieli, a tym, co zostaje prywatne
Reguły poleceń z własnymi testami (przykłady match i not_match) i sposób, by je sprawdzić bez uruchamiania sesji
Skille, które zamieniają sprawdzony prompt w $pr-ready dostępne dla całego zespołu
Onboarding w jednej sesji, który kończy się dowodem, a nie wrażeniem, że „chyba działa”
Zadanie w CI, które pada, gdy wspólna konfiguracja się rozjedzie, więc nikt nie musi zaglądać do laptopów

Ograniczenia dla całej organizacji, których nikt nie może nadpisać, należą do requirements.toml i opisuje je strona zarządzanie Codeksem w firmie. Kolejność całego wdrożenia znajdziesz w hubie Codex dla zespołów.

Które pliki Codeksa zespół commituje, a które zostają prywatne?

Artefakt	Ścieżka	W repo?	Zawiera
Konwencje	`AGENTS.md` (w korzeniu i w pakietach)	Tak	Polecenia build i test, zasady kodu, zasady review
Konfiguracja projektu	`.codex/config.toml`	Tak	`approval_policy`, `sandbox_mode` (albo `default_permissions` w wersji beta, nigdy oba), `web_search`, `[mcp_servers.*]`
Reguły poleceń	`.codex/rules/*.rules`	Tak	Decyzje `prefix_rule()`: `allow`, `prompt`, `forbidden`
Skille	`.agents/skills/<nazwa>/SKILL.md`	Tak	Procedury wywoływane jako `$<nazwa>`
Własność	Wpisy w `CODEOWNERS` dla czterech ścieżek powyżej	Tak	Kto zatwierdza zmianę konfiguracji agenta w zespole
Konfiguracja osobista	`$CODEX_HOME/config.toml` (domyślnie `~/.codex/`)	Nie	Osobiste preferencje, pomocniki do poświadczeń, `notify`
Profile	`$CODEX_HOME/<nazwa>.config.toml`, wybierane przez `--profile <nazwa>`	Nie	Warianty na żądanie, np. tańszy model do szybkiej pracy
Wymuszone limity	`/etc/codex/requirements.toml`, MDM lub zarządzany pakiet w chmurze	Należy do administratora	Ograniczenia, których żadna niższa warstwa nie poluzuje

Ten podział to nie tylko konwencja. W 0.157.1 Codex odrzuca część kluczy z warstwy projektu, bo zawartość repozytorium nie powinna decydować, dokąd trafiają poświadczenia ani jakie lokalne polecenia się uruchomią: między innymi model_provider, model_providers, notify, profile, profiles, otel, openai_base_url i chatgpt_base_url (kod źródłowy Codeksa, PROJECT_LOCAL_CONFIG_DENYLIST). Profilu nie da się więc dostarczyć w repozytorium; każdy programista tworzy go w $CODEX_HOME.

Zbuduj wspólną warstwę projektu

Napisz konfigurację projektu. Niech będzie krótka. Każdy klucz ustawiony tutaj nadpisuje osobisty wybór każdego programisty.
```
# .codex/config.toml -- wspólne ustawienia zespołu
approval_policy = "on-request"
sandbox_mode = "workspace-write"

# "disabled" pasuje do repozytoriów z wrażliwym kodem
web_search = "disabled"

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
```
sandbox_mode należy do starszego systemu sandboksa. OpenAI zaleca profile uprawnień (beta, CLI 0.138.0 lub nowsze), wybierane kluczem default_permissions = ":workspace"; w jednej warstwie wybierz jeden system, bo według OpenAI te dwa „nie składają się” ze sobą. Ta strona zostaje przy sandbox_mode, bo profile są wciąż w becie, a wymuszanie jednego lub drugiego z requirements.toml opisuje strona zarządzanie Codeksem w firmie.

Nie ustawiaj model. Zespół pracuje wtedy na domyślnym modelu Codeksa, na 2026-10-12 jest to GPT-6.1 Sol (domyślny w pakiecie od CLI 0.159.1), i przechodzi na nowy razem ze zmianą domyślnego modelu po stronie OpenAI, zamiast utknąć na starszym. Aktualne modele i ceny są w hubie modeli.
Dodaj reguły poleceń z testami. Reguły to pliki w Starlarku. Lista wewnątrz pattern oznacza „dowolne z tych na tej pozycji”, a przykłady match i not_match są sprawdzane przy wczytaniu pliku, więc reguła, która nie robi tego, co zakładał autor, od razu zgłasza błąd.
.codex/rules/team.rules
```
prefix_rule(
    pattern = [["npm", "pnpm"]],
    decision = "allow",
    match = ["pnpm test", "npm run lint"],
)

prefix_rule(
    pattern = ["git", ["push", "reset"]],
    decision = "prompt",
    justification = "Pushes and resets change shared history. Confirm first.",
    match = ["git push origin main", "git reset --hard HEAD~1"],
    not_match = ["git status", "git diff"],
)

prefix_rule(
    pattern = ["rm", "-rf"],
    decision = "forbidden",
    justification = "Use git clean -n to preview deletions instead.",
    match = ["rm -rf dist"],
)
```
Gdy do jednego polecenia pasuje kilka reguł, wygrywa najbardziej restrykcyjna decyzja. Polecenie sprawdzisz względem pliku bez uruchamiania sesji:
Okno terminala
```
codex execpolicy check --rules .codex/rules/team.rules git push origin main
# {"matchedRules":[...],"decision":"prompt"}
```
W 0.157.1 i 0.162.1 codex execpolicy nie pojawia się w codex --help (sprawdzone 2026-10-12), ale działa, a w 0.157.1 kończy się kodem różnym od zera, gdy przykład match nie pasuje. Strona OpenAI o regułach nadal mówi „Rules are experimental and may change” (sprawdzone 2026-10-12), więc zostaw tę kontrolę w CI i uruchamiaj ją ponownie po każdej aktualizacji Codeksa. Po edycji pliku z regułami zrestartuj Codeksa.
Podziel AGENTS.md według zakresu. Plik w korzeniu zawiera to, co obowiązuje wszędzie; plik pakietu tylko to, co się tam różni. Codex skleja łańcuch od korzenia repozytorium do katalogu roboczego i domyślnie ucina go na 32 KiB (project_doc_max_bytes), więc wszystko, co powtarzasz z korzenia, zużywa budżet dwa razy.
AGENTS.md
```
## Commands
- Install: pnpm install --frozen-lockfile
- Verify: pnpm lint && pnpm typecheck && pnpm test
## Rules
- New endpoints need an integration test in tests/integration/
- Schema changes need a migration in migrations/; never edit an applied one
## Done means
- The Verify command passes and the PR description lists what was not tested
```
Jak przycinać i mierzyć ten łańcuch, opisuje strona optymalizacja AGENTS.md i skilli w Codeksie.
Zamień sprawdzone prompty w skille. Skill to katalog z plikiem SKILL.md. Codex przeszukuje .agents/skills/ w każdym katalogu od roboczego w górę do korzenia repozytorium, a do tego ~/.agents/skills/ dla skilli osobistych oraz skille rozsyłane przez administratora (zob. zarządzanie Codeksem w firmie). W przeciwieństwie do konfiguracji projektu skille wczytują się także w niezaufanej kopii.
```
---
name: pr-ready
description: Prepare the current branch for a pull request. Use when the user
  asks to finish, wrap up, or open a PR.
---

1. Run the Verify command from AGENTS.md. Fix failures in source, never by
   editing or skipping tests.
2. Run `git diff --stat origin/main...HEAD` and list every file you changed.
3. Write the PR description: what changed, why, how it was tested, and
   what was NOT tested.
4. Stop and report if Verify still fails after two attempts.
```
Plik leży w .agents/skills/pr-ready/SKILL.md, a name musi się zgadzać z nazwą katalogu. Każdy, kto sklonuje repozytorium, uruchamia go jako $pr-ready; /skills pokazuje, co się wczytało. Gdy skill ma trafić także do innych repozytoriów, spakuj go jako plugin w prywatnym marketplace zespołu.
Chroń konfigurację przez CODEOWNERS. Zmiana w .codex/, .agents/skills/ albo w którymkolwiek AGENTS.md zmienia zachowanie agenta u każdego w zespole, więc wymaga tego samego wskazanego recenzenta co zmiana w CI.
```
# .github/CODEOWNERS
/.github/         @acme/dev-platform
/.codex/          @acme/dev-platform
/.agents/skills/  @acme/dev-platform
AGENTS.md         @acme/dev-platform
```

Która warstwa konfiguracji Codeksa wygrywa?

Od najniższego do najwyższego pierwszeństwa w 0.157.1: wbudowane ustawienia domyślne, /etc/codex/config.toml, zarządzany pakiet w chmurze, $CODEX_HOME/config.toml, wybrany plik profilu, potem warstwy projektu (.codex/config.toml w katalogu roboczym, katalogach nadrzędnych i korzeniu repozytorium), a na końcu nadpisania w czasie uruchomienia, takie jak -c klucz=wartość, --sandbox czy wybór modelu w interfejsie. requirements.toml stoi poza tym stosem: ogranicza to, co wolno wybrać każdej warstwie.

Dla zespołu liczą się dwie konsekwencje. Plik projektu w repo wygrywa z osobistym profilem, więc --profile nie poluzuje po cichu sandboksa zespołu. A warstwy projektu ładują się tylko w zaufanym katalogu: w niezaufanej kopii Codex pomija .codex/config.toml, wyłącza reguły (.codex/rules/) i hooki projektu, a od 0.150.0 ignoruje też AGENTS.md projektu. Skille z .agents/skills/ nadal się wczytują.

Prompty do skopiowania dla konfiguracji zespołowej Codeksa

Draft this repository's shared Codex setup. Do not change any existing file; write new
files only under .codex/ and .agents/skills/ and show me a diff at the end.
1. .codex/config.toml with approval_policy = "on-request", sandbox_mode =
   "workspace-write" (and no default_permissions: the two do not compose),
   web_search = "disabled", and one [mcp_servers.<name>] entry for
   each MCP server the README or CONTRIBUTING.md says the team uses. Do not set model,
   profile, notify or model_provider.
2. .codex/rules/team.rules: allow the package manager and build tool this repository
   actually uses (read package.json, Makefile or pyproject.toml), prompt for
   git push and git reset, forbid rm -rf. Every prefix_rule must carry match examples,
   and every prompt or forbidden rule a not_match example and a justification.
3. Run `codex execpolicy check --rules .codex/rules/team.rules` against three
   commands from step 2 and paste the JSON decisions.
4. List anything in the current AGENTS.md that belongs in a skill instead, because it
   is a multi-step procedure rather than a rule.

Turn the prompt in .github/codex/prompts/fix-ci.md into a Codex skill at
.agents/skills/fix-ci/SKILL.md.
- Frontmatter: name must be fix-ci; the description says when to use the skill in one
  or two sentences, including the words a teammate would type ("CI is red", "the build
  failed").
- Body: numbered steps. Start by reproducing the failure locally with the Verify command
  from AGENTS.md. Fix the root cause in source; never skip, delete or loosen a test.
  Stop and report after two failed attempts.
- End with a report format: failing check, root cause, files changed, commands run
  with their exit codes.
Then list the skills Codex can see and confirm fix-ci is among them.

Check my Codex setup against this repository's shared configuration. Do not edit files.
1. Summarise the AGENTS.md instructions you loaded and name every file they came from.
2. List the skills you can see, and mark which come from .agents/skills/ in this repo.
3. List the MCP servers you can reach and whether each one is authenticated.
4. State the sandbox mode, approval policy and model this session runs with.
5. Run the Verify command from AGENTS.md and report its exit code.
End with a table: expected (from the committed files) vs actual, and a one-line fix
for every mismatch.

Wdróż nową osobę do konfiguracji Codeksa w jednej sesji

Zainstaluj CLI poleceniem npm install -g @openai/codex (albo brew install --cask codex); pozostałe interfejsy opisuje strona instalacja Codeksa.
Uruchom codex login, wybierz workspace ChatGPT zespołu i potwierdź poleceniem codex login status.
Sklonuj repozytorium i uruchom w nim codex. Zaakceptuj pytanie o zaufanie: jeśli je odrzucisz, zacommitowane .codex/config.toml, .codex/rules/ i hooki projektu pozostają wyłączone, a AGENTS.md się nie wczyta. Skille wczytują się w obu przypadkach, więc widoczny $pr-ready nie dowodzi zaufania.
Zaloguj się do wspólnych serwerów MCP, które wymagają OAuth, np. codex mcp login linear.
Uruchom codex doctor, który sprawdzi instalację, logowanie i łączność. W TUI wpisz /debug-config, żeby zobaczyć każdą warstwę konfiguracji i źródło każdego wymagania, a potem /status.
Sprawdź, co model faktycznie dostaje, bez wywoływania go. codex debug prompt-input | grep -c "pr-ready" zwraca liczbę większą od zera, gdy skill zespołu się wczytał, niezależnie od zaufania; codex debug prompt-input | grep -c "Verify: pnpm lint" zwraca 0, gdy projekt jest oznaczony jako niezaufany (odrzuciłeś pytanie o zaufanie), bo ta linia pochodzi z AGENTS.md; po zaakceptowaniu pytania zwraca liczbę większą od zera.
Wklej prompt „kontrola konfiguracji nowej osoby w zespole” z sekcji wyżej, a potem uruchom $onboard, jeśli zespół ma skill wprowadzający.

Kryterium wyjścia to tabela z kroku 7 bez rozbieżności. Taki dowód tech lead przyjmie w komentarzu do pull requesta; samo „zainstalowałem” dowodem nie jest.

Jak udowodnić, że wspólna konfiguracja Codeksa działa, bez podglądania każdej sesji?

Traktuj wspólną warstwę jak kod: zadanie w CI sprawdza ją przy każdym pull requeście, a wynik pracy agenta przechodzi przez te same bramki co praca człowieka.

name: codex-config
on:
  pull_request:
    paths: ['.codex/**', '.agents/skills/**', '**/AGENTS.md']
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: '22'
      - run: npm install -g @openai/codex@0.157.1
      - name: Rules load and still decide what we expect
        run: |
          args=()
          for f in .codex/rules/*.rules; do args+=(--rules "$f"); done
          codex execpolicy check "${args[@]}" rm -rf / | grep -q '"decision":"forbidden"'
          codex execpolicy check "${args[@]}" git push origin main | grep -q '"decision":"prompt"'
      - name: AGENTS.md chain fits the 32 KiB default
        run: |
          bytes=$(find . -name AGENTS.md -not -path '*/node_modules/*' -exec cat {} + | wc -c)
          echo "AGENTS.md total: $bytes bytes"
          test "$bytes" -le 32768
      - name: Every skill's name matches its directory
        run: |
          for dir in .agents/skills/*/; do
            name=$(basename "$dir")
            grep -qx "name: $name" "${dir}SKILL.md" || { echo "${dir}: name must be $name"; exit 1; }
            grep -q '^description: ' "${dir}SKILL.md" || { echo "${dir}: missing description"; exit 1; }
          done

Zadanie nie potrzebuje żadnego sekretu i nie uruchamia modelu: parsuje reguły (co wykonuje ich przykłady match), sprawdza dwie decyzje, które nigdy nie powinny się zmienić, oraz budżet kontekstu i metadane skilli. Kontrola rozmiaru sumuje wszystkie pliki AGENTS.md w repozytorium, co jest surowsze niż łańcuch, który Codex wczytuje dla jednego katalogu. Dwa sprawdzane polecenia dopasuj do własnych reguł.

Przy wyzwalaczu pull_request GitHub uruchamia ten workflow z gałęzi scalenia samego pull requesta, więc PR, który zmienia .codex/, może też zmienić sprawdzające go zadanie. Kontrola naprawdę wiąże dopiero wtedy, gdy /.github/ również podlega CODEOWNERS (jak w kroku 5), a ochrona gałęzi lub ruleset wymaga tej recenzji.

Kontrola	Dowód	Kto zatwierdza
Wspólna warstwa jest poprawna	Zielone zadanie `codex-config` na pull requeście	`CODEOWNERS` dla `.codex/`
Wszyscy mają tę samą konfigurację	`/status` u dwóch osób w tym samym repozytorium pokazuje ten sam sandbox, politykę zatwierdzeń i model	Tech lead
Nowe osoby są skonfigurowane	Tabela z onboardingu bez rozbieżności, wklejona w zgłoszeniu onboardingowym	Tech lead
Praca agenta spełnia poprzeczkę	Te same CI, testy i wymagane review co przy pull requestach ludzi, plus `codex review --base main` przed otwarciem PR	Właściciel repozytorium

Jak skalować review, żeby nie stało się wąskim gardłem, opisują strony review pracy Codeksa oraz, od strony procesu zespołu, kolejka review.

Przewidywalne zużycie w zespole dzięki wspólnym ustawieniom

Model domyślny zostaw Codeksowi, tańsze modele trzymaj w osobistych profilach. Kto chce lżejszego modelu do eksploracji, tworzy $CODEX_HOME/quick.config.toml z model = "gpt-6-luna" (albo gpt-6-sol) i uruchamia codex --profile quick. Warstwa projektu nadal wygrywa w kwestii sandboksa i zatwierdzeń.
Najpierw poziom rozumowania, potem model. Codex domyślnie uruchamia GPT-6.1 Sol z poziomem rozumowania low. Gdy wyniki nie wystarczają, podnieś poziom na jedną sesję w /model albo ustaw model_reasoning_effort = "medium" w pliku osobistego profilu, zanim sięgniesz po inny model.
Płać za kontekst raz, a nie w każdej sesji. Każdy bajt AGENTS.md kosztuje kontekst w każdej sesji, a każdy serwer MCP dokłada metadane narzędzi (tool search odracza wczytanie pełnych definicji). Usuń serwery, których zespół nie używa, a do wpisu serwera dodaj enabled_tools = [...], gdy liczy się tylko kilka jego narzędzi.
Sprawdzaj rzeczywiste zużycie, nie szacunki. /usage pokazuje zużycie konta i resety limitów, a /status bieżącą sesję. Kredyty, plany i panele opisuje strona koszty Codeksa.

Gdy wspólna konfiguracja Codeksa się psuje: jak z tego wyjść

Jedna osoba dostaje inne wyniki niż reszta. Najpierw sprawdź zaufanie: niezaufana kopia gubi .codex/config.toml, reguły i hooki projektu oraz AGENTS.md projektu, a skille wczytują się dalej, więc konfiguracja wygląda na kompletną. Potem szukaj nadpisań -c w aliasie powłoki, wybranego --profile i użyj /debug-config, by znaleźć warstwę, która ustawiła dziwną wartość.
Klucz w .codex/config.toml nic nie zmienia. Może należeć do kluczy, których Codex nie przyjmuje z warstwy projektu, takich jak profile, model_provider czy notify. Przenieś go do konfiguracji osobistej albo, jeśli ma obowiązywać wszystkich, do requirements.toml.
Plik reguł blokuje polecenie, które wcześniej przechodziło. Pasowało kilka reguł i wygrała najbardziej restrykcyjna. Uruchom codex execpolicy check ze wszystkimi plikami reguł tej osoby, także z ~/.codex/rules/, i znajdź regułę, która zdecydowała.
Instrukcje z końca AGENTS.md są ignorowane. Łańcuch przekroczył 32 KiB i został ucięty. Przenieś procedury do skilli, usuń to, co mówi już plik w korzeniu, i dopiero wtedy rozważ podniesienie project_doc_max_bytes.
Nowy skill się nie pojawia. Sprawdź, czy katalog leży w .agents/skills/ między katalogiem roboczym a korzeniem repozytorium, czy name zgadza się z nazwą katalogu i czy zmiana jest wypchnięta; potem zrestartuj Codeksa i zajrzyj do /skills.
Ktoś z zespołu nie może połączyć się ze wspólnym serwerem MCP. Wpis jest wspólny, ale logowanie osobiste: uruchom codex mcp login <nazwa>, a tokeny trzymaj w zmiennych środowiskowych (bearer_token_env_var), nigdy w zacommitowanym pliku.
Ktoś chce poluzować sandbox „tylko w tym repo”. Warstwa projektu na to pozwala i właśnie dlatego pilnuje jej CODEOWNERS. Jeśli ma się to nigdy nie zdarzyć, wymuś to przez allowed_sandbox_modes w requirements.toml.

Co dalej z pracą zespołową w Codeksie

Wdróż konfigurację we właściwej kolejności: Codex dla zespołów i firm.
Ustaw limity, których nikt nie nadpisze, z dowodami do audytu: zarządzanie Codeksem w firmie.
Poznaj każdy tryb zatwierdzeń i sandboksa, zanim wybierzesz: uprawnienia, sandboksy i tryby zatwierdzeń.
Wprowadź Codeksa do samego pipeline’u: Codex w CI/CD.
Porównaj wspólne konfiguracje innych narzędzi: współpraca zespołowa w Claude Code i współpraca zespołowa w Cursorze.