Przewodnik Rozwiązywania Problemów

Twój agent AI właśnie zatrzymał się w połowie zadania, wyrzucił błąd, którego nigdy nie widziałeś, lub zaczął generować kod, który nie ma nic wspólnego z twoim projektem. Zanim otworzysz issue na GitHub, przejrzyj tę stronę. Większość problemów ma szybkie rozwiązanie.

Problemy z Cursor

Instalacja i Konfiguracja

Cursor nie uruchamia się po instalacji

Zweryfikuj wymagania systemowe: macOS 10.15+, Windows 10+ lub 64-bitowy Linux. Co najmniej 4GB RAM (zalecane 8GB), 2GB wolnego miejsca na dysku.
Wypróbuj tryb bezpieczny:
Okno terminala
```
cursor --disable-extensions
```
Zresetuj dane użytkownika (najpierw zrób backup):
- macOS: ~/Library/Application Support/Cursor
- Windows: %APPDATA%\Cursor
- Linux: ~/.config/Cursor
Sprawdź konflikty: Oprogramowanie antywirusowe, proxy korporacyjne i reguły firewall mogą blokować dostęp sieciowy Cursor.

Nie można zaimportować ustawień VS Code

Zamknij VS Code całkowicie przed importowaniem. Jeśli automatyczny import nie działa:

W VS Code: File > Preferences > Profiles > Export
W Cursor: File > Preferences > Profiles > Import
Rozszerzenia, motywy, keybindings i ustawienia wszystkie się przenoszą

Problemy z Funkcjami AI

Autouzupełnianie Tab nie działa

Sprawdź	Działanie
Limity planu	Darmowy tier: 2,000/miesiąc. Sprawdź Settings > Subscription > Usage
Status indeksowania	Settings > Features > Codebase Indexing. Kliknij “Reindex”, jeśli nieaktualny
Status modelu	Odwiedź status.cursor.sh dla raportów awarii
Typ pliku	Niektóre typy plików mają ograniczone wsparcie. Testuj w pliku `.js` lub `.py`
Rozszerzenia	Wyłącz konkurencyjne rozszerzenia completion (Copilot, Tabnine)

Tryb Agent nie może modyfikować plików

Zweryfikuj tryb: Selektor trybu powinien pokazywać “Agent” (ikona ołówka), nie “Ask”
Uprawnienia plików: ls -la filename — upewnij się, że masz dostęp do zapisu
Blokady Git: Usuń nieaktualne blokady przez rm .git/index.lock
Flaga tylko do odczytu: Niektóre edytory lub ustawienia OS oznaczają pliki jako read-only

Usuń pliki oznaczone @, których nie potrzebujesz ściśle
Użyj zakresów linii: @large-file.ts:100-200 zamiast całego pliku
Rozpocznij nowy czat z /clear kontekstem

Włącz tryb Max dla pełnego 200K context window (kosztuje więcej na żądanie)
Użyj Cmd/Ctrl+M, aby przełączać między strategiami czytania pełnego pliku i outline
Dołącz konkretne symbole (@UserClass) zamiast całych plików

”Rate limit exceeded” — wyczerpano szybkie żądania

Twoja miesięczna quota szybkich żądań została wyczerpana. Opcje:

Poczekaj: Wolne żądania są nieograniczone, ale opóźnione
Upgrade: Pro+ ($60/miesiąc) lub Ultra ($200/miesiąc) dla większej ilości
Użyj własnego klucza API: Settings > Models > API Keys (płatność za użycie, bez limitów)
Sprawdź użycie: Settings > Subscription > Usage dla dokładnych liczb

Problemy z Wydajnością

Cursor działa wolno

Wyłącz nieużywane rozszerzenia (View > Extensions)
Dodaj plik .cursorignore:
```
node_modules/
dist/
.git/
*.log
coverage/
```
Wyczyść cache: Cmd/Ctrl+Shift+P > “Clear Editor History”
Zamknij nieużywane zakładki i okna
Zrestartuj Cursor

Wysokie zużycie pamięci

Duże codebase powodują napęcznienie indeksu. Łagodzenie:

Wyklucz duże katalogi w .cursorignore
Podziel workspace monorepo na mniejsze okna Cursor
Zamykaj zakładki edytora, których aktywnie nie używasz
Wyłącz funkcje, których nie używasz (np. wyszukiwanie semantyczne dla ogromnych repozytoriów)

Problemy z Claude Code

Problemy z Instalacją

”Command not found: claude”

npm
Problemy z PATH

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code
npm list -g @anthropic-ai/claude-code   # weryfikuj

# Dodaj npm global bin do PATH
export PATH="$PATH:$(npm config get prefix)/bin"

# Uczyń trwałym
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc
source ~/.zshrc

Windows: Błąd “Git not found”

Claude Code wymaga Git dla Windows:

Pobierz z git-scm.com
Zainstaluj z zaznaczoną opcją “Add to PATH”
Zrestartuj terminal
Weryfikuj: git --version

Problemy z Uwierzytelnieniem

