Codex Cli

---
name: codex-cli
description: "Запуск внешнего агента OpenAI Codex CLI (`codex exec`) из текущей сессии. Используй, когда пользователь прямо называет исполнителем внешнюю модель — «сделай это через ChatGPT», «пусть напишет GPT», «отправь в чатжпт», «спроси у кодекса», «прогони через codex»; когда просит второе мнение или проверку решения у другой модели — «что скажет другая модель», «second opinion»; когда просит сгенерировать растровое изображение — иконку, картинку, логотип, мокап, фон, текстуру; когда просит отдать codex'у правку, рефакторинг или генерацию кода; когда просит внешнее ревью изменений репозитория, коммита или ветки. Разбирает запуск целиком: поиск бинарника, выбор песочницы, чтение ответа, разбор отказов и то, что уходит наружу. Не для ревью и правок силами самой сессии и не для схем и диаграмм, которые рисуются в SVG или HTML."
---

# Codex CLI

`codex` — агент OpenAI, живущий отдельным процессом: получает промпт, сам ходит по файлам,
сам запускает команды и возвращает финальный текст. Из сессии он вызывается пакетно,
подкомандой `exec`.

**Скилл требует того, чего в проекте может не быть.** Codex CLI ставится отдельно и работает
по платной подписке OpenAI (ChatGPT-аккаунт либо ключ API) — это не часть Claude Code и не часть
поставки 1С. Нет ни того, ни другого — скажи об этом и делай задачу силами самой сессии,
а не подбирай обходной путь.

## Перед запуском

```bash
codex --version
```

Команды нет — остановись и скажи пользователю поставить: `npm i -g @openai/codex`. **Путь
к бинарнику не зашивай и не ищи по диску:** на каждой машине он свой, а npm-глобал кладёт
`codex` в PATH. Нет авторизации — `codex login`; браузерный вход недоступен — `codex login --device-auth` либо `codex login --with-api-key`. Общая диагностика установки, конфига
и аутентификации — `codex doctor`.

## Единый шаблон запуска

```bash
codex exec -s read-only --skip-git-repo-check -C "$PWD" -o "$ОТВЕТ" - <<'EOF'
<промпт>
EOF
```

- Промпт передаётся **только** через heredoc, а на месте аргумента стоит `-`. Дашь промпт
  и аргументом, и на stdin — codex склеит их: аргумент станет промптом, stdin приедет
  отдельным блоком `<stdin>`.
- Heredoc обязательно `<<'EOF'` в одинарных кавычках, иначе bash развернёт `$` внутри промпта.
- `$ОТВЕТ` — файл во временном каталоге сессии, а при его отсутствии в системном temp.
  **В каталог проекта не писать:** файл ответа попадёт в git.
- Timeout в Bash-тулзе — от 180000 (3 мин), тяжёлые задачи — до 600000.
- Русский текст проходит в обе стороны: промпт и файл ответа — UTF-8.
- Промпт пишется по контракту из `references/prompting.md`: одна задача на запуск, форма ответа
  названа, политика по умолчанию задана. «Посмотри и скажи, что думаешь» — не промпт.

## Модель не передаётся

`-m` по умолчанию **не ставится**. Модель берётся из `~/.codex/config.toml` пользователя — там
его текущий выбор, и он новее любого списка, который можно записать в скилл. Список доступных
моделей CLI не отдаёт, поэтому таблицы моделей здесь нет намеренно.

`-m` появляется, только когда пользователь назвал модель сам. Устаревшее или недоступное имя
не деградирует молча, а валит запуск:

```
ERROR: {"type":"error","status":400,…"The 'X' model is not supported when using Codex with a ChatGPT account."}
```

Какая модель отработала — видно в шапке stdout (`model:`) рядом с режимом песочницы и уровнем
рассуждений. Уровень рассуждений тоже берётся из конфига; перебить разово —
`-c model_reasoning_effort="high"` (либо `minimal`, `low`, `xhigh`).

## Что уходит наружу

Всё, что попало в промпт, и всё, что codex прочитал на диске, уходит в OpenAI. Для проекта 1С
это код конфигурации заказчика, а иногда и данные из выгрузок.

