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

## Ключ настроен, а запросы всё равно падают? Проверьте по порядку

Остальная часть страницы построена по кодам ошибок; если вы **уже вписали ключ и адреса ровно по документации, а запросы всё равно не проходят**, пройдите этот чек-лист (curl-самопроверка и чтение HTTP-кодов — раздел 5 в [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths)):

1. **Сначала один curl-тест.** `401` = проблема с ключом; `404` = неверный префикс пути; `400` с `model_not_available_on_endpoint` = перепутан протокол (не ключ — см. пункт 4); соединение не устанавливается = сеть/прокси (пункт 6).
2. **Переменная не на своём месте.** `ANTHROPIC_AUTH_TOKEN` уходит заголовком `Authorization: Bearer`, `ANTHROPIC_API_KEY` — заголовком `x-api-key`; перепутали — и шлюз не увидит корректных учётных данных. **Старые переменные в окружении перекрывают текущие настройки**: выполните `env | grep -i anthropic` и `env | grep -i openai` и уберите лишнее.
3. **Форма Base URL.** Семейство Claude Code: `https://api.qcode.cc/api` (**без `/v1`**); OpenAI SDK и совместимые клиенты: `https://api.qcode.cc/openai/v1`; Codex CLI в конфиг-файле: `https://api.qcode.cc/openai` плюс `wire_api = "responses"`. Один лишний или недостающий сегмент — и будет 404.
4. **Несовпадение протокола и модели.** Если послать модель Claude на эндпоинт OpenAI, ещё до аутентификации придёт `model_not_available_on_endpoint` — поменяйте эндпоинт или модель по матрице из раздела 2 страницы [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths).
5. **Регрессии версии клиента (Claude Code):**
   - **2.1.265–2.1.267**: каждый запрос даёт 400 (отвергается схема инструмента Artifact) — обновитесь до **≥2.1.268** или поставьте `CLAUDE_CODE_DISABLE_ARTIFACT=1`.
   - **2.1.275**: при `ANTHROPIC_BASE_URL` на шлюз каждый запрос падает с `400 … Input tag 'advisor_20260301'` — обновитесь до **≥2.1.276**.
   - Ошибки `Unexpected value(s) … anthropic-beta` — поставьте `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.
6. **Системный прокси против домена доступа.** `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` меняют маршрут; добавьте `*.qcode.cc` в `NO_PROXY` или временно отмените эти переменные.
7. **Не помогло**: посмотрите запрос на [probe.qcode.cc](https://probe.qcode.cc) по ключу — как выглядел реальный запрос и что вернулось — и **обратитесь в поддержку с request id** (онлайн-чат или hi@qcode.cc).

Значения кодов — в [Справочнике ошибок](/docs/reference/errors); вопросы вида «можно ли подписку использовать как API» — в статье [Подписка, официальный API и ключ QCode](/docs/reference/subscription-vs-api-key).

Не паникуйте, если при использовании Claude Code возникли проблемы. Данное руководство организовано по принципу «Быстрая самопроверка → Пошаговая диагностика → Решение», что поможет вам эффективно найти и устранить проблему.

## Быстрая самопроверка

При возникновении проблемы сначала выполните три быстрых шага проверки — 80% проблем можно выявить на этом этапе.

### 1. Проверьте версию Claude Code

```bash
claude --version
```

Убедитесь, что используете последнюю версию. Claude Code обновляется очень часто, многие проблемы уже исправлены в новых версиях.

**Обновление до последней версии:**

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

### 2. Запустите автоматическую диагностику

```bash
claude /doctor
```

Команда `/doctor` автоматически проверяет:
- Соответствует ли версия Node.js требованиям (≥ 18)
- Действительность API Key
- Нормальное сетевое подключение
- Наличие синтаксических ошибок в конфигурационных файлах

### 3. Подтвердите версию Node.js

Claude Code требует Node.js версии 18 или выше:

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

Если версия слишком низкая, выполните обновление:

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

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

## Проблемы с установкой

### Ошибка прав доступа npm install

**Симптомы:**

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

**Решение 1: Использование sudo (быстро, но не рекомендуется для постоянного использования)**

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

**Решение 2: Изменение глобальной директории npm (рекомендуется)**

```bash
# Создание пользовательской директории для глобальных пакетов
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
```

**Решение 3: Использование nvm для управления Node.js**

```bash
# Установка 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
```

### Сбой установки из-за проблем с сетью

**Симптомы:**

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

**Решение: Использование китайского зеркала**

```bash
# Временное использование зеркала 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
```

Если вы используете прокси:

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

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

### Политика выполнения PowerShell в Windows

**Симптомы:**

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

**Решение:**

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

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

Или используйте CMD вместо PowerShell:

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

## Проблемы с подключением

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

### Неправильный формат API Key

**Формат API Key для QCode.cc:**

```text
cr_xxxxxxxxxxxxxxxx
```

Обратите внимание: префикс `cr_`, а не `sk-ant-` как у официального Anthropic.

**Проверка конфигурации API Key:**

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

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

**Распространённые ошибки:**

| Ошибка | Описание |
|--------|----------|
| Пробелы в начале или конце ключа | `cr_ xxx` → `cr_xxx` |
| Использован официальный формат ключа | `sk-ant-xxx` — это официальный ключ Anthropic, а не ключ QCode.cc |
| Ключ обрезан | Проверьте, полностью ли скопирован ключ |
| Использован просроченный ключ | Подтвердите статус ключа в QCode.cc Dashboard |

### Неправильная конфигурация ANTHROPIC_BASE_URL

При использовании сервиса QCode.cc необходимо правильно настроить Base URL:

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

**Шаги диагностики:**

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

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

# Верно: ветке Anthropic нужен префикс /api, но без сегмента пути запроса
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"

# Неверно: без https / лишний завершающий слэш / расписан путь целиком
export ANTHROPIC_BASE_URL="http://api.qcode.cc/api"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api/"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api/v1/messages"
```