Klucz API nie działa

Klucz powinien zaczynać się od sk-ant- (bez dodatkowych spacji lub cudzysłowów)
Zweryfikuj, że klucz jest aktywny na console.anthropic.com
Ustaw go poprawnie:
Okno terminala
```
export ANTHROPIC_API_KEY="sk-ant-..."
```
Testuj: claude "hello" — powinieneś otrzymać odpowiedź
Jeśli używasz SSO: Użyj /login w REPL Claude Code, aby ponownie się uwierzytelnić

Limity Użycia

”Rate limit reached” po kilku wiadomościach

Zrozumienie limitów:

Plan	Wiadomości na 5-godzinne okno
Pro ($20/miesiąc)	~10-40
Max 5x ($100/miesiąc)	~50-200
Max 20x ($200/miesiąc)	~200-800

Strategie łagodzenia:

Użyj /compact, aby podsumować przed zapełnieniem okna
Użyj /clear między niepowiązanymi zadaniami
Grupuj powiązane pytania: “1. Napraw bug auth 2. Dodaj testy 3. Zaktualizuj README”
Sprawdź pozostałą quotę przez /status
Rozważ dostęp API dla dużego wolumenu użycia (płatność za token, bez limitów okna)

Problemy z Wykonywaniem

Błędy odmowy dostępu

Granularne (zalecane)
Pełne zaufanie (tylko sandboxed)

Skonfiguruj konkretne uprawnienia przez /permissions lub w .claude/settings.json. Wstępnie zatwierdź edycję plików, konkretne polecenia lub narzędzia MCP.

claude --dangerously-skip-permissions

Najlepiej łączyć z Docker dla bezpieczeństwa:

docker run -v $(pwd):/app -w /app claude-code \
  claude --dangerously-skip-permissions -p "napraw wszystkie błędy lint"

Zmiany nie są stosowane

Zweryfikuj, że jesteś we właściwym katalogu: pwd
Sprawdź ścieżki plików — Claude używa ścieżek względem katalogu roboczego
Szukaj blokad Git: rm .git/index.lock
Uruchom git status i git diff, aby zobaczyć, co faktycznie się zmieniło
Jeśli edycja nie powiodła się cicho, spróbuj operacji ponownie z bardziej wyraźnym promptem

Problemy z Codex

Instalacja i Konfiguracja

Codex CLI nie instaluje się

npm install -g @openai/codex
codex --version

Jeśli wystąpią błędy uprawnień:

sudo npm install -g @openai/codex    # macOS/Linux
# Lub użyj nvm do zarządzania Node bez sudo

Uwierzytelnianie nie działa

Zweryfikuj, że twój klucz OpenAI API jest ustawiony:
Okno terminala
```
export OPENAI_API_KEY="sk-..."
```
Sprawdź, czy klucz jest aktywny na platform.openai.com/api-keys
Upewnij się, że masz dostęp do Codex włączony w swoim planie
Testuj: codex "hello" — powinien odpowiedzieć bez błędów

Problemy z Wykonywaniem

Konflikty worktree

Codex tworzy Git worktrees dla każdego zadania. Jeśli zadanie nie powiedzie się w połowie wykonania:

# Lista worktrees
git worktree list

# Usuń nieaktualne worktrees
git worktree prune

# Wymuś usunięcie konkretnego worktree
git worktree remove /path/to/worktree --force

Błędy poleceń sandbox

Codex domyślnie wykonuje polecenia w piaskownicy. Jeśli polecenia zawodzą:

Sprawdź, czy polecenie jest dostępne w środowisku sandbox
Zweryfikuj ustawienia dostępu do sieci — piaskownice mogą domyślnie blokować ruch wychodzący
Dla poleceń wymagających sieci: skonfiguruj sandbox, aby zezwalał na konkretne hosty
Dla poleceń lokalnych: upewnij się, że wszystkie zależności są dostępne w worktree

Cloud agent nie odpowiada

Sprawdź swoje połączenie internetowe
Zweryfikuj klucz API i status planu na platform.openai.com
Sprawdź status usługi Codex na status.openai.com
Spróbuj uruchomić to samo zadanie lokalnie przez CLI codex, aby wyizolować problem
Cloud agents mogą czekać w kolejce podczas szczytowego użycia — sprawdź status zadania w App

Problemy z Serwerem MCP

Problemy z Połączeniem

Serwer MCP nie uruchamia się

Zweryfikuj, że pakiet jest zainstalowany:
Okno terminala
```
npx -y @modelcontextprotocol/server-github --help
```

Sprawdź konfigurację (przykład Claude Code):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Tryb debugowania:

claude --debug    # pokazuje szczegóły połączenia MCP

Sprawdź zmienne środowiskowe: Większość serwerów MCP potrzebuje tokenów (GITHUB_TOKEN, DATABASE_URL, itp.)

Operacje MCP przekraczają limit czasu

