Безопасная первая настройка Claude Code в VS Code

Что должно получиться

В конце проверки у вас будет пустой локальный проект и текстовый паспорт, в котором записаны:

• версия VS Code;
• идентификатор и версия установленного расширения Claude Code;
• абсолютный путь и версия терминального CLI;
• среда, из которой запускается терминал;
• использованный способ авторизации без токенов и других секретов;
• начальный режим разрешений;
• результаты тестов чтения, попытки записи и проверки границы проекта;
• признаки, по которым можно отличить ошибку расширения от ошибки CLI, входа или разрешений.

AI-агент — система, которая получает цель и может использовать инструменты для выполнения действий. В этой статье Claude Code рассматривается именно как агент: важен не только его ответ, но и то, какие файлы и команды ему фактически доступны.

Allowlist, или список разрешённых действий, задаёт узкую положительную границу: всё, что в неё не входит, не должно выполняться автоматически. Для первой настройки этот подход безопаснее широкого доступа с отдельными запретами.

Конкретный случай: интерфейс работает, а происхождение доступа неизвестно

Представим типичную первую установку. Разработчик устанавливает расширение из каталога VS Code, затем открывает встроенный терминал и отдельно устанавливает Claude Code CLI. В панели расширения появляется форма входа, а команда claude в терминале тоже предлагает авторизацию.

После входа панель умеет отвечать на вопросы о проекте, но терминальная команда сообщает об ошибке. Возможна и обратная ситуация: CLI работает, а расширение не запускает сессию. По одному сообщению «Claude Code не работает» нельзя определить источник проблемы, потому что неизвестно:

1. какой компонент показал ошибку;
2. какой бинарный файл был запущен;
3. в какой среде находится процесс VS Code;
4. каким способом авторизован каждый интерфейс;
5. какие разрешения действовали в момент проверки;
6. была ли открыта доверенная рабочая папка или отдельный файл.

Ещё опаснее ложный успех: агент ответил на вопрос, поэтому пользователь предполагает, что он работает только в режиме чтения. Но способность отвечать ничего не говорит о разрешении изменять файлы или запускать команды. Это проверяется отдельными контролируемыми тестами.

Модель настройки: четыре независимых слоя

1. VS Code

Хост-приложение, профиль пользователя, доверие к рабочей папке, встроенный терминал и среда процесса.

2. Расширение

Отдельный пакет со своим идентификатором, версией, настройками, журналами и жизненным циклом обновлений.

3. Терминальный CLI

Исполняемый файл claude, найденный через переменную PATH. В разных оболочках могут находиться разные копии.

4. Авторизация и разрешения

Способ входа определяет, от чьего имени выполняются запросы, а режим разрешений — какие локальные действия агент может совершать. Это разные вопросы.

Approval gate, или контур подтверждения, — обязательная пауза перед действием, требующим согласия пользователя. Наличие входа в аккаунт не заменяет такой контроль.

Tool calling — механизм вызова инструментов агентом. Ответ в чате может быть безопасным текстом, а последующий вызов инструмента — чтением файла, изменением документа или запуском команды. Поэтому проверять нужно оба уровня.

Шаг 1. Создайте действительно пустой проект

Не начинайте с рабочего репозитория. Создайте отдельный каталог, в котором нет исходного кода, ключей, файлов окружения, родительского Git-репозитория и символических ссылок на другие каталоги.

Linux и macOS

mkdir -p "$HOME/claude-code-isolated-check"
cd "$HOME/claude-code-isolated-check"
pwd
find . -mindepth 1 -maxdepth 1 -print
git rev-parse --show-toplevel 2>/dev/null || echo "Внешний Git-репозиторий не найден"

PowerShell

$Project = Join-Path $HOME "claude-code-isolated-check"
New-Item -ItemType Directory -Force -Path $Project | Out-Null
Set-Location $Project
(Get-Location).Path
Get-ChildItem -Force
git rev-parse --show-toplevel 2>$null
if ($LASTEXITCODE -ne 0) {
  "Внешний Git-репозиторий не найден"
}

Вывод команды find или Get-ChildItem должен быть пустым до создания контрольных файлов. Если git rev-parse показывает родительский репозиторий, выберите другой каталог: иначе агент может считать его корнем проекта.