### Сбой подключения из-за прокси/VPN

**Симптомы:**

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

**Шаги диагностики:**

```bash
# 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
```

**Примечания о VPN:**

- Убедитесь, что VPN не блокирует API-запросы
- Некоторые правила разделения трафика в VPN могут влиять на подключение к API
- Если VPN вызывает проблемы, попробуйте добавить домен API в правила прямого подключения

### Проблемы с SSL/TLS сертификатами

**Симптомы:**

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

**Решения:**

```bash
# Вариант 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
```

### Тестирование подключения

Тестирование подключения к API напрямую с помощью curl:

```bash
# Тест базового подключения
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-5",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

**Ожидаемые результаты:**
- Проверка состояния возвращает `200`
- API-вызов возвращает JSON-ответ

**Таблица распространённых проблем:**

| Результат curl | Возможная причина | Решение |
|----------------|-------------------|---------|
| `connection refused` | Неправильный адрес сервиса или сервис не запущен | Проверьте ANTHROPIC_BASE_URL |
| `connection timeout` | Сеть недоступна или заблокирована файрволом | Проверьте настройки сети/прокси |
| `401 Unauthorized` | Недействительный API Key | Проверьте правильность ключа |
| `403 Forbidden` | У ключа нет прав | Свяжитесь с поставщиком услуг |
| SSL-ошибки | Проблемы с сертификатом | См. раздел SSL выше |

## Проблемы с правами доступа

### Недостаточно прав на чтение/запись файлов

**Симптомы:**

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

**Решение:**

```bash
# 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 Code:**

Claude Code имеет систему разрешений для контроля над тем, какие операции он может выполнять. Если вы обнаружили, что Claude заблокирован при попытке выполнить какое-либо действие:

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

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

### Отказ в операциях Git

**Симптомы:**

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

**Решение:**

```bash
# 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                      # Подтверждение нахождения в директории репозитория
```

### Сбой выполнения Bash-команд

При выполнении bash-команд Claude Code может запрашивать подтверждение. Если команда постоянно отклоняется:

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

# Если это проект, которому вы доверяете, можно настроить разрешённые команды в CLAUDE.md
# CLAUDE.md
## Разрешённые команды
allowedTools:
  - Bash(npm run *)
  - Bash(pnpm *)
  - Bash(git *)
  - Bash(docker compose *)