Zwiększ timeout w konfiguracji (domyślnie zazwyczaj 10-30 sekund)
Sprawdź, czy zewnętrzna usługa (baza danych, API) odpowiada
Zweryfikuj łączność sieciową z twojej maszyny
Niektóre serwery MCP mają limity rate — sprawdź dokumentację serwera

Gdy AI Stale Popełnia Podstawowe Błędy

Objaw	Przyczyna	Rozwiązanie
AI sugeruje wzorce, które nie pasują do twojego codebase	Brakujący kontekst projektu	Cursor: `/Generate Cursor Rules`. Claude Code: `/init`. Codex: zaktualizuj `AGENTS.md`
AI reimplementuje istniejące funkcje	Brak odniesienia do istniejącego kodu	Użyj referencji `@`, aby dołączyć odpowiednie pliki. Bądź wyraźny: “rozszerz istniejący moduł auth”
Odpowiedzi są ogólne lub niskiej jakości	Niewłaściwy model lub tryb	Zweryfikuj, że używasz Opus 4.6 / GPT-5.3-Codex. Włącz tryb Max dla złożonych zadań
AI zapomina wymagania w połowie zadania	Przepełnienie kontekstu	Użyj `/compact`, aby podsumować. Podziel duże zadania na mniejsze rozmowy
Niewłaściwe API bibliotek lub nieaktualne wzorce	Brak dostępu do dokumentacji	Zainstaluj Context7 MCP lub użyj `@web`, aby pobrać aktualne docs
AI przyjmuje całkowicie niewłaściwe podejście	Niewystarczające wskazówki	Zakończ prompty “Zadaj mi pytania, zanim zaczniesz implementować”

Typowe Komunikaty Błędów

”Model is currently overloaded”

Serwery dostawcy AI są na limicie pojemności. Poczekaj 1-2 minuty i spróbuj ponownie. Jeśli utrzymuje się, przełącz się tymczasowo na inny model lub spróbuj w godzinach poza szczytem.

”Invalid API key”

Sprawdź, czy klucz zaczyna się od poprawnego prefiksu (sk-ant- dla Anthropic, sk- dla OpenAI)
Upewnij się, że nie ma dodatkowych spacji lub cudzysłowów
Zweryfikuj, że klucz nie został cofnięty na dashboardzie dostawcy
Potwierdź, że używasz właściwego klucza dla właściwej usługi

”Context length exceeded”

Rozmowa plus zawartość pliku przekracza context window modelu. Zmniejsz input: usuń niepotrzebne pliki, użyj /compact lub podziel zadanie.

”File not found”

Niewłaściwy katalog roboczy (pwd, aby sprawdzić)
Literówka w nazwie pliku
Plik usunięty lub przeniesiony
Wrażliwość na wielkość liter (systemy plików Linux i macOS domyślnie są case-sensitive)

Procedury Odzyskiwania

Utracone zmiany w kodzie

Prewencja (zawsze rób to przed dużymi operacjami AI):

git add -A && git commit -m "WIP: checkpoint przed zmianami AI"

Opcje odzyskiwania:

Checkpointy Cursor: Użyj przycisku przywracania w czacie
Git reflog: git reflog pokazuje każdą zmianę HEAD, nawet niezacommitowane
Historia lokalna: Cursor/VS Code utrzymują lokalną historię plików per plik
Odzyskiwanie na poziomie OS: Time Machine (macOS), File History (Windows)

Uszkodzona historia czatu

Eksportuj obecny czat, jeśli możliwe
Wyczyść problematyczne dane:
- Cursor: Usuń ~/.cursor/chats/
- Claude Code: Rozpocznij nową sesję (stare sesje pozostają dostępne przez claude -r)
Zrestartuj narzędzie

Wbudowana Diagnostyka

Help > Toggle Developer Tools (sprawdź Console dla błędów)
Cmd/Ctrl+Shift+P > “Cursor: Show Logs”
Kopiuj output diagnostyczny przy zgłaszaniu bugów

/doctor        # pełne sprawdzenie zdrowia
/status        # status systemu i quoty
/help          # dostępne polecenia
claude --version

codex --version
codex "Jaka jest moja obecna konfiguracja?"  # weryfikuj setup

Uzyskiwanie Pomocy

Kanały Wsparcia

Narzędzie	Społeczność	Oficjalne
Cursor	Forum, Discord	Feedback w aplikacji, wsparcie enterprise
Claude Code	Discord, GitHub Issues	support@anthropic.com, kanały enterprise
Codex	Community, GitHub Issues	help.openai.com, wsparcie enterprise

Środki Zapobiegawcze

Aktualizuj regularnie: Nowe wydania często naprawiają dokładnie ten bug, którego doświadczasz
Backup konfiguracji: Kopiuj .cursor/, .claude/ i AGENTS.md przed głównymi aktualizacjami
Monitoruj użycie: Sprawdzaj quoty i koszty co tydzień
Używaj kontroli wersji: Commituj przed dużymi operacjami AI. Używaj gałęzi do eksperymentów
Utrzymuj skupiony kontekst: /clear lub nowy czat między niepowiązanymi zadaniami