Konfiguracja

TL;DR

Wybierz przepływ konfiguracji na podstawie tego, jak często chcesz aktualizować i czy chcesz samodzielnie uruchamiać Gateway:

• Personalizacja żyje poza repozytorium: trzymaj konfigurację i obszar roboczy w ~/.openclaw/openclaw.json i ~/.openclaw/workspace/, aby aktualizacje repozytorium ich nie dotykały.
• Stabilny przepływ pracy (zalecany dla większości): zainstaluj aplikację macOS i pozwól jej uruchamiać dołączony Gateway.
• Przepływ pracy na najnowszej wersji rozwojowej (dev): uruchamiaj Gateway samodzielnie przez pnpm gateway:watch, a następnie pozwól aplikacji macOS podłączyć się w trybie lokalnym.

Wymagania wstępne (ze źródeł)

• Zalecany Node 24 (Node 22 LTS, obecnie 22.19+, nadal obsługiwany)
• pnpm jest wymagany dla checkoutów ze źródeł. OpenClaw ładuje dołączone pluginy z pakietów przestrzeni roboczej pnpm extensions/* w trybie dev, więc główne npm install nie przygotowuje pełnego drzewa źródeł.
• Docker (opcjonalnie; tylko dla konfiguracji/e2e w kontenerach - zobacz Docker)

Strategia personalizacji (aby aktualizacje nie szkodziły)

Jeśli chcesz „100% dopasowania do mnie” i łatwych aktualizacji, trzymaj swoją personalizację w:

• Konfiguracja: ~/.openclaw/openclaw.json (w stylu JSON/JSON5)
• Obszar roboczy: ~/.openclaw/workspace (Skills, prompty, pamięci; zrób z niego prywatne repozytorium git)

Zainicjalizuj raz:

openclaw setup

Z wnętrza tego repozytorium użyj lokalnego punktu wejścia CLI:

openclaw setup

Jeśli nie masz jeszcze instalacji globalnej, uruchom to przez pnpm openclaw setup.

Uruchamianie Gateway z tego repozytorium

Po pnpm build możesz uruchomić spakowane CLI bezpośrednio:

node openclaw.mjs gateway --port 18789 --verbose

Stabilny przepływ pracy (najpierw aplikacja macOS)

1. Zainstaluj i uruchom OpenClaw.app (pasek menu).
2. Ukończ listę kontrolną onboardingu/uprawnień (monity TCC).
3. Upewnij się, że Gateway jest lokalny i działa (aplikacja nim zarządza).
4. Połącz powierzchnie (przykład: WhatsApp):

openclaw channels login

5. Kontrola poprawności:

openclaw health

Jeśli onboarding nie jest dostępny w twojej kompilacji:

• Uruchom openclaw setup, potem openclaw channels login, a następnie ręcznie uruchom Gateway (openclaw gateway).

Przepływ pracy na najnowszej wersji rozwojowej (Gateway w terminalu)

Cel: pracować nad TypeScript Gateway, mieć hot reload i utrzymać podłączony interfejs aplikacji macOS.

0) (Opcjonalnie) Uruchom również aplikację macOS ze źródeł

Jeśli chcesz także mieć aplikację macOS na najnowszej wersji rozwojowej:

./scripts/restart-mac.sh

1) Uruchom dev Gateway

pnpm install# First run only (or after resetting local OpenClaw config/workspace)pnpm openclaw setuppnpm gateway:watch

gateway:watch uruchamia lub restartuje proces obserwujący Gateway w nazwanej sesji tmux i automatycznie dołącza z interaktywnych terminali. Powłoki nieinteraktywne pozostają odłączone i wypisują tmux attach -t openclaw-gateway-watch-main; użyj OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch, aby zachować odłączone uruchomienie interaktywne, albo pnpm gateway:watch:raw dla trybu obserwacji na pierwszym planie. Obserwator przeładowuje się przy istotnych zmianach źródeł, konfiguracji i metadanych dołączonych pluginów. Jeśli obserwowany Gateway zakończy działanie podczas startu, gateway:watch uruchamia openclaw doctor --fix --non-interactive jeden raz i próbuje ponownie; ustaw OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0, aby wyłączyć ten wyłącznie deweloperski przebieg naprawczy. pnpm openclaw setup to jednorazowy krok inicjalizacji lokalnej konfiguracji/obszaru roboczego dla świeżego checkoutu. pnpm gateway:watch nie przebudowuje dist/control-ui, więc po zmianach w ui/ uruchom ponownie pnpm ui:build albo używaj pnpm ui:dev podczas rozwijania Control UI.

2) Skieruj aplikację macOS na działający Gateway

W OpenClaw.app:

• Tryb połączenia: lokalny Aplikacja podłączy się do działającego gatewaya na skonfigurowanym porcie.

3) Zweryfikuj

• Status Gateway w aplikacji powinien brzmieć „Używa istniejącego gatewaya …”
• Albo przez CLI:

openclaw health

Częste pułapki

• Zły port: Gateway WS domyślnie używa ws://127.0.0.1:18789; utrzymuj aplikację i CLI na tym samym porcie.
• Gdzie znajduje się stan:
  • Stan kanału/providera: ~/.openclaw/credentials/
  • Profile uwierzytelniania modelu: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Sesje: ~/.openclaw/agents/<agentId>/sessions/
  • Logi: /tmp/openclaw/

Mapa przechowywania poświadczeń

Użyj tego podczas debugowania uwierzytelniania lub decydowania, co archiwizować:

• WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Token bota Telegram: konfiguracja/env lub channels.telegram.tokenFile (tylko zwykły plik; symlinki odrzucane)
• Token bota Discord: konfiguracja/env lub SecretRef (providery env/file/exec)
• Tokeny Slack: konfiguracja/env (channels.slack.*)
• Listy dozwolonego parowania:
  • ~/.openclaw/credentials/<channel>-allowFrom.json (konto domyślne)
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (konta niedomyślne)
• Profile uwierzytelniania modelu: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Ładunek sekretów oparty na pliku (opcjonalnie): ~/.openclaw/secrets.json
• Import starszego OAuth: ~/.openclaw/credentials/oauth.json Więcej szczegółów: Bezpieczeństwo.

Aktualizowanie (bez niszczenia konfiguracji)

• Traktuj ~/.openclaw/workspace i ~/.openclaw/ jako „swoje rzeczy”; nie wkładaj osobistych promptów/konfiguracji do repozytorium openclaw.
• Aktualizowanie źródeł: git pull + pnpm install + dalsze używanie pnpm gateway:watch.

Linux (usługa użytkownika systemd)

Instalacje na Linuksie używają usługi użytkownika systemd. Domyślnie systemd zatrzymuje usługi użytkownika po wylogowaniu/bezczynności, co zabija Gateway. Onboarding próbuje włączyć utrzymywanie usług po wylogowaniu za ciebie (może poprosić o sudo). Jeśli nadal jest wyłączone, uruchom:

sudo loginctl enable-linger $USER

Dla serwerów always-on lub wieloużytkownikowych rozważ usługę systemową zamiast usługi użytkownika (utrzymywanie po wylogowaniu nie jest potrzebne). Zobacz runbook Gateway, aby poznać notatki systemd.

Powiązana dokumentacja

• Runbook Gateway (flagi, nadzór, porty)
• Konfiguracja Gateway (schemat konfiguracji + przykłady)
• Discord i Telegram (tagi odpowiedzi + ustawienia replyToMode)
• Konfiguracja asystenta OpenClaw
• Aplikacja macOS (cykl życia gatewaya)