Claude Code — это AI-агент от Anthropic который работает прямо в терминале. Не расширение для IDE, не чат в браузере — полноценный инструмент командной строки который читает ваш репозиторий целиком, понимает архитектуру проекта, вносит изменения в несколько файлов одновременно и коммитит результат. Запускается командой claude из любой папки проекта.
В этом руководстве разберём три способа установки на macOS, их отличия, как пройти авторизацию, настроить первый проект и что делать если что-то пошло не так. Актуально для macOS 10.15 Catalina и новее — от Intel Mac до Apple Silicon.
Что нужно до начала установки
Claude Code требует оплаченного аккаунта Anthropic. Бесплатный Claude.ai для работы с Claude Code не подходит. Доступные варианты: Claude Pro — $20/месяц, покрывает большинство задач разработки; Claude Max — $100 или $200/месяц, для интенсивного использования с высокими лимитами; Anthropic Console — API-доступ с балансом на аккаунте, подходит для автоматизации и CI/CD.
Системные требования: macOS 10.15+, 4 GB RAM минимум (8 GB+ для комфортной работы с большими репозиториями), 200–300 MB свободного места на диске. Git желателен — Claude Code использует историю коммитов для понимания контекста проекта.
Проверяете версию macOS:
sw_vers -productVersion
Способ 1: Нативный бинарник (рекомендуется Anthropic)
Это официально рекомендуемый способ. Нативный установщик не требует Node.js, не конфликтует с другими пакетами, автоматически обновляется в фоне.
Открываете Terminal (Spotlight → Terminal или Applications → Utilities → Terminal) и выполняете одну команду:
curl -fsSL https://claude.ai/install.sh | bash
Скрипт скачивает подписанный бинарник, устанавливает его в ~/.local/bin/claude или ~/.claude/bin/claude, автоматически добавляет путь в ~/.zshrc (или ~/.bashrc в зависимости от вашей оболочки).
После установки перезапускаете терминал или выполняете:
source ~/.zshrc
Проверяете что установка прошла успешно:
claude --version
claude doctor
Команда claude doctor диагностирует конфигурацию — проверяет PATH, права, состояние авторизации и здоровье MCP-серверов. Запускайте её первой при любых проблемах.
Бинарник macOS подписан Anthropic PBC и нотаризован Apple — никаких предупреждений Gatekeeper при запуске.
Способ 2: Homebrew
Для тех кто уже использует Homebrew и предпочитает управлять инструментами через него:
brew install --cask claude-code
Homebrew установит Claude Code как cask (GUI-приложение или нативный бинарник). Работает корректно, но у этого способа есть один минус: автообновление не работает. Новые версии нужно устанавливать вручную:
brew upgrade claude-code
Если вы не следите за обновлениями регулярно, через несколько месяцев окажетесь на устаревшей версии. Для рабочего использования это неудобно.
Способ 3: npm (устаревший, но рабочий)
Этот способ всё ещё работает, но Anthropic официально помечает его как устаревший. Используйте его только если у вас есть конкретная причина — например, нужно зафиксировать определённую версию или вы работаете в среде где npm является стандартом.
Требование: Node.js 18 или выше. Проверяете:
node --version
Если Node.js не установлен или версия ниже 18 — устанавливаете через nvm (рекомендуется) или с nodejs.org:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc
nvm install 22
nvm use 22
nvm (Node Version Manager) позволяет держать несколько версий Node.js и переключаться между ними. Версия 22 LTS — актуальная рекомендация для Claude Code.
Устанавливаете Claude Code глобально:
npm install -g @anthropic-ai/claude-code
Важно: никогда не используйте sudo с этой командой. sudo npm install -g ломает права на npm-директорию и создаёт проблемы с безопасностью которые потом сложно исправить. Если видите ошибку EACCES (отказ в доступе) — настраиваете npm так чтобы он использовал директорию в вашем домашнем каталоге:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
После этого повторяете установку без sudo.
Авторизация
После установки любым из трёх способов запускаете:
claude
Claude Code попытается открыть браузер для OAuth-авторизации через аккаунт Anthropic. Если браузер открылся — входите в свой аккаунт Claude.ai и подтверждаете доступ.
Если браузер не открылся автоматически (headless-среда, SSH, Docker) — используйте флаг --headless:
claude auth login --headless
Терминал покажет URL — копируете его, открываете в браузере на любом устройстве, авторизуетесь и вставляете полученный код обратно в терминал.
Токен авторизации хранится в ~/.claude/config.json (AES-256 шифрование) и остаётся активным 30 дней без использования. Если работаете через API-ключ напрямую:
export ANTHROPIC_API_KEY=sk-ant-...
Добавьте эту строку в ~/.zshrc чтобы ключ подставлялся автоматически при каждой сессии.
Проверяете авторизацию:
claude doctor
В выводе должны видеть: Authentication: ✓ Logged in.
Первый запуск
Переходите в папку проекта и запускаете Claude Code:
cd ~/Projects/my-project
claude
Claude Code за 2–5 секунд анализирует структуру репозитория (для проекта до 50,000 файлов) и приветствует вас интерактивным интерфейсом в терминале. Можно сразу задавать вопросы о коде на русском или английском.
Несколько полезных команд для старта:
claude "объясни архитектуру этого проекта"
claude "найди все места где обрабатываются ошибки"
claude "добавь unit-тест для функции processPayment"
Для неинтерактивного использования (скрипты, CI/CD):
claude -p "проверь наличие SQL-инъекций в файлах controllers/" --output-format json
Настройка CLAUDE.md
CLAUDE.md — это файл в корне проекта который Claude Code читает при каждом запуске. Здесь вы описываете контекст который AI должен знать о вашем проекте: команды для запуска, соглашения по коду, архитектурные решения.
Создаёте в корне проекта:
nano CLAUDE.md
Коммитьте CLAUDE.md в репозиторий — тогда все участники команды получают одинаковый контекст.
В монорепозиториях добавляйте CLAUDE.md в каждую поддиректорию: корневые правила применяются везде, правила поддиректории — только когда работаете в ней.
Типичные проблемы на macOS
command not found: claude после установки. PATH не обновился в текущей сессии терминала. Перезапустите Terminal или выполните source ~/.zshrc. Если не помогло — проверьте что в ~/.zshrc есть строка с экспортом пути (установщик добавляет её автоматически, но иногда в неправильный файл если у вас нестандартная конфигурация shell).
Gatekeeper блокирует запуск. Нативный бинарник нотаризован Apple и блокироваться не должен. Если всё же блокируется — скорее всего у вас npm-установка старой версии. Переустановите нативным способом.
EACCES при npm install. Не используйте sudo. Настройте npm prefix как описано выше, или переходите на нативный установщик.
Slow start или зависает на анализе проекта. Большие node_modules, .git с огромной историей или монорепозитории с десятками тысяч файлов. Добавьте .claudeignore в корень проекта (синтаксис как у .gitignore) с исключениями:
node_modules/
dist/
.next/
*.log
Авторизация не срабатывает. Запустите claude auth login --headless и авторизуйтесь вручную через браузер.
Полезные ссылки:
- Официальная документация Claude Code
- Claude Pro подписка
- Anthropic Console (API-ключи)
- npm пакет @anthropic-ai/claude-code
FAQ:
Claude Code бесплатный? Нет. Требует оплаченный аккаунт: Claude Pro ($20/мес), Claude Max ($100–200/мес) или баланс в Anthropic Console. Бесплатный план Claude.ai не даёт доступа к Claude Code.
Нужен ли Node.js для установки? Только для npm-способа (устаревший). Нативный установщик и Homebrew не требуют Node.js вообще.
Работает ли на Apple Silicon (M1/M2/M3/M4)? Да, нативный бинарник поставляется для arm64. Устанавливается и работает без Rosetta 2.
Как обновить Claude Code? Нативный установщик обновляется автоматически в фоне. Для Homebrew: brew upgrade claude-code. Для npm: npm update -g @anthropic-ai/claude-code.
Можно ли использовать с приватными репозиториями? Да. Claude Code работает локально с файлами на вашем компьютере. В Anthropic уходят только запросы к модели, не содержимое файлов целиком — только контекст который вы явно добавляете в запрос.