Instrukcja dotyczy klastra BlueOcean w wersji v3.

Do czego służy OpenCode?

W środowisku BlueOcean JupyterLab oraz BlueOcean Desktop można korzystać z OpenCode — narzędzia terminalowego, które pomaga pracować z modelem AI nad kodem i plikami znajdującymi się w katalogu użytkownika. OpenCode jest zainstalowany i skonfigurowany centralnie, ale każdy użytkownik korzysta z własnego konta oraz własnego klucza API.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że:

  • masz dostęp do klastra BlueOcean v3 i możesz uruchomić JupyterLab lub BlueOcean Desktop,
  • masz aktywne konto w serwisie ai.p.lodz.pl,
  • na koncie został utworzony klucz API.

Jeżeli nie masz konta w ai.p.lodz.pl albo nie możesz utworzyć klucza API, zgłoś potrzebę uzyskania dostępu zgodnie z zasadami obowiązującymi w Twojej jednostce. Samo posiadanie konta w BlueOcean nie oznacza automatycznie dostępu do usługi AI.

1. Utworzenie klucza API

  1. Zaloguj się na stronie ai.p.lodz.pl.
  2. Przejdź do menu Ustawienia → Konto → Klucze API.
  3. Utwórz nowy klucz i skopiuj go od razu do bezpiecznego miejsca. Po zamknięciu okna pełna wartość klucza może nie być ponownie widoczna.

Każdy użytkownik powinien używać wyłącznie własnego klucza. Klucza nie należy współdzielić z innymi osobami.

2. Zapisanie klucza w BlueOcean

Otwórz terminal w JupyterLab albo BlueOcean Desktop i wykonaj poniższe polecenia. W miejsce tu_wstaw_swoj_klucz wpisz klucz skopiowany z ai.p.lodz.pl.

Konfiguracja klucza API
mkdir -p ~/.config/kopl
chmod 700 ~/.config/kopl

cat > ~/.config/kopl/opencode.env <<'EOF'
KOPL_OPENWEBUI_API_KEY=tu_wstaw_swoj_klucz
EOF

chmod 600 ~/.config/kopl/opencode.env

Plik ~/.config/kopl/opencode.env znajduje się w prywatnym katalogu domowym użytkownika. Uprawnienie 600 oznacza, że tylko właściciel może go odczytać i zmienić.

Nie wklejaj prawdziwego klucza do notatników, skryptów, repozytoriów Git, zgłoszeń serwisowych, wiadomości e-mail ani publicznych kanałów komunikacji. Nie wykonuj także poleceń wyświetlających zawartość pliku z kluczem podczas udostępniania ekranu lub zapisywania sesji terminala.

3. Sprawdzenie konfiguracji

Sprawdź istnienie pliku i jego uprawnienia bez wyświetlania wartości klucza:

Bezpieczna weryfikacja
ls -l ~/.config/kopl/opencode.env

grep -q '^KOPL_OPENWEBUI_API_KEY=.' ~/.config/kopl/opencode.env   && echo "Klucz jest zapisany"   || echo "Brak klucza lub niepoprawny wpis"

Wynik pierwszego polecenia powinien zaczynać się od -rw-------. Jeżeli uprawnienia są inne, popraw je:

chmod 700 ~/.config/kopl
chmod 600 ~/.config/kopl/opencode.env

4. Uruchomienie OpenCode

Po zapisaniu klucza zakończ wcześniej uruchomione procesy OpenCode i otwórz nowy terminal lub nową sesję JupyterLab/Desktop. Klucz jest automatycznie wczytywany podczas uruchamiania sesji.

W terminalu aktywuj środowisko Conda bo-jupyter, a następnie uruchom OpenCode:

Uruchomienie
conda activate bo-jupyter
opencode

Po uruchomieniu pracuj w katalogu projektu lub katalogu z plikami, których ma dotyczyć rozmowa. Przed zatwierdzeniem zmian proponowanych przez AI zawsze przejrzyj różnice i upewnij się, że nie obejmują plików zawierających dane poufne.

Najczęstsze problemy

ObjawCo sprawdzić
opencode: command not foundSprawdź, czy środowisko bo-jupyter zostało aktywowane poleceniem conda activate bo-jupyter. Jeżeli terminal był otwarty przed zmianą konfiguracji, uruchom nowy terminal.
OpenCode informuje o braku kluczaSprawdź, czy plik ma dokładną nazwę ~/.config/kopl/opencode.env, a wpis zaczyna się od KOPL_OPENWEBUI_API_KEY=. Nie dodawaj spacji po obu stronach znaku =.
Błąd uwierzytelnienia, np. 401Klucz może być niepoprawny, unieważniony albo wygasły. Utwórz nowy klucz w ai.p.lodz.pl i zastąp wartość w pliku konfiguracyjnym.
Brak dostępu, np. 403Sprawdź, czy konto w ai.p.lodz.pl ma przyznany dostęp do usługi. W razie braku dostępu zgłoś potrzebę jego nadania.
Błąd uprawnień do plikuWykonaj ponownie polecenia chmod 700 ~/.config/kopl oraz chmod 600 ~/.config/kopl/opencode.env.

Wymiana lub unieważnienie klucza

Jeżeli podejrzewasz ujawnienie klucza, niezwłocznie unieważnij go w serwisie ai.p.lodz.pl, utwórz nowy i zapisz nową wartość w ~/.config/kopl/opencode.env. Następnie uruchom nową sesję terminala oraz OpenCode.

Aby usunąć lokalną konfigurację po unieważnieniu klucza, usuń plik ~/.config/kopl/opencode.env. OpenCode nie będzie wtedy mógł korzystać z usługi AI do czasu zapisania nowego klucza.

Dobre praktyki

  • Traktuj odpowiedzi modelu jako propozycje wymagające weryfikacji.
  • Przed uruchomieniem wygenerowanych poleceń sprawdź, jakie pliki i zasoby zmienią.
  • Nie przekazuj do modelu haseł, kluczy, danych osobowych ani innych informacji poufnych.
  • Nie dodawaj pliku opencode.env do repozytorium Git.
  • W razie podejrzenia ujawnienia klucza natychmiast go unieważnij i utwórz nowy.
  • No labels