Откройте именно папку, а не отдельный файл:

code .

В заголовке окна и проводнике VS Code проверьте имя каталога. Для первой проверки не добавляйте в рабочую область вторую папку.

Шаг 2. Зафиксируйте VS Code и расширение

Получите версию VS Code из того же терминала, из которого открывали проект:

code --version

Первая строка обычно содержит версию приложения, следующие могут содержать идентификатор сборки и архитектуру. Сохраняйте вывод целиком: только номера версии иногда недостаточно для различения сборок.

Теперь выведите установленные расширения вместе с версиями:

code --list-extensions --show-versions

Найдите строку Claude Code по названию, затем сверьте её с карточкой расширения внутри VS Code:

1. откройте представление Extensions;
2. выберите установленное расширение Claude Code;
3. запишите точный идентификатор издателя и расширения;
4. запишите установленную версию;
5. убедитесь, что пакет включён для текущего профиля;
6. проверьте, не установлена ли одновременно другая похожая интеграция.

Не фильтруйте список только по слову claude и не считайте название достаточным доказательством происхождения. Для паспорта нужна полная строка вида:

<publisher>.<extension-id>@<installed-version>

Значения в угловых скобках нужно заменить фактическими данными. Не копируйте условную строку в отчёт как результат проверки.

Шаг 3. Найдите фактический CLI

Наблюдаемость начинается с ответа на простой вопрос: какой исполняемый файл действительно запущен. Имя команды само по себе этого не показывает.

Linux и macOS

command -v claude
type -a claude
claude --version

PowerShell

Get-Command claude -All | Format-List Name,CommandType,Source,Version
claude --version

Зафиксируйте абсолютный путь и полный вывод версии. Если найдено несколько команд, не удаляйте их наугад. Сначала установите, какая копия находится первой в PATH.

Повторите те же команды во встроенном терминале VS Code. Результаты внешнего и встроенного терминалов должны сравниваться буквально. Различие путей означает, что вы тестировали разные установки.

Дополнительно зафиксируйте оболочку:

printf '%s\n' "$SHELL"
printf '%s\n' "$PATH"

В PowerShell:

$PSVersionTable.PSVersion
$env:Path

Путь может содержать чувствительные имена локальных каталогов. Храните полный диагностический файл локально, а перед публикацией удаляйте пользовательские имена и нерелевантные сегменты.

Шаг 4. Создайте паспорт конфигурации до авторизации

Создайте в пустом проекте файл setup-record.txt. Он станет единственным ожидаемым изменяемым файлом на подготовительном этапе.

CLAUDE CODE / VS CODE — ПАСПОРТ ПЕРВОЙ НАСТРОЙКИ

Дата проверки:
Операционная система:
Архитектура:
Оболочка:

VS Code:
  версия:
  сборка:
  способ установки:

Расширение:
  точный идентификатор:
  установленная версия:
  профиль VS Code:
  состояние после перезапуска:

CLI:
  абсолютный путь:
  версия:
  способ установки:
  число найденных копий:

Авторизация:
  интерфейс входа:
  способ:
  учётная область без идентификаторов:
  секреты в отчёт не записывались: да / нет

Доступ:
  начальный режим:
  чтение контрольного файла:
  запись без подтверждения:
  запись после подтверждения:
  обращение за пределы проекта:
  запуск безвредной команды:

Диагностика:
  CLI:
  расширение:
  журналы VS Code:
  расхождения:

Итог:
  принято / не принято
  причина:

В поле «способ авторизации» укажите категорию, которую фактически использовали: например, интерактивный вход в браузере или переменная окружения с API-ключом. Не записывайте адрес аккаунта, ключ, токен сессии, cookie или код подтверждения.

Шаг 5. Проверьте авторизацию отдельно в каждом интерфейсе

Сначала выберите один способ авторизации для теста. Не настраивайте одновременно интерактивный вход и несколько переменных с ключами: при ошибке будет трудно понять, какой источник учётных данных сработал.

Проверка терминального интерфейса

Запустите CLI из пустого проекта:

claude

Если программа предлагает вход, завершите его только через интерфейс, открытый самим установленным CLI. После входа используйте доступную в вашей версии команду состояния или справку интерактивного интерфейса и запишите:

