---
title: Часто задаваемые вопросы
sidebar:
  order: 14
---

Распространённые ошибки, неожиданное поведение и вопросы в духе «так и должно
работать?». Если вашей проблемы здесь нет, создайте
[задачу на GitHub](https://github.com/alibaba/open-code-review/issues), указав
выполненные шаги и полный вывод.

## Конфигурация и запуск

### `no valid LLM endpoint configured`

```
no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL,
~/.opencodereview/config.json, or ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/
ANTHROPIC_MODEL must be set
```

OCR прошёл всю цепочку разрешения эндпоинта ([Конфигурация](../configuration/#reuse-existing-environment-variables)),
но не нашёл полного набора `(URL, token, model)`. Выполните одно из следующих
действий:

- Запустите `ocr config set llm.url …` / `llm.auth_token …` / `llm.model …`,
  чтобы заполнить `~/.opencodereview/config.json`, **или**
- Экспортируйте `OCR_LLM_URL` / `OCR_LLM_TOKEN` / `OCR_LLM_MODEL`, **или**
- Экспортируйте `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` /
  `ANTHROPIC_MODEL`, если уже используете Claude Code.

Затем выполните `ocr llm test`, чтобы проверить подключение перед повторным
запуском ревью.

### `ocr llm test` показывает неверный источник

OCR использует **первый** полный набор, а не последний. Поэтому, если файл
конфигурации содержит все три ключа llm.*, переменные окружения игнорируются.
Чтобы приоритет получили переменные окружения, удалите ключи конфигурации
(`rm` для файла или удаление вручную) либо переключитесь на новые значения с
помощью `ocr config set`.

### Ошибка 401 / 403 от `ocr llm test`

У токена отсутствует нужная область доступа, истёк срок действия или выбран
неверный поставщик. Anthropic и OpenAI используют разные заголовки
аутентификации и форматы URL — убедитесь, что значение `llm.use_anthropic`
соответствует указанному URL:

- Anthropic: URL заканчивается на `/v1/messages`, `use_anthropic=true`.
- OpenAI / OpenAI-совместимые API: URL заканчивается на
  `/v1/chat/completions`, `use_anthropic=false`.

### `not a git repository`

`ocr review` выполняет `git diff` (а для неотслеживаемых файлов —
`git ls-files`) в текущем каталоге. Если вы находитесь не внутри рабочего
дерева Git, программа сразу завершается. Перейдите в репозиторий с помощью
`cd` или передайте `--repo /path/to/repo`.

### "No tool calls parsed" (локальные модели / Ollama)

```
[ocr] No tool calls parsed for src/foo.go, retrying...
[ocr] Max tool requests reached for src/foo.go.
```

Если каждое ревью циклически повторяет попытки после `No tool calls parsed`,
завершается сообщением "Max tool requests reached" и не создаёт комментариев,
проблема в модели, а не в конфигурации. OCR полностью управляет ревью через
вызовы инструментов, поэтому **модель должна поддерживать нативный вызов
инструментов (function calling)**. Модель, которая лишь *описывает* вызовы
инструментов в текстовом выводе (или внутри блоков `<think>`), не сможет
работать с OCR независимо от настройки промпта; распространённый пример —
`deepseek-r1`. Модели с нативной поддержкой инструментов, например `qwen3`,
работают нормально. Для Ollama выбирайте модели с меткой поддержки
инструментов: <https://ollama.com/search?c=tools>.

Проверьте локальную модель напрямую, без участия OCR:

```bash
curl http://127.0.0.1:11434/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "qwen3:32b",
  "messages": [{"role": "user", "content": "The code below has a bug, use the report_bug tool to report it.\n\nfunc add(a, b int) int {\n  return a - b\n}"}],
  "tools": [{"type": "function", "function": {"name": "report_bug", "description": "Report a bug in the code",
    "parameters": {"type": "object", "properties": {"line": {"type": "integer"}, "description": {"type": "string"}}, "required": ["description"]}}}]
}'
```

Успех: ответ содержит структурированный массив `tool_calls` с именем
`report_bug`. Ошибка: «вызов» отображается как текст внутри `content`.

Если модель *поддерживает* инструменты, но отвечает медленно на локальном
оборудовании, увеличьте тайм-аут LLM — см. раздел
[Тайм-ауты](../configuration/#timeouts).

## Фильтрация и правила

### Мой файл не проверяется

Запустите `ocr review --preview` (без затрат на LLM). В выводе перечислены все
файлы-кандидаты с **причиной**, по которой каждый из них был оставлен или
исключён:

```
src/foo.go              modified
src/foo_test.go         modified  (excluded: user_exclude)
node_modules/lib.js     added     (excluded: default_path)
imgs/logo.png           binary    (excluded: unsupported_ext)
```

Пять причин исключения соответствуют этапам
[фильтрации файлов](../review-rules/#how-files-are-filtered):

| Причина | Исправление |
|---|---|
| `binary` | Ничего делать не нужно: бинарные файлы не содержат текста, пригодного для ревью. |
| `user_exclude` | Удалите шаблон из списка `exclude`. |
| `unsupported_ext` | Добавьте расширение в список `include`, чтобы обойти проверку списка разрешённых типов. |
| `default_path` | Добавьте файл в `include`: это переопределяет встроенные шаблоны исключения тестовых файлов. |
| `deleted` | Ничего делать не нужно: нового содержимого для ревью нет. |

### Моё пользовательское правило не срабатывает

Запустите `ocr rules check <file-path>`. Команда выводит **уровень** и
**glob-шаблон**, которые совпали после прохождения всей цепочки:

```
File: src/api/UserHandler.go
Source: Project (.opencodereview/rule.json)
Pattern: src/api/**/*.go
Rule: …
```

Если показан неверный уровень (например, "System built-in" вместо ожидаемого
правила проекта), скорее всего, важен **порядок объявления**: побеждает первый
совпавший шаблон. Переместите более конкретное правило выше в массиве `rules`
или исправьте glob-шаблон.

### Расширение фигурных скобок не работает

`bmatcuk/doublestar/v4` поддерживает конструкции `{ts,tsx}`. Если совпадения
нет, проверьте наличие лишних пробелов: `{ts, tsx}` с пробелом незаметно не
совпадает с `tsx`.

## Ревью

### Для файла показано ноль комментариев — он действительно был проверен?

Откройте [Просмотр сессий](../viewer/) (`ocr viewer`), найдите сеанс и
посмотрите дорожку `main_task` нужного файла:

- Есть вызовы инструментов и завершение `task_done` → ревью успешно завершено
  без замечаний.
- Есть вызовы инструментов, но цикл оборвался → найдите карточку ошибки.
- Карточек `main_task` нет → файл был отфильтрован до ревью; см. раздел
  [Фильтрация и правила](#filtering--rules) выше.

### У комментариев указано `start_line: 0` и `end_line: 0`

OCR не смог привязать комментарий к конкретной строке diff. Две
распространённые причины:

- Модель перефразировала `existing_code`, вместо того чтобы дословно
  скопировать его из diff. Инструкция запрещает это, но иногда модель её
  нарушает.
- Необычное форматирование diff (CRLF, смешанные табуляции и пробелы) нарушило
  сопоставление скользящим окном.

Комментарий всё равно действителен — просто он не был размещён автоматически.
Большинство интеграций с агентами (SKILL, плагин Claude Code) читают поле
`existing_code` и самостоятельно находят нужное место в файле.

### Превышен порог токенов

```
[ocr] WARNING: prompt tokens (94000) exceed 80% of max_tokens(58888) for src/big.sql
```

Начальный промпт для файла (правило + diff + список изменённых файлов) ещё до
ответа модели превысил 80 % от `MAX_TOKENS = 58888`. OCR пропускает файл и
продолжает работу; в режиме JSON это также отображается в `warnings`.

Возможные решения:

- Добавьте автоматически созданный файл в список `exclude`.
- Разделите крупный рефакторинг на небольшие коммиты.
- Для последовательности небольших коммитов используйте режим `--commit`, а не
  проверяйте их все сразу в режиме рабочей области.

### Этап планирования занял слишком много времени, хотя файл небольшой

Сначала выполните `ocr review --preview`. Если значение `lines.changed` для
файла превышает `PLAN_MODE_LINE_THRESHOLD` (по умолчанию **50**), запускается
этап планирования. Это ожидаемое поведение: крупные diff выигрывают от
предварительного планирования. Чтобы пропустить его для одного ревью,
используйте меньший diff или временно измените встроенный шаблон (для опытных
пользователей; потребуется переопределить `--tools`).

### "Max tool requests reached"

```
[ocr] Max tool requests reached for src/foo.go.
```

Модель выполнила 30 (`MAX_TOOL_REQUEST_TIMES`) раундов использования
инструментов, не вызвав `task_done`. Комментарии, созданные к этому моменту,
всё равно собираются и отображаются. Если это происходит для большинства
файлов, причина обычно в одном из следующего:

- Модель плохо следует инструкции «вызвать `task_done` после завершения».
  Переключитесь на более сильную модель (например, Claude Opus).
- Инструмент возвращает ошибку, а модель продолжает повторять попытки.
  Просмотрите JSONL сеанса: если один и тот же результат инструмента
  повторяется, причина именно в этом.
- Файл действительно большой или насыщен контекстом, и 30 раундов
  недостаточно. Увеличьте или уменьшите предел с помощью `--max-tools <n>`
  (например, `--max-tools 40` для большего числа или `--max-tools 15` для
  меньшего). Значения 1–9 повышаются до 10; `0` (значение по умолчанию)
  использует предел шаблона, равный 30.
- Модель вообще не поддерживает нативный вызов инструментов (это часто
  встречается у локальных моделей) — см.
  ["No tool calls parsed" (локальные модели / Ollama)](#no-tool-calls-parsed-ollama).

### Некоторые субагенты завершаются с ошибкой, но команда возвращает код 0

Это сделано намеренно. OCR изолирует ошибки отдельных файлов, чтобы один
проблемный файл не прерывал ревью 20 файлов. Итоговый код завершения равен `0`,
если успешно обработано *хоть что-то*; ненулевой код возвращается только при
полном сбое, когда не завершился ни один субагент. Проверьте массив `warnings`
в режиме JSON или stderr в текстовом режиме, чтобы увидеть, какие файлы
обработать не удалось.

### Ревью в CI выполняется намного медленнее, чем локально

Две обычные причины:

- **Ограничения частоты запросов модели** — при ограничении клиент LLM
  увеличивает интервалы и повторяет запросы. Уменьшите `--concurrency`
  (например, до `4`), чтобы не достигать ограничения.
- **Холодный кеш** — если поставщик поддерживает кеширование промптов, первый
  запуск после развёртывания не получает от него преимуществ. Последующие
  запуски в том же временном окне выполняются быстрее.

## Вывод и интеграция

### При `--audience agent` всё равно отображаются строки хода выполнения

Убедитесь, что это не **stderr**. Сообщения о ходе выполнения (предупреждения и
ошибки) иногда отправляются в stderr. Чистый stdout, гарантируемый параметром
`--audience agent`, предназначен *для удобного разбора*. Чтобы скрыть весь
остальной вывод, перенаправьте его:
`ocr review --audience agent 2>/dev/null`.

### Вывод JSON равен `{ "files_reviewed": 0, "comments": [] }`

В рабочей области не было подходящих файлов. Это сделано намеренно: явная
структура позволяет вызывающей стороне отличить «проверять нечего» от «в
проверенных файлах замечаний нет». Обычное ревью без комментариев возвращает
стандартный пустой массив `[]`.

### Где хранятся файлы JSONL сеансов?

```
~/.opencodereview/sessions/<path-encoded-repo-path>/<session-id>.jsonl
```

Путь репозитория кодируется заменой `/` и `\` на `-`, а `:` — на `_`
(например, `/Users/foo/my-repo` → `Users-foo-my-repo`). Просматривайте сеансы
с помощью `ocr viewer`. Чтобы очистить историю, удалите каталог; при следующем
запуске OCR снова создаст закодированный путь.

## Производительность и стоимость

### Как определить стоимость токенов?

Включите телеметрию:

```bash
ocr config set telemetry.enabled true
ocr config set telemetry.exporter console
ocr review
```

Вызовы LLM не получают отдельных спанов: вместо этого они записываются как
метрики. Следите за `ocr.llm.tokens_used` (счётчик с метками `model` + `type`),
`ocr.llm.requests_total` (счётчик с метками `model` + `status`) и
`ocr.llm.request_duration_seconds` (гистограмма с меткой `model`). Консольный
экспортёр выводит эти агрегаты в процессе работы. Для панелей мониторинга
переключитесь на экспортёр OTLP и отправляйте данные в свой стек метрик — см.
раздел [Телеметрия](../telemetry/).

### Почему мои ревью такие дорогие?

Основные способы повлиять на стоимость:

- Этап планирования включается для файлов с 50 и более изменёнными строками. Он
  требует дополнительного вызова LLM для каждого файла. Уменьшение порога
  снижает стоимость, а его увеличение ускоряет небольшие PR.
- Значение `MAX_TOOL_REQUEST_TIMES = 30` достаточно велико. Модель,
  использующая каждый раунд, создаёт более длинный диалог (и расходует больше
  токенов), чем модель, завершающая работу за 3 раунда. Более сильные модели
  обычно заканчивают быстрее. И наоборот, если вы увеличили предел с помощью
  `--max-tools`, чтобы избежать ошибки "max tool requests reached", стоимость
  каждого файла будет расти примерно линейно.
- Сжатие памяти само по себе является вызовом LLM. Длительные подзадачи
  оплачивают раунды сжатия в дополнение к раундам ревью.

### Как уменьшить количество вызовов LLM?

- Добавьте список `include`, чтобы OCR не проверял ненужные файлы.
- Уменьшите `--concurrency`, если ваша учётная запись использует тарификацию
  пиковых нагрузок.
- Передавайте `--background`: более полный исходный контекст иногда позволяет
  модели завершить работу без дополнительных вызовов `file_read` /
  `code_search`.

## Конфиденциальность и безопасность

### Отправляет ли OCR мой код куда-либо?

OCR отправляет ваши **diff** (и необязательные фрагменты, прочитанные
инструментами) на настроенный вами эндпоинт LLM. Никакие другие данные не
покидают компьютер: файлы JSONL сеансов и правил хранятся только локально.

Если телеметрия включена, параметр `content_logging` проходит через слой
конфигурации, но сейчас **не управляет** ни одной ветвью кода: содержимое
промптов и ответов никогда не экспортируется в сборщик независимо от значения
параметра. Считайте его зарезервированным и оставляйте значение `false` в
рабочей среде. Подробнее см. в разделе
[Телеметрия](../telemetry/#content-logging).

### Можно ли скрыть секреты перед отправкой в LLM?

Встроенной функции нет. Рекомендуемый процесс:

1. Не добавляйте секреты в репозиторий (обычное правило).
2. Добавляйте в `exclude` файлы, которые заведомо содержат секретные данные.
3. Используйте фильтры `git diff --no-textconv` или маскирование перед коммитом,
   чтобы секреты не попадали в diff.

Функция «правил маскирования» запланирована; следите за
[трекером задач](https://github.com/alibaba/open-code-review/issues).

## Разное

### Где находится журнал изменений?

В [релизах GitHub](https://github.com/alibaba/open-code-review/releases):
каждый релиз содержит примечания, созданные из Conventional Commits.

### Поддерживает ли OCR системы контроля версий, отличные от Git?

Нет. Провайдеры diff запускают `git` во внешнем процессе. Для SVN, Mercurial и
других систем потребуются новые провайдеры; задача о поддержке Hg открыта
[здесь](https://github.com/alibaba/open-code-review/issues).

### Почему бинарный файл называется `opencodereview`, а CLI — `ocr`?

Статический бинарный файл, публикуемый в релизах, назван по имени проекта
(`opencodereview`); обёртка NPM устанавливает его как `ocr` для удобства. При
сборке из исходного кода получается `dist/opencodereview` — скопируйте его как
`ocr` в каталог из `$PATH`.

### Как удалить OCR?

```bash
npm uninstall -g @alibaba-group/open-code-review        # NPM install
sudo rm /usr/local/bin/ocr                              # binary install
rm -rf ~/.opencodereview                                # all state
```

OCR не записывает данные за пределами `~/.opencodereview` (кроме бинарного
файла, загружаемого через NPM), поэтому удаление этого каталога очищает историю,
конфигурацию и пользовательские правила.

## См. также

- [Конфигурация](../configuration/) — разрешение эндпоинта LLM и ключи конфигурации.
- [Правила ревью](../review-rules/) — фильтрация файлов и цепочка разрешения правил.
- [Просмотр сессий](../viewer/) — изучение прошлых сеансов ревью.
- [Телеметрия](../telemetry/) — использование токенов и метрики LLM.