- Не отправляй того, чего пользователь не называл сам: пароли, строки подключения, содержимое
  локальных настроек, выгрузки с персональными данными.
- Промпт собирай из минимума — конкретный вопрос и нужные фрагменты, а не «посмотри проект».
- Сомневаешься, можно ли отдавать этот кусок, — спроси до запуска. Отправка необратима.
- Результаты MCP-инструментов уходят туда же: то, что сервер вернул Codex'у, — это данные проекта.
- Всё это остаётся и на диске: `~/.codex/sessions/*.jsonl` хранит промпт, вывод команд и ответы
  MCP открытым текстом. Разовый запуск на коде заказчика — с `--ephemeral`: файл сессии не пишется,
  но и `resume` для неё невозможен.

## Песочница

Дефолт — `-s read-only`: codex читает и рассуждает, но не пишет. Повышение уровня — отдельное
решение, названное вслух и разрешённое пользователем, а не «заодно».

| Режим | Когда | Чем платим |
|---|---|---|
| `-s read-only` | вопрос, разбор, второе мнение | ничего не изменится |
| `-s workspace-write` | правка файлов, **и генерация изображения тоже** | правки прилетают молча |
| `--dangerously-bypass-approvals-and-sandbox` | не применять | снимает песочницу целиком |

Запись вне рабочего каталога решается флагом `--add-dir <КАТАЛОГ>`, а не снятием песочницы.

Перед `-s workspace-write` в каталоге проекта рабочее дерево должно быть чистым или изменения
закоммичены — иначе правки codex'а и свои потом не разделить.

## Сценарии

| Задача | Команда |
|---|---|
| второе мнение, разбор кода или текста | шаблон выше как есть |
| ревью незакоммиченных изменений | `codex exec review --uncommitted` |
| ревью против ветки | `codex exec review --base <ветка>` |
| ревью коммита | `codex exec review --commit <sha>` |
| оспорить изменение: «разнеси», «найди дыры», «что сломается в бою» | `references/adversarial-review.md` — шаблон под 1С и схема JSON |
| правка или рефакторинг кода | шаблон + `-s workspace-write` |
| уточнить, продолжить разговор той же сессией | `codex exec resume --last`, раздел «Продолжение диалога» |
| независимый разбор механизма второй моделью | раздел «Паттерн: независимый разбор» |
| генерация изображения | `references/image-gen.md` — открой перед запуском |

**`review` — не `exec` с другим промптом, а отдельная подкоманда с другим набором флагов:**
`-s` и `-C` она не принимает вовсе. Значит запускать её надо из каталога самого репозитория,
а режим песочницы она возьмёт из конфига пользователя. Свои указания ревьюеру передаются
позиционным промптом или тем же `- ` с heredoc.

Цель ревью: рабочее дерево грязное — `--uncommitted`; чистое — `--base` против ветки по умолчанию
(`git symbolic-ref refs/remotes/origin/HEAD`, иначе `main`/`master`/`trunk`). Ответ `review` — текст:
вводный абзац, затем `Full review comments:` со строками `[P1]`/`[P2]` и адресом `файл:строки`.
`--output-schema` подкоманда `review` игнорирует молча — структурированный результат даёт только
`exec` со схемой, см. `references/adversarial-review.md`. Длинное ревью запускай в фоне
(`run_in_background`) и забирай ответ из `-o`, когда придёт уведомление.

## Продолжение диалога

```bash
codex exec resume --last --skip-git-repo-check -o "$ОТВЕТ" - <<'EOF'
<следующий вопрос>
EOF
```

Сессия продолжается с полным контекстом: Codex помнит и вопрос, и свой ответ. `--last` берёт
последнюю сессию **этого каталога** — сессии фильтруются по cwd; конкретную задаёт её id из шапки
stdout (`session id:`). `--skip-git-repo-check` нужен так же, как при первом запуске: без него
в нетрастовом каталоге `resume` падает. Ни `-s`, ни `-C` у `resume` нет — песочницу и каталог
на ходу не сменить.

## MCP у Codex — свой

Codex **не читает** `.mcp.json` проекта. Его серверы описаны в `~/.codex/config.toml`, список —
`codex mcp list`. Видеть инструмент и мочь его вызвать — разное:

- **В пакетном режиме проходят только инструменты, разрешённые поимённо** в файле конфига
  (`[mcp_servers.<сервер>.tools."<инструмент>"]` с `approval_mode = "approve"`; у серверов
  из плагинов путь начинается с `plugins."<плагин>".`). Остальные отклоняются с текстом
  `MCP tool call requires approval, but approval policy is never`. `-c` из командной строки до
  этих ключей не достаёт. Режим `default_tools_approval_mode = "writes"` различает чтение
  и запись по аннотациям инструментов — у сервера без аннотаций он не работает.
- **MCP-серверы работают вне песочницы.** `-s read-only` не остановит пишущий инструмент, если
  тот разрешён. Разрешать — только читающие.
- **Рабочий каталог сервера — не каталог проекта.** Сервер из плагина стартует в каталоге
  плагина; если инструмент принимает путь к корню проекта параметром, передавать его в каждом
  вызове и писать это в промпт явно.
- Самоотчёт Codex о своих инструментах ненадёжен: на один и тот же вопрос он отвечал по-разному
  в разных запусках. Доказательство доступности — только фактический вызов.

## Паттерн: независимый разбор второй моделью

Цель — проверить **свой** вывод о механизме, а не получить «мнение вообще».

1. Сначала свой разбор; вывод записан до запуска Codex — иначе второй ответ подстроится под первый.
2. Codex получает ту же постановку и те же инструменты (`-s read-only`, те же MCP-серверы), но
   не твой вывод и не наводящие формулировки.
3. Сравнить два вывода. Расхождение — факт для пользователя, а не повод выбрать удобный ответ.

## Чтение ответа

`-o <файл>` кладёт туда финальное сообщение — только его. Читай ответ из файла: в stdout, кроме
него, идут шапка, ход рассуждений и вывод всех запущенных codex'ом команд. Файл пишет сам CLI,
поэтому `-s read-only` его не блокирует.

Нужен машинный разбор — `--json` (JSONL событий) либо `--output-schema <файл.json>`
(JSON Schema, задаёт форму финального ответа). В JSONL: `thread.started` несёт `thread_id` — id сессии
для `resume`; `item.completed` с `item.type` = `agent_message` (текст), `command_execution` (команда
и её вывод), `mcp_tool_call` (сервер, инструмент, результат, статус); `turn.completed` — `usage`
с расходом токенов.

Как подавать ответ Codex пользователю: находки — дословно и в порядке серьёзности, его пометки
«это предположение» сохранять; после ревью ничего не чинить, пока пользователь не назвал, что именно;
Codex упал или не запустился — доложить отказ, а не подменить его ответ своим. Подменённое «второе
мнение» — уже не второе мнение.

## После делегирования правки

`git status` и `git diff` — обязательно. Codex правит файлы напрямую, его изменения ничем
не помечены, и отчёт в ответе не заменяет диф.

## Отказ вместо результата

| Симптом | Причина и что делать |
|---|---|
| `codex: command not found` | не установлен — `npm i -g @openai/codex` |
| 400 «model is not supported» | снять `-m`, отдать выбор модели конфигу пользователя |
| промпт склеился, в логе «Reading additional input from stdin» | промпт задан и аргументом, и на stdin — оставить только heredoc |
| запуск висит на подтверждении | в пакетном режиме подтверждать некому — смотреть `approval_policy` в конфиге |
| правка не записалась | остался `-s read-only` либо цель вне рабочего каталога — `--add-dir` |
| `Not inside a trusted directory and --skip-git-repo-check was not specified` | добавить флаг — и к `exec`, и к `resume` |
| `MCP tool call requires approval, but approval policy is never` | инструмент не разрешён поимённо в `~/.codex/config.toml` |
| «Tool … is not available», хотя в прошлом запуске был | MCP-сервер не поднялся: `codex mcp list`, затем сам сервер и то, через что он стартует |
| bash: `fatal error - add_item … failed` | несколько bash стартуют одновременно — гонка таблицы монтирования MSYS; запускать по одному, снять осиротевшие `codex` |

Отказ не заглаживай пересказом: покажи пользователю строку ошибки из stdout.