• подтверждён ли вход;
• какой общий тип учётной области показан;
• не отображаются ли секреты;
• какой режим разрешений активен;
• какой каталог считается текущим проектом.

Названия интерактивных команд могут меняться. Если ожидаемая команда состояния отсутствует, откройте встроенную справку и используйте команду, которую перечисляет установленная версия. Не подменяйте отсутствие команды результатом из другой версии документации.

Проверка расширения

Затем откройте панель Claude Code в VS Code. Не предполагайте, что она автоматически наследовала состояние CLI. Проверьте, показывает ли расширение собственное предложение войти, ошибку запуска или готовую сессию.

В паспорт запишите наблюдение без догадок:

CLI: вход подтверждён / вход не подтверждён / состояние не удалось определить
Расширение: вход подтверждён / вход не подтверждён / состояние не удалось определить
Основание: название экрана, команды или журнала без секретных данных

Если один интерфейс авторизован, а второй нет, это уже полезный результат диагностики. Не повторяйте вход много раз и не переустанавливайте всё сразу: сначала сохраните сообщение об ошибке и журнал конкретного компонента.

Шаг 6. Выберите консервативный режим доступа

Для первой сессии выбирайте режим, в котором агент либо только планирует, либо запрашивает подтверждение перед записью и выполнением команд. Точное название режима зависит от установленной версии, поэтому зафиксируйте формулировку, которую показывает ваш интерфейс.

Безопасная стартовая политика выглядит так:

• рабочая область ограничена одним пустым каталогом;
• чтение контрольных файлов разрешено;
• изменение файлов требует видимого подтверждения;
• команды терминала требуют подтверждения или ограничены узким списком;
• сетевые и внешние интеграции для теста не нужны;
• обход подтверждений не используется;
• доступ к домашнему каталогу не считается частью теста.

Если интерфейс предлагает режим обхода проверок, не включайте его для первичной диагностики. Такой режим смешивает две задачи: проверку работоспособности и выдачу широких прав.

Промпт «ничего не изменяй» полезен как указание намерения, но не является технической границей. Надёжность проверяется фактическим запросом подтверждения и состоянием файлов после действия.

Шаг 7. Подготовьте контрольные файлы

Создайте два безвредных файла. Первый агент должен прочитать. Второй не должен появиться без ожидаемого подтверждения.

Linux и macOS

printf '%s\n' 'READ_TOKEN=orange-bridge-27' > read-only-check.txt
printf '%s\n' 'Этот файл фиксирует ход проверки.' >> setup-record.txt
ls -la

PowerShell

'READ_TOKEN=orange-bridge-27' | Set-Content -Encoding utf8 read-only-check.txt
'Этот файл фиксирует ход проверки.' |
  Add-Content -Encoding utf8 setup-record.txt
Get-ChildItem -Force

Строка orange-bridge-27 — синтетический маркер, а не секрет или тестовый результат. Можно заменить её собственной случайной несекретной строкой. Не используйте реальный ключ, имя клиента или содержимое рабочего файла.

Зафиксируйте исходное состояние:

find . -maxdepth 1 -type f -print -exec sha256sum {} \;

На macOS, если sha256sum отсутствует:

find . -maxdepth 1 -type f -exec shasum -a 256 {} \;

В PowerShell:

Get-ChildItem -File | ForEach-Object {
  Get-FileHash -Algorithm SHA256 $_.FullName
}

Шаг 8. Выполните тест чтения

В интерфейсе Claude Code дайте узкое задание:

Работай только в текущем проекте.
Прочитай файл read-only-check.txt.
Верни точное значение после READ_TOKEN=.
Не изменяй файлы и не запускай команды, если они не нужны для чтения.

Успешным считается не просто осмысленный ответ. Проверьте три условия:

1. ответ содержит фактический контрольный маркер;
2. после задания не появились новые файлы;
3. хеши существующих файлов не изменились.

Повторите листинг и расчёт хешей теми же командами, что использовали до теста. В паспорт запишите наблюдаемый результат. Если агент вернул неправильную строку, не исправляйте её в отчёте: это отказ проверки чтения.

Тест следует провести отдельно в терминальном CLI и в расширении. Один и тот же проект и один запрос позволяют сравнить интерфейсы, но не доказывают, что их внутренние настройки идентичны.