```

## Проблемы с производительностью

### Медленная скорость ответа

**Возможные причины и решения:**

| Причина | Метод диагностики | Решение |
|---------|-------------------|---------|
| Сетевая задержка | `ping адрес_сервиса` | Проверьте сеть/прокси |
| Используется модель Opus | `/model` для просмотра | Переключитесь на Sonnet |
| Слишком большой контекст | `/cost` для просмотра количества токенов | `/compact` для сжатия |
| Высокая нагрузка на сервере | Проверка времени ответа HTTP | Попробуйте позже |

**Советы по оптимизации сети (для пользователей из Китая):**

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

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

### Переполнение контекста

**Симптомы:**
- Ответы Claude начинают «забывать» то, что было сказано ранее
- Качество ответов заметно снижается
- Появляется повторяющийся или противоречивый контент

**Решения:**

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

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

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

**Профилактические меры:**

- После завершения каждой независимой задачи используйте `/compact`
- При смене темы без колебаний используйте `/clear`
- Используйте `.claudeignore` для исключения нерелевантных больших файлов
- Используйте `@` для точной ссылки на нужные файлы, не позволяйте Claude выполнять глобальный поиск

### Слишком высокое потребление памяти

**Симптомы:**
- Система начинает тормозить
- Процесс Claude Code занимает много памяти

**Решения:**

```bash
# 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
```

## Таблица распространённых кодов ошибок

| Код ошибки | Значение | Причина | Решение |
|------------|----------|---------|---------|
| **400** | Bad Request | Неправильный формат запроса | Проверьте наличие недопустимых символов; обновите Claude Code до последней версии |
| **401** | Unauthorized | API Key недействителен или просрочен | Проверьте настройку `ANTHROPIC_AUTH_TOKEN`; подтвердите, что ключ не просрочен |
| **403** | Forbidden | Нет прав доступа | Подтвердите, что у ключа есть права доступа к соответствующей модели |
| **404** | Not Found | Модель или путь не существуют | Проверьте правильность `ANTHROPIC_BASE_URL` и названия модели |
| **429** | Too Many Requests | Слишком частые запросы | Подождите 30-60 секунд и повторите; уменьшите количество параллельных запросов |
| **500** | Internal Server Error | Внутренняя ошибка сервера | Попробуйте позже; при повторении свяжитесь со службой поддержки |
| **502** | Bad Gateway | Вышестоящий сервис недоступен | Попробуйте позже; проверьте объявления о сервисе |
| **503** | Service Unavailable | Сервис временно перегружен | Подождите несколько минут и повторите |
| **529** | API Overloaded | Перегрузка Claude API | Это означает высокую нагрузку на сервис Anthropic; подождите и повторите |

### Подробнее о 429: Ограничение скорости

429 — наиболее часто встречающаяся ошибка, заслуживающая детального рассмотрения:

**Причины возникновения:**

1. **Слишком высокая частота запросов**: отправляется слишком много запросов в секунду
2. **Слишком быстрое потребление токенов**: за короткое время израсходовано много токенов
3. **Слишком много параллельных сессий**: одновременно открыто несколько экземпляров Claude Code
4. **Исчерпана квота аккаунта**: дневная/месячная квота исчерпана

**Поэтапная обработка:**

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

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

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

### Подробнее о 529: Перегрузка API

529 — это особый код ошибки Anthropic, означающий перегрузку сервиса Claude API:

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

**Меры по устранению:**

- Это не ваша проблема, а временная ситуация на стороне сервиса Anthropic
- Обычно длится от нескольких минут до получаса
- Подождите 1-2 минуты и повторите
- Если проблема повторяется, можно временно переключиться на другую модель (например, серию GPT)
- Следите за [Anthropic Status](https://status.anthropic.com/) для получения информации о состоянии сервиса

## Другие распространённые вопросы

### Claude Code не реагирует после запуска

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

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

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

### CLAUDE.md не работает

```bash
# 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 для применения настроек
# Выйдите и войдите снова
```

### Искаженные символы китайского языка

```bash
# 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
```

### Конфликты Git приводят к сбою операций Claude

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

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

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

### Проблемы с Docker (для опытных пользователей)

Если вы используете Claude Code в контейнере Docker:

```bash
# Убедитесь, что в контейнере есть 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
```

## Сводка процесса диагностики

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

```text
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. Если ничего не помогло → Получение помощи
```

## Получение помощи

Если ни один из вышеуказанных методов не решил вашу проблему, вы можете получить помощь через следующие каналы:

### Онлайн-поддержка QCode.cc

Нажмите на иконку онлайн-поддержки в правом нижнем углу сайта [QCode.cc](https://qcode.cc), в рабочее время обычно можно получить ответ в течение нескольких минут.

**При обращении предоставьте:**
- Версию Claude Code (вывод команды `claude --version`)
- Операционную систему и её версию
- Полное сообщение об ошибке
- Решения, которые вы уже пробовали

### GitHub Issues

Claude Code — это проект с открытым исходным кодом, вы можете отправить issue на GitHub:

- **Адрес репозитория**: [github.com/anthropics/claude-code](https://github.com/anthropics/claude-code)
- Поищите существующие issues, возможно, кто-то уже сталкивался с подобной проблемой
- При создании нового issue опишите проблему на английском языке (так вы быстрее получите официальный ответ)

### Ресурсы сообщества

- **Официальная документация Claude Code**: [docs.anthropic.com](https://docs.anthropic.com)
- **Статус сервиса Anthropic**: [status.anthropic.com](https://status.anthropic.com)
- **Документация для пользователей QCode.cc**: [docs.qcode.cc](https://docs.qcode.cc)

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