Встановлення, авторизація, оновлення та діагностика

1. Встановлення — це лише половина справи

Claude Code встановлено. Далі все одно щось ламається: команда claude не знаходиться, відкривається не те середовище, вхід виконано чужим обліковим записом, проєкт лежить у WSL, а CLI запущено з PowerShell. Встановлення ≠ готовність до роботи.

Карта поверхонь у вас вже є з минулої лекції: маршрут іде з проєкту в терміналі, IDE — для перевірки результату. Тепер його треба привʼязати до вашої машини.

Гарний перший запуск нудний — отже, далі ви займетеся кодом, а не розкопками в терміналі. Критерій готовності — чотири відповіді:

• чи бачить система команду claude;
• чи запускається сесія;
• чи розуміє Claude ваше середовище через /doctor;
• під яким обліковим записом усе працює.

Точні команди встановлення змінюються — інструмент розвивається швидко. Тому я даю не вічний магічний рядок, а логіку: встановлюєте CLI актуальним способом за офіційною документацією, потім перевіряєте готовність середовища.

2. Встановити CLI на свою ОС

Спочатку принципи, потім команди.

Способів кілька — це нормально. CLI встановлюється через менеджер пакетів ОС, npm або офіційний скрипт. Усі варіанти дійсні, але дають різні шляхи оновлення і місця встановлення.

Беріть спосіб, який уже живе на вашій машині. Є Homebrew — через нього; працюєте з Node.js — npm; нічого немає — офіційний скрипт. Не встановлюйте менеджер пакетів заради одного інструмента.

Актуальна команда — в офіційній документації. Рядки нижче — приклади на момент написання, звіряйте з docs.

macOS

Три шляхи. Homebrew, якщо він уже встановлений:

brew install --cask claude-code

npm, якщо встановлено Node.js:

npm install -g @anthropic-ai/claude-code

Офіційний скрипт, без попередніх умов:

curl -fsSL https://claude.ai/install.sh | bash

Після будь-якого способу в новому вікні термінала має працювати команда claude. Не працює — майже завжди PATH, який не оновився в поточній сесії. Перезапустіть термінал. Докладніше — у розділі про сигнали першого дня.

Про Apple Silicon (M1/M2/M3/M4): сучасні інсталятори самі обирають збірку. Помилки про архітектуру — сигнал, що Homebrew або Node працюють через Rosetta, а CLI встановлено під іншу архітектуру. Виправляється перевстановленням Homebrew/Node під нативний arm64.

Linux

Те саме, але без Homebrew. Два шляхи — npm і офіційний скрипт:

# через npm, якщо є Node.js
npm install -g @anthropic-ai/claude-code

# або офіційний скрипт-інсталятор
curl -fsSL https://claude.ai/install.sh | bash

Скрипт кладе бінарник у ~/.local/bin або аналог у домашньому каталозі. Глобальний npm-пакет — туди, куди налаштовано npm prefix. Налаштовано на системні каталоги (/usr/local/lib/node_modules) — знадобиться sudo, але це погана ознака: переналаштуйте prefix на домашній каталог і не встановлюйте глобальні пакети під root.

Контейнерні середовища (Docker, dev container, CI runner): Claude Code встановлюється всередині контейнера, а не на хості. Встановлення на ноутбуці контейнеру не допомагає — файли проєкту живуть у ньому.

Windows

Варіантів одразу кілька, і вони принципово різні.

Native PowerShell — якщо проєкт і Git живуть у звичайному середовищі Windows. Офіційний скрипт:

irm https://claude.ai/install.ps1 | iex

Або npm, якщо у вас є Node.js:

npm install -g @anthropic-ai/claude-code

WSL (Windows Subsystem for Linux) — якщо проєкт лежить всередині WSL (веброзробка, Docker, Linux-tooling). Встановлюйте там само, як на звичайному Linux:

# всередині WSL
curl -fsSL https://claude.ai/install.sh | bash

Git Bash — окремий випадок: Claude Code, встановлений нативно у Windows, працює і в Git Bash. Окремо встановлювати нічого не потрібно.

Головна Windows-пастка: встановити CLI в одному середовищі, запускати з іншого. Встановили в WSL — запускайте з WSL. Встановили нативно — з PowerShell або Git Bash. Встановили нативно, а проєкт у WSL — Claude побачить файлову систему Windows, а не вашу папку всередині WSL. Це не поломка, просто різні світи. Повернетеся до таблиці з наступного розділу: де проєкт і звідки запуск.

Що робити відразу після встановлення

Незалежно від ОС, перша дія одна:

claude --version   # перевірили, що система бачить команду і правильну версію

