Руководство по поиску и устранению неисправностей

claude --version

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

claude /doctor

node --version
# Должно вывести v18.x.x или выше

# Использование nvm для управления версиями Node.js (рекомендуется)
nvm install 22
nvm use 22

# Или просто скачайте и установите
# Перейдите на https://nodejs.org/ для загрузки LTS-версии

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

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

# Создание пользовательской директории для глобальных пакетов
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Добавление в PATH (запись в ~/.bashrc или ~/.zshrc)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Повторная установка
npm install -g @anthropic-ai/claude-code

# Установка nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc

# Установка и использование Node.js
nvm install 22
nvm use 22

# Node.js, установленный через nvm, не требует sudo
npm install -g @anthropic-ai/claude-code

npm ERR! network request to https://registry.npmjs.org/ failed
npm ERR! code ETIMEDOUT

# Временное использование зеркала Taobao
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# Или постоянная настройка зеркала
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

# Настройка прокси для npm
npm config set proxy http://ваш_прокси:порт
npm config set https-proxy http://ваш_прокси:порт

# После установки можно отменить настройки прокси
npm config delete proxy
npm config delete https-proxy

claude : File C:\Users\xxx\AppData\Roaming\npm\claude.ps1 cannot be loaded
because running scripts is disabled on this system.

# Откройте PowerShell от имени администратора и выполните:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Затем снова запустите claude
claude

# Запуск напрямую в CMD
claude

cr_xxxxxxxxxxxxxxxx

# Просмотр текущих переменных окружения
echo $ANTHROPIC_AUTH_TOKEN

# Правильная настройка (ключ QCode.cc)
export ANTHROPIC_AUTH_TOKEN="cr_ваш_ключ"

# Base URL для QCode.cc
export ANTHROPIC_BASE_URL="https://ваш_адрес_сервиса"

# 1. Проверка текущей конфигурации
echo $ANTHROPIC_BASE_URL

# 2. Подтверждение правильности формата URL
#    - Должен начинаться с https://
#    - В конце не должно быть слэша /
#    - Не должен содержать путь (например, /v1/messages)

# Правильный пример
export ANTHROPIC_BASE_URL="https://api.example.com"

# Неправильные примеры
export ANTHROPIC_BASE_URL="http://api.example.com"      # отсутствует https
export ANTHROPIC_BASE_URL="https://api.example.com/"     # лишний слэш
export ANTHROPIC_BASE_URL="https://api.example.com/v1"   # лишний путь

Error: connect ETIMEDOUT
Error: getaddrinfo ENOTFOUND api.example.com

# 1. Проверка правильности настроек прокси
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY

# 2. Тестирование сетевого подключения
curl -v https://ваш_адрес_сервиса/health

# 3. Если используется прокси, убедитесь, что Claude Code может его использовать
export HTTP_PROXY="http://адрес_прокси:порт"
export HTTPS_PROXY="http://адрес_прокси:порт"

# 4. Если прокси не нужен, но он настроен, отмените настройки
unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY

Error: unable to verify the first certificate
Error: self signed certificate in certificate chain

# Вариант 1: Обновление системных CA-сертификатов
# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates

# macOS
brew install ca-certificates

# Вариант 2: Если это промежуточные сертификаты корпоративной сети, настройте Node.js на их доверие
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.crt"

# Вариант 3: Временный пропуск проверки сертификатов (только для тестирования, не рекомендуется для постоянного использования)
export NODE_TLS_REJECT_UNAUTHORIZED=0

# Тест базового подключения
curl -s -o /dev/null -w "%{http_code}" \
  https://ваш_адрес_сервиса/health

# Тест API-вызова (замените на ваш ключ и адрес)
curl https://ваш_адрес_сервиса/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_ваш_ключ" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Error: EACCES: permission denied, open '/path/to/file'

# 1. Проверка прав на файл
ls -la /path/to/file

# 2. Убедитесь, что у текущего пользователя есть права на чтение и запись
chmod u+rw /path/to/file

# 3. Проверьте права на директорию (при создании новых файлов Claude требуются права на запись в директорию)
chmod u+w /path/to/directory

# 4. Если файл создан root'ом, измените владельца
sudo chown $(whoami) /path/to/file

# Просмотр текущих настроек разрешений
claude /permissions

# Настройка разрешённых директорий в settings.json
# ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Read files in /home/user/projects/**",
      "Write files in /home/user/projects/**",
      "Execute bash commands"
    ]
  }
}

fatal: unable to access 'https://github.com/xxx/xxx.git/':
The requested URL returned error: 403

# 1. Проверка конфигурации Git
git config --list

# 2. Подтверждение настройки SSH-ключей или Token
ssh -T git@github.com          # Тестирование SSH-подключения
gh auth status                  # Тестирование аутентификации GitHub CLI

# 3. Если используется HTTPS, проверка учетных данных
git config credential.helper    # Просмотр способа управления учетными данными

# 4. Убедитесь, что Claude Code находится в правильном Git-репозитории
git status                      # Подтверждение нахождения в директории репозитория

# Просмотр конфигурации разрешений
claude /permissions

