Что делать, если что-то не работает?

Коротко: начните с orch doctor (или /orch:doctor в Claude Code): он проверяет установку и проект, ничего не меняет и к каждой проблеме печатает подсказку после стрелки →. Дальше — разделы ниже по симптому.

orch doctor: что проверяет и как читать вывод

orch doctor           # человекочитаемый вывод
orch doctor --json    # то же в JSON

Каждая строка начинается со значка:

Строка с подсказкой → … — готовая команда или шаг. В конце — итог: Итог: ok N · warn N · fail N · info N.

Что проверяется (источник: plugin/cli/doctor.mjs):

• node — нужен Node 20 или новее, и его должны находить хуки плагина при запуске приложения из Dock.
• плагин — установлен ли (симлинк ~/.claude/skills/orch или маркетплейс), версия.
• orch в PATH — виден ли orch в терминале.
• агенты и skills агентов — совпадают ли настройки агентов с config/models.json.
• хуки и гарды — валиден ли hooks.json; на временном проекте проверяется, что защита запрещает git push и запись в .env, а git status разрешает.
• события — срабатывали ли хуки недавно.
• доска, statusLine, git, graphify.
• проект — .orchestrator/config.json: валидность, команды проверки, зоны, пресет типа проекта, модуль статей.
• search-\* — поиск по коду: плагины LSP, TypeScript 5, граф graphify.
• remote-\* — удалённая работа: маршрут orch exec, адрес API для Remote Control, реестр фоновых процессов, claude CLI, доверие каталогу, облачный сервер.

Частые проблемы

orch: command not found в терминале

Каталог ~/.local/bin не в PATH: добавьте в ~/.zshrc строку export PATH="$HOME/.local/bin:$PATH". Внутри Claude Code команда orch доступна всегда.

Команды /orch:* не появились после установки или обновления

Выполните /reload-plugins в открытой сессии или откройте новую. Если не помогло — orch doctor, строки «плагин» и «события».

Агент написал appagent guard: …

Это сработала защита: агент попытался сделать запрещённое (push, удаление вне проекта, чтение .env, установку пакетов, запись вне своей зоны). Обычно ничего делать не нужно: агент завершит задачу как заблокированную и опишет нужное действие, лид выполнит его после вашего «да». Что именно блокируется — Безопасность. Если правило мешает постоянно, разрешение добавляется в .orchestrator/config.json → guard.allowInSubagents (подробности — ../RUNBOOK.md).

Упёрлись в лимит подписки

В ответе «hit your limit» или «rate limit»: дождитесь сброса окна (время — в строке состояния), затем скажите «продолжи прогон». Чтобы вместить работу в остаток окна, выберите дешёвый профиль — см. Экономия лимита.

Сессия разрослась или была долгая пауза

Дайте закончить текущий шаг, затем /orch:handoff и новая сессия со словом «продолжай»: состояние хранится в .orchestrator/, ничего не теряется. Подробнее — Как ставить задачи.

Прогон оборвался

Откройте новую сессию в проекте, выполните /orch:status и скажите «продолжи прогон». Готовые задачи пропускаются, остальные запускаются заново.

Доска не открывается

Подробнее — Доска-пульт.

1. orch board status — запущена ли доска и на каком порту; orch board stop, затем /orch:board — перезапуск.
2. Экран входа вместо доски: ссылка входа одноразовая и живёт 10 минут; новая — orch board token.
3. «Слишком много неверных попыток входа»: подождите; если ссылку мог увидеть чужой — orch board token --rotate (прежние входы отзываются).
4. После обновления плагина доска ведёт себя странно: orch board stop && orch board.
5. Порт занят: orch board --port 4400.
6. Ответ 403: открывайте http://127.0.0.1:<порт>/ или http://localhost:<порт>/; другие имена хоста доска отклоняет намеренно.
7. Причины смотрите в логе ~/.claude/orch/board.log.

Агенты ищут по коду медленно (LSP не работает)

orch doctor → строки search-* показывают, чего не хватает, и дают команду. Без LSP всё работает, поиск лишь менее точен. Для .vue нужен отдельный мод vue-lsp (mods/vue-lsp/README.md в репозитории).

Фоновый процесс упал или завис (работа с телефона)

orch exec list            # что идёт и что упало
orch exec status <id>     # причина: лимит ходов, отказы разрешений, хвост ошибок
orch exec stop <id>       # остановить
orch exec --resume-from <id>   # продолжить: готовое не переделывается

Сервер перегружен — лиды ждут в очереди; это не ошибка, они стартуют, когда нагрузка падает. Подробнее — ../RUNBOOK.md, раздел «Нагрузка: сервер перегружен». Про сервер и телефон — Телефон и статьи.

Нет доступа к Claude из России

Anthropic не обслуживает Россию и Беларусь. Сервер для удалённой работы нужно арендовать в поддерживаемой стране (../SERVER.md). Доступ к Claude appagent не предоставляет.

Не помогло

Поддержки в тарифе нет. Обновитесь до последней версии (Что нового) и повторите orch doctor: возможно, проблема исправлена. Вывод orch doctor --json пригодится вам самим и тому, кто будет разбираться (в нём пути и статусы; перед отправкой кому-либо просмотрите его).