Версія вивелася без помилок — встановлення відбулося. Повну діагностику (/doctor, /status) запускаємо всередині відкритої сесії — про це в наступних розділах. Не поспішайте із завданням: спочатку виберіть правильне середовище та відкрийте проєкт там, де він живе.

3. Запускайте Claude там, де живе проєкт

Одна команда поводиться по-різному залежно від того, де ви її запускаєте. На Windows особливо: проєкт у WSL, Git у Git Bash, IDE відкриває PowerShell. Формально один ноутбук, фактично — кілька робочих світів.

Правило: запускайте Claude Code там само, де живе проєкт і де ви зазвичай запускаєте його команди.

На Windows обидва шляхи нормальні. «Правильний» — той, де вже живуть проєкт, Git і інструменти. Проєкт у WSL — туди ж Claude; повністю Windows-native — PowerShell.

Термінал всередині IDE не окремий всесвіт — це вбудований термінал на вибраному shell. Але саме тут спливає ефект: в звичайному вікні WSL, а в IDE раптом PowerShell. Ззовні «один проєкт», по факту — різна діагностика. Першу перевірку запускайте в тому терміналі, яким будете користуватися щодня.

Сумніваєтеся в папці — орієнтуйтеся на корінь проєкту: там лежать README, build.gradle, package.json, docker-compose.yml. Для наскрізного прикладу це каталог із Commerce OS, а не робочий стіл і не домашній каталог.

4. Перший запуск: версія, сесія, діагностика

Правильне середовище вибрано — марафон команд не потрібен. Достатньо короткого ланцюжка: усе готово або де саме затримка.

flowchart TD
    A[Встановили Claude Code] --> B[Відкрили термінал у потрібному середовищі]
    B --> C[Перейшли до каталогу проєкту]
    C --> D[Перевірили claude --version]
    D --> E[Запустили claude]
    E --> F["/doctor"]
    F --> G["/status"]
    G --> H{Усе гаразд?}
    H -- Так --> I[Зберегли лог першого запуску]
    H -- Ні --> J[Виправили shell / PATH / auth / каталог і повторили]

На практиці:

cd ~/projects/commerce-os      # переходимо до каталогу проєкту
claude --version               # наприклад: 2.1.x
claude                         # відкриваємо інтерактивну сесію

Команди на кшталт /... працюють всередині відкритої сесії, а не у звичайному shell. Спочатку claude, потім діагностика всередині сесії:

/doctor                        # перевірка встановлення, shell, авторизації та оточення
/status                        # поточний стан сесії

Назви команд або формат виводу у вашій версії трохи інші — не катастрофа. Джерело істини: вбудований /help, claude --version та актуальна довідка, а не скриншот із чужого блогу.

Що дають ці кроки:

claude --version відповідає на головне питання: чи бачить ОС Claude Code як виконувану команду. Замість версії бачите:

claude: command not found
# або
'claude' не є внутрішньою або зовнішньою командою

— проблема не в інструменті: shell його не знаходить. Зазвичай PATH, інше середовище або неперезапущений термінал.

claude запускайте з каталогу проєкту. Відкриєте зі випадкової папки — Claude не допоможе з тим проєктом, що був у голові.

/doctor — вбудована діагностика: підсвічує стан встановлення, авторизації та оточення, не «ставить оцінку». Не кожне попередження — кінець світу. «Бачу не той shell» — привід зіставити факти, а не перевстановлювати все: де проєкт, з якого термінала вхід, чи збігається це з робочим середовищем.

/status — коротка картка: чи активна сесія, чи видно проєкт, чи все гаразд з авторизацією. claude --version працює, сесія відкрилася, /doctor без критики, /status спокійний — старт хороший.

5. Авторизація та оновлення

Вхід і оновлення лякають не складністю, а тим, що в різних людей виглядають по-різному. В одного все пройшло через браузер за хвилину, у вас шлях інший — і одразу думка «все зламалося, я особливий». Так буває: у вас просто інший сценарій доступу — тип підписки, робочий обліковий запис, командний доступ, спосіб оплати, корпоративне налаштування.

Розбиратися в кожному варіанті не потрібно. Важливий не вигляд вікна входу, а результат: Claude Code авторизовано, і ви знаєте, під яким обліковим записом. Тому після входу знову дивіться /status. Вхід виконано не тим обліковим записом — завершіть сеанс способом із вашої актуальної версії та увійдіть знову. Звичка важливіша за команду: побачили сумнів — перевірили статус, поправили обліковий запис, прогнали діагностику.

З оновленнями правило те саме: оновлюйте тим самим способом, яким встановлювали. Менеджером пакетів — через нього. Окремим інсталятором — тим самим каналом. Змішаєте способи — отримаєте дві версії на машині, і shell підхопить не ту.