Шаг 9. Проверьте запись без принятия изменения

Следующий тест выясняет, остановится ли агент перед изменением. Дайте задание:

Создай в текущем проекте файл write-check.txt
с единственной строкой WRITE_CONFIRMED.
Перед записью обязательно покажи требуемое действие и запроси подтверждение.

Ожидаемое поведение консервативного режима — видимый запрос подтверждения до появления файла. На первом проходе отклоните действие. Затем проверьте:

test ! -e write-check.txt && echo "После отказа файл отсутствует"

В PowerShell:

if (-not (Test-Path write-check.txt)) {
  "После отказа файл отсутствует"
}

Если файл появился до подтверждения или после отказа, не продолжайте к рабочему репозиторию. Зафиксируйте точный режим разрешений и источник сессии. Это проблема границы доступа, даже если содержимое файла безвредно.

На втором проходе повторите запрос и примите только создание указанного файла. После выполнения проверьте имя, содержимое и отсутствие дополнительных изменений:

test -f write-check.txt
wc -l write-check.txt
sed -n '1,3p' write-check.txt
find . -maxdepth 1 -type f -print

Файл должен содержать одну ожидаемую строку. Дополнительные файлы, изменения конфигурации или команды требуют отдельного объяснения в протоколе.

Шаг 10. Проверьте запуск безопасной команды

Попросите агента выполнить команду без побочных эффектов:

Покажи абсолютный путь текущего каталога командой,
которая ничего не изменяет. Перед запуском следуй
действующему режиму подтверждения.

Сравните полученный путь с результатом собственного pwd или (Get-Location).Path. Проверьте:

• было ли запрошено подтверждение, если режим его обещал;
• совпадает ли рабочий каталог;
• не была ли выполнена другая команда;
• не изменились ли файлы проекта.

Этот тест подтверждает только запуск одной безвредной команды в текущей сессии. Он не доказывает безопасность любых команд и не проверяет изоляцию операционной системы.

Шаг 11. Проверьте границу проекта

Не просите агента читать реальные данные за пределами каталога. Вместо этого проверьте, как он реагирует на намеренно запрещённое действие:

Не выполняй действие.
Объясни, потребуется ли отдельное разрешение,
чтобы обратиться к файлу за пределами текущего проекта.
Не называй и не читай никакие внешние файлы.

Такой запрос проверяет объяснение интерфейса, но не фактическую изоляцию. Для технической проверки используйте отдельный синтетический соседний каталог без чувствительных данных и попытку, которая должна быть остановлена до чтения.

Например, пользователь может заранее создать рядом отдельный файл-маркер, не содержащий секретов, а затем запросить чтение только при условии отдельного подтверждения. Если вы проводите такой тест, сохраните в паспорте:

• абсолютные пути обоих тестовых каталогов;
• состояние доверия VS Code;
• режим разрешений;
• появился ли запрос подтверждения;
• было ли действие отклонено;
• не произошло ли чтение до решения пользователя.

Шаг 12. Соберите диагностику CLI

Сначала используйте справку именно установленной версии:

claude --help

Проверьте, перечисляет ли она команду или режим диагностики. Если перечисляет, запустите его и сохраните обезличенный результат в паспорт. Не используйте имя диагностической команды из чужой версии без проверки в локальной справке.

Минимальный диагностический набор, не зависящий от внутреннего формата продукта:

command -v claude
type -a claude
claude --version
claude --help

На Windows:

Get-Command claude -All | Format-List Name,CommandType,Source,Version
claude --version
claude --help

Если CLI не запускается, зафиксируйте отдельно:

• точную команду;
• код возврата, если оболочка его показывает;
• полный текст ошибки без секретов;
• путь найденного бинарного файла;
• результат запуска во внешнем и встроенном терминале;
• происходит ли ошибка до авторизации или после неё.

Шаг 13. Соберите диагностику расширения

Ошибка расширения не обязана появляться в терминале. В VS Code последовательно проверьте:

1. карточку расширения и установленную версию;
2. панель Output и канал, относящийся к Claude Code;
3. панель Output для Extension Host, если собственный канал пуст;
4. команду разработчика для просмотра запущенных расширений;
5. консоль инструментов разработчика только при необходимости;
6. повтор после команды перезагрузки окна VS Code.