# Если это проект, которому вы доверяете, можно настроить разрешённые команды в CLAUDE.md
# CLAUDE.md
## Разрешённые команды
allowedTools:

  - Bash(npm run *)
  - Bash(pnpm *)
  - Bash(git *)
  - Bash(docker compose *)

# Тестирование задержки до сервера
ping адрес_сервиса

# Если задержка превышает 500ms, рассмотрите следующее:
# 1. Проверьте оптимальность настроек прокси
# 2. Попробуйте использовать в разное время (избегайте пиковых нагрузок)
# 3. Свяжитесь со службой поддержки QCode.cc для получения оптимального узла

# Вариант 1: Сжатие контекста (с сохранением ключевой информации)
/compact

# Вариант 2: Полная очистка (если можно начать с нуля)
/clear

# Вариант 3: Оптимизация каждого ввода
# Не отправляйте всё содержимое файлов сразу
# Используйте @ для ссылки вместо вставки
# Выполняйте только одну задачу за раз

# 1. Проверка использования памяти Node.js
node -e "console.log(process.memoryUsage())"

# 2. Обновление Node.js до последней LTS-версии
nvm install 22
nvm use 22

# 3. Если проблема сохраняется, ограничьте максимальный объём памяти Node.js
export NODE_OPTIONS="--max-old-space-size=4096"

# 4. Перезапуск Claude Code
# Выйдите из текущей сессии и перезапустите
exit
claude

# Ошибка 429 возникает изредка
# → Подождите 30 секунд для автоматического повтора, Claude Code имеет встроенную логику повтора

# Ошибка 429 возникает часто
# → Уменьшите частоту запросов
# → Используйте /compact для уменьшения размера контекста
# → Избегайте одновременного запуска нескольких экземпляров Claude Code

# Постоянная ошибка 429
# → Проверьте, не исчерпана ли квота тарифного плана
# → Войдите в QCode.cc Dashboard для просмотра использования
# → Рассмотрите возможность перехода на более высокий тарифный план

Error: 529 API Overloaded
The API is temporarily overloaded. Please try again later.

# 1. Проверка правильности установки
which claude
npm list -g @anthropic-ai/claude-code

# 2. Просмотр подробной информации об ошибке
claude --debug

# 3. Попробуйте очистить кэш и перезапустить
rm -rf ~/.claude/cache
claude

# 1. Подтверждение правильного расположения файла
ls -la CLAUDE.md                # Корневая директория проекта
ls -la .claude/CLAUDE.md        # Приватная конфигурация проекта
ls -la ~/.claude/CLAUDE.md      # Глобальная конфигурация

# 2. Подтверждение кодировки UTF-8
file CLAUDE.md
# Должно отобразиться: CLAUDE.md: UTF-8 Unicode text

# 3. Подтверждение отсутствия синтаксических ошибок (хотя это Markdown, некоторые специальные символы могут вызвать проблемы с парсингом)
# Избегайте использования специальных маркеров, кроме ``` в CLAUDE.md

# 4. Перезапуск Claude Code для применения настроек
# Выйдите и войдите снова

# 1. Проверка настроек кодировки терминала
echo $LANG
# Должно содержать UTF-8, например en_US.UTF-8 или zh_CN.UTF-8

# 2. Установка правильной кодировки
export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8

# 3. Подтверждение поддержки UTF-8 терминалом
# macOS Terminal / iTerm2 поддерживают по умолчанию
# Windows Terminal поддерживает по умолчанию
# Windows CMD требует выполнения: chcp 65001

# 1. Сначала решите конфликты Git
git status     # Просмотр конфликтующих файлов
git diff       # Просмотр содержимого конфликтов

# 2. Позвольте Claude помочь решить конфликты
> "Просмотрите текущие конфликтующие файлы git и помогите мне их решить. Сохраните изменения с обеих сторон."

# 3. После решения продолжите
git add .
git commit -m "resolve merge conflicts"

# Убедитесь, что в контейнере есть Node.js 22+
docker run -it node:22-slim bash

# Установка Claude Code
npm install -g @anthropic-ai/claude-code

# Передача необходимых переменных окружения
docker run -it \
  -e ANTHROPIC_AUTH_TOKEN="cr_ваш_ключ" \
  -e ANTHROPIC_BASE_URL="https://ваш_адрес_сервиса" \
  -v $(pwd):/workspace \
  -w /workspace \
  node:22-slim claude

1. Быстрая самопроверка
   ├── claude --version (версия актуальна)
   ├── claude /doctor (автоматическая диагностика)
   └── node --version (Node.js ≥ 18)

2. Сетевое подключение
   ├── curl тестирование адреса API
   ├── проверка настроек прокси/VPN
   └── проверка DNS-разрешения

3. Конфигурация аутентификации
   ├── Правильность формата ANTHROPIC_AUTH_TOKEN
   ├── Правильность ANTHROPIC_BASE_URL
   └── Срок действия ключа

4. Проверка прав доступа
   ├── Права файловой системы
   ├── Права Git
   └── Конфигурация разрешений Claude Code

5. Оптимизация производительности
   ├── /compact сжатие контекста
   ├── /model переключение на подходящую модель
   └── .claudeignore исключение больших файлов

6. Если ничего не помогло → Получение помощи