claude --version               # наприклад: 2.1.x
# оновіть Claude Code тим самим способом, яким встановили його спочатку
claude --version               # наприклад: 2.1.y

Після оновлення відкрийте Claude і проганяйте /doctor — дешева перевірка. Попросили знову увійти — повторний вхід після оновлення буває, це не поломка. І не женіться за номером версії з чужого відео: трохи новіша або старіша — не проблема. Мета першого дня — робоче й передбачуване середовище, а не колекція номерків.

6. Не працює з першого разу: читайте сигнали

Акуратний запуск інколи впирається в технічну прозу: shell не бачить команду, термінал в IDE в іншому середовищі, проєкт відкрито не там, авторизація крутиться по колу. Це корисно: тут ви поводитеся як інженер — симптом, гіпотеза, виправлення.

Найчастіша історія першого дня — це PATH. Якщо говорити зовсім по-людськи, PATH — це список місць, де ОС шукає команди. Уявіть список адрес, по яких shell бігає в пошуках дверей із написом claude. Якщо двері існують, але адреси немає в списку, shell чесно каже: «Вибачте, не знаю такої команди». Тому повідомлення command not found далеко не завжди означає, що Claude Code «не встановився». Дуже часто це означає, що поточний shell просто не знає, де його шукати.

Не менш часта історія — різні середовища під одним дахом. Наприклад, ви встановили Claude Code і перевірили його в одному вікні термінала, а потім відкрили IDE, всередині якої термінал налаштовано по-іншому. Там уже інше життя: інший shell, інший PATH, інколи взагалі інша файлова система. Звідси й магічні ефекти на кшталт «годину тому все працювало». Насправді не магія. Просто ви зайшли через інші двері.

Окремо запамʼятайте важливе правило для віддалених і контейнерних середовищ. Якщо проєкт реально живе по SSH або всередині контейнера, локальне встановлення Claude Code на вашому ноутбуці не робить його автоматично доступним там. Це часта помилка новачка: команда чудово працює локально, але під час переходу у віддалене середовище її ніби ніколи не існувало. І це нормально. Просто CLI має бути встановлений і запущений там, де виконуються команди проєкту.

У цей момент дуже хочеться почати перевстановлювати все підряд по колу. Зазвичай це погана стратегія. Значно корисніше поставити собі чотири спокійні запитання. Чи бачу я команду claude? Чи я в тій самій середовищі, де живе проєкт? Чи тим самим обліковим записом виконано вхід? Що саме показує /doctor? Зазвичай уже на одному з цих кроків проблема стає помітною без чаклунства.

7. Лог першого запуску: артефакт, що рятує час

Коли перша діагностика пройшла успішно, рука так і тягнеться закрити термінал і радісно йти далі. Але дуже корисно зробити одну маленьку річ: зберегти короткий лог першого запуску. Це не офіційний звіт і не бюрократія заради бюрократії. Це ваша контрольна фотографія робочого стану.

Такий лог може виглядати дуже просто:

# Лог першого запуску Claude Code

Дата: 2026-05-24
Проєкт: AI Commerce Growth OS
Каталог: ~/projects/commerce-os
ОС: macOS / Windows / Linux
Shell: zsh / bash / PowerShell / WSL
Claude CLI: 2.1.x
Авторизація: ok
/doctor: без критичних помилок
/status: сесія активна, проєкт відкритий

Нотатки:
- Claude запускаю з WSL, не з PowerShell
- термінал в IDE має використовувати те саме середовище

Чому це корисно? Тому що через кілька днів або після першого оновлення у вас зʼявляється дуже приземлена точка порівняння. Якщо щось раптом перестало працювати, ви не згадуєте ситуацію по памʼяті в дусі «ніби все було нормально». Ви відкриваєте свій же лог і дивитеся: з якого середовища ви запускали Claude, яка версія була, під яким shell усе працювало і що було записано в нотатках.

Особливо добре це працює у наскрізному проєкті. Ви відкриваєте Commerce OS, запускаєте Claude Code зі знайомої теки, проганяєте /doctor, бачите спокійний стан — і знаєте, що старт дійсно був коректним. Не тому, що вам так здається, а тому, що у вас є маленький, але дуже зрозумілий слід.

На цьому етапі вам не потрібно знати всі можливості Claude Code і тим більше не потрібно памʼятати всі його команди напамʼять. Достатньо куди ціннішого стану: ви розумієте, де запускаєте інструмент, як перевірити його встановлення, чим підтверджується робоча авторизація і яким способом швидко діагностувати першу проблему. Для першого робочого дня це вже дуже хороший технічний фундамент.

8. Доступ до Claude Code на цьому курсі

Залишилося закрити останнє практичне питання: під яким обліковим записом ви запускатимете Claude Code на цьому курсі. У розділі про авторизацію ми говорили, що шлях входу у всіх може виглядати по-різному — особиста підписка, робочий обліковий запис, командний доступ. Для навчання ми обрали окремий шлях, який не вимагає від вас особистої підписки і однаково працює в усіх студентів: доступ через сервер JavaRush.

Ідея проста. Замість того щоб кожен студент підключав власний платіжний обліковий запис, ми видаємо вам індивідуальний доступ до нашого шлюзу. Claude Code думає, що звертається до звичайного API, але насправді його запити йдуть через наш Gateway, який уже знає, яку модель віддати і як врахувати витрати. Для вас це означає рівно одне: менше метушні з налаштуванням доступу і єдині умови для всієї групи.

Технічно це налаштовується через змінні середовища у конфігураційному файлі Claude Code. Усе просто й красиво: CLI читає налаштування і розуміє, за якою адресою звертатися і з яким токеном.

Два файли налаштувань: глобальний і проєктний

Ми дамо вам два файли налаштувань, і важливо одразу зрозуміти, чим вони відрізняються і хто з них головніший. Claude Code читає налаштування з кількох місць і накладає їх за пріоритетом — більш «вузький» файл перебиває більш «широкий».

~/.claude/settings.json

.claude/settings.local.json

Пріоритет такий: проєктний settings.local.json перебиває глобальний settings.json. Логіка як з одягом: глобальний файл — це базовий шар, який одягнутий завжди, а проектний local — це те, що ви накидаєте зверху для конкретної ситуації.

Навіщо саме два файли, а не один? Тому що це дає вам гнучкість без ризику зламати базу. Глобальний файл із доступом до Gateway ви налаштували один раз — і він мовчки працює в усіх навчальних проєктах. А проєктний settings.local.json — це ваша пісочниця: тут можна відпрацьовувати складніші сценарії конфігурації, перевизначати окремі параметри під конкретний проєкт і експериментувати, точно знаючи, що базовий доступ при цьому залишиться цілим. Якщо експеримент у local-файлі щось зламав — ви просто прибираєте оверрайд, і глобальне налаштування знову в силі.

Як виглядає глобальний файл доступу

Доступ до Gateway ми кладемо саме в глобальний ~/.claude/settings.json — щоб він працював у будь-якому проєкті курсу, а не лише в одному. Вміст виглядає так (ключ тут — завідомо несправжній, свій індивідуальний ви отримаєте окремо):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm.javarush.com",
    "ANTHROPIC_AUTH_TOKEN": "PASTE_YOUR_COURSE_KEY_HERE",
    "ANTHROPIC_MODEL": "claude-course-fast",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-course-fast",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-course-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-course-max"
  }
}

Розберімо три рядки по суті:

• ANTHROPIC_BASE_URL — адреса, куди CLI надсилає запити. Замість стандартного API він дивиться на наш Gateway, а ми вже далі пересилаємо ваші запити на сервер.
• ANTHROPIC_AUTH_TOKEN — ваш індивідуальний ключ доступу до Gateway. Саме за ним наш шлюз розуміє, що запит ваш, і веде облік витрати токенів. Цей ключ — особистий, його не потрібно нікому показувати і тим більше комітити в репозиторій.
• CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY — прапорець, який перемикає Claude Code CLI на сервер JavaRush.

Важливий момент, який ми закріплюємо одразу: ключ доступу знаходиться в глобальному файлі в домашньому каталозі, а не в проєкті. Тому його фізично неможливо випадково закомітити разом із кодом. А проєктний settings.local.json, у якому ви експериментуєте, і так не потрапляє в Git. Так зроблено не випадково — це та сама інженерна гігієна, про яку курс буде нагадувати постійно: секрети не виїжджають у репозиторій.

Перевірка, що доступ працює

Перевіряється все тим самим способом, що й звичайна авторизація з розділу 5. Джерело правди — /status: відкриваєте сесію і дивитеся, що Claude Code бачить доступ і готовий до роботи.

claude                 # відкриваємо сесію

/status                # переконуємося, що доступ через Gateway активний

Якщо /status виглядає спокійно — вітаю, технічний старт на курсі у вас повністю зібраний: базове середовище (Git, Node.js), сам Claude Code, решта стеку проєкту та робочий доступ через Gateway. Далі починається найцікавіше — реальна робота над проєктом. І, на відміну від встановлення, ось її-то заучувати напамʼять не доведеться: ви вчитиметеся думати, а не запамʼятовувати команди.