Записывайте время ошибки и действие, после которого она появилась. Строка «не работает» бесполезна; запись ниже уже позволяет локализовать слой:

Время:
Интерфейс: расширение VS Code
Действие: открытие новой сессии в пустом проекте
Версия расширения:
Версия VS Code:
Сообщение:
CLI в том же терминале: запускается / не запускается
Авторизация CLI: подтверждена / не определена
Авторизация расширения: подтверждена / не определена

Перед передачей журнала удалите токены, заголовки авторизации, локальные имена пользователей и содержимое файлов. Не удаляйте время, версию, название компонента и текст безопасного кода ошибки: именно они помогают установить источник.

Как интерпретировать расхождения

CLI не найден, расширение открывается

Это не противоречие. Расширение может иметь собственный способ запуска или окружение. Диагностируйте CLI как отдельную установку и не объявляйте расширение подтверждением исправного PATH.

CLI запускается во внешнем терминале, но не во встроенном

Сравните оболочку, PATH и способ запуска VS Code. Перезапуск окна после изменения среды может быть необходим, но сначала сохраните исходное расхождение.

Версии в терминалах различаются

Найдены разные копии CLI или разные среды. Выберите одну установку осознанно, исправьте порядок поиска и повторите весь протокол.

CLI авторизован, расширение просит вход

Не считайте это повреждением аккаунта. Сначала установите, должны ли эти компоненты совместно использовать авторизацию в вашей фактической конфигурации.

Расширение работает, CLI сообщает об ошибке авторизации

Проверяйте учётные данные CLI, а не переустанавливайте расширение. Успешная сессия панели не доказывает состояние терминального процесса.

Агент читает файл, но не может записать

Это может быть ожидаемым результатом выбранного режима. Посмотрите, был ли показан запрос подтверждения и что именно было отклонено.

Файл изменён без подтверждения

Текущая конфигурация не соответствует безопасному стартовому режиму. Не открывайте рабочий проект, пока не будет понятен источник разрешения.

После подтверждения создано больше одного файла

Проверьте дифф и журнал инструментов. Подтверждение одного действия не должно автоматически считаться согласием на произвольный набор изменений.

После обновления проблема исчезла

Это полезное наблюдение, но без старой и новой версий оно не воспроизводимо. Запишите обе версии и повторите контрольные тесты.

Проверка итоговой конфигурации

Конфигурацию можно принять только после повторного запуска VS Code. Перезагрузите окно, откройте тот же пустой каталог и повторно получите:

code --version
code --list-extensions --show-versions
command -v claude
claude --version

Для PowerShell замените command -v claude на:

(Get-Command claude).Source

Затем выполните короткий контрольный цикл:

1. прочитайте read-only-check.txt через выбранный основной интерфейс;
2. проверьте отсутствие неожиданных изменений;
3. запросите изменение write-check.txt;
4. убедитесь, что решение пользователя требуется в ожидаемой точке;
5. сравните рабочий каталог с локальной командой;
6. сохраните итоговые версии и состояние авторизации;
7. пометьте каждый тест как «пройден», «не пройден» или «не проверен».

Не заменяйте «не проверен» на «пройден». Например, отказ от теста доступа за границу проекта может быть разумным решением, но итоговый паспорт должен честно отражать ограничение.

Минимальный критерий приёмки

Настройка готова к осторожному переносу в рабочий проект, если одновременно выполнены условия:

• установленное расширение однозначно определено по идентификатору и версии;
• CLI однозначно определён по абсолютному пути и версии;
• внешний и встроенный терминалы запускают ожидаемую копию;
• способ авторизации записан без секретов;
• состояние входа проверено отдельно для используемых интерфейсов;
• режим разрешений записан точной формулировкой интерфейса;
• контрольный файл успешно прочитан;
• после отклонённой записи файл не появился;
• после явного подтверждения создан только ожидаемый файл;
• безвредная команда выполнялась в правильном каталоге;
• после перезапуска версии и поведение не изменились;
• в журналах нет необъяснённой ошибки текущей сессии.

В итоговой строке паспорта удобно использовать решение:

ПРИНЯТО:
версии зафиксированы;
CLI однозначен;
авторизация определена;
запись требует подтверждения;
контрольные тесты пройдены.

или

НЕ ПРИНЯТО:
не определён источник CLI;
расширение и терминал расходятся;
файл изменён до подтверждения;
требуется отдельная диагностика.

Перенос в рабочий репозиторий

После успешной проверки не переносите тестовые файлы в рабочий код автоматически. Откройте репозиторий отдельным окном VS Code и начните с режима не шире проверенного.

Перед первой задачей:

• проверьте корень Git-репозитория;
• посмотрите git status до запуска агента;
• уберите из рабочей области лишние каталоги;
• не держите секреты в открытых вкладках и незашифрованных файлах;
• попросите агента сначала описать план;
• просматривайте каждый дифф перед принятием;
• не расширяйте права только ради устранения первой ошибки.

Prompt injection — вредоносная или конфликтующая инструкция внутри читаемого агентом содержимого. Пустой проект проверяет установку и разрешения, но не защищает рабочий репозиторий от инструкций в документации, задачах, веб-страницах или результатах инструментов.

Перед переносом сохраните копию паспорта вне репозитория или удалите из него абсолютные локальные пути. Сам файл диагностики не должен случайно попасть в публикацию.

Типичные неудачные подходы

«Переустановить всё сразу»

После массовой переустановки невозможно понять, какой компонент был причиной. Меняйте по одному слою и повторяйте одинаковый тест.

«Если чат отвечает, значит настройка готова»

Ответ подтверждает только часть цепочки. Он не фиксирует путь CLI, версию расширения и право на запись.

«Расширение и CLI имеют одно имя, значит это одна установка»

Имя продукта не доказывает общий бинарный файл, общий процесс или общую сессию авторизации.

«Сразу дать полный доступ, чтобы исключить разрешения»

Такой тест устраняет защитную границу и смешивает диагностику с риском. Сначала проверьте чтение и подтверждаемую запись.

«Проверить на настоящем репозитории»

Неожиданная запись, команда или чтение секрета становятся реальным инцидентом. Синтетический проект даёт тот же диагностический сигнал безопаснее.

«Скопировать номер версии из инструкции»

Паспорт должен описывать ваш компьютер. Получайте версию командой и карточкой установленного расширения.

«Приложить весь журнал к задаче»

Журналы могут содержать пути, запросы и учётные данные. Перед передачей оставьте только минимальный фрагмент, необходимый для воспроизведения.

Ограничения проверки

• Пустой проект не моделирует рабочий репозиторий полностью. В реальном коде появятся Git, конфигурации, хуки, зависимости и недоверенное содержимое.
• Подтверждение в одном тесте не доказывает поведение всех инструментов. Чтение, запись, команды, сеть и внешние интеграции могут иметь разные политики.
• Интерфейсы и команды меняются. Локальная справка и установленная версия имеют приоритет над запомнившимся названием пункта меню.
• Паспорт фиксирует момент времени. После обновления VS Code, расширения, CLI или изменения авторизации тест нужно повторить.
• Ограничение рабочей папкой не равно системной песочнице. Фактическая изоляция зависит от продукта, режима и операционной системы.
• Тест не проверяет безопасность облачной учётной записи. Политики организации, лимиты, биллинг и управление ключами требуют отдельного аудита.
• Отсутствие ошибки в интерфейсе не доказывает отсутствие ошибки в журнале. Для спорного случая сохраняйте время и проверяйте канал конкретного компонента.

Итог

Безопасная первая настройка Claude Code — это не один успешный вход. Это короткий воспроизводимый эксперимент, в котором расширение, CLI, авторизация и разрешения рассматриваются отдельно.

Главный артефакт проверки — заполненный паспорт: фактические версии, абсолютный путь CLI, способ входа, выбранный режим и наблюдаемые результаты контрольных действий. С ним ошибку можно локализовать, а конфигурацию — повторить после обновления или на другом компьютере, не полагаясь на память и предположения.

Что изучить дальше

Другие воспроизводимые схемы настройки и контроля агентов собраны в разделе «Руководства». Определения AI-агента, allowlist, tool calling, approval gate, промпта и наблюдаемости доступны в глоссарии Agent Lab Journal.