OpenClaw App SDK to publiczne API klienta dla aplikacji działających poza procesem OpenClaw. UżyjDocumentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
@openclaw/sdk, gdy skrypt, pulpit, zadanie CI, rozszerzenie IDE
lub inna aplikacja zewnętrzna chce połączyć się z Gateway, uruchamiać przebiegi
agentów, strumieniować zdarzenia, czekać na wyniki, anulować pracę albo sprawdzać
zasoby Gateway.
App SDK różni się od Plugin SDK.
@openclaw/sdk komunikuje się z Gateway spoza OpenClaw.
openclaw/plugin-sdk/* jest przeznaczone tylko dla pluginów uruchamianych wewnątrz OpenClaw, które
rejestrują dostawców, kanały, narzędzia, hooki lub zaufane środowiska wykonawcze.Co jest dziś dostarczane
@openclaw/sdk zawiera:
| Powierzchnia | Status | Co robi |
|---|---|---|
OpenClaw | Gotowe | Główny punkt wejścia klienta. Odpowiada za transport, połączenie, żądania i zdarzenia. |
GatewayClientTransport | Gotowe | Transport WebSocket oparty na kliencie Gateway. |
oc.agents | Gotowe | Wyświetla, tworzy, aktualizuje, usuwa i pobiera uchwyty agentów. |
Agent.run() | Gotowe | Uruchamia przebieg Gateway agent i zwraca Run. |
oc.runs | Gotowe | Tworzy, pobiera, oczekuje na, anuluje i strumieniuje przebiegi. |
Run.events() | Gotowe | Strumieniuje znormalizowane zdarzenia dla przebiegu z odtworzeniem dla szybkich przebiegów. |
Run.wait() | Gotowe | Wywołuje agent.wait i zwraca stabilny RunResult. |
Run.cancel() | Gotowe | Wywołuje sessions.abort według identyfikatora przebiegu, z kluczem sesji, gdy jest dostępny. |
oc.sessions | Gotowe | Tworzy, rozwiązuje, wysyła do, łata, kompaktuje i pobiera uchwyty sesji. |
Session.send() | Gotowe | Wywołuje sessions.send i zwraca Run. |
oc.tasks | Gotowe | Wyświetla, odczytuje i anuluje wpisy rejestru zadań Gateway. |
oc.models | Gotowe | Wywołuje models.list oraz bieżące RPC statusu models.authStatus. |
oc.tools | Gotowe | Wyświetla, zakresuje i wywołuje narzędzia Gateway przez potok polityk. |
oc.artifacts | Gotowe | Wyświetla, pobiera i pobiera do pliku artefakty transkrypcji Gateway. |
oc.approvals | Gotowe | Wyświetla i rozwiązuje zatwierdzenia exec przez RPC zatwierdzeń Gateway. |
oc.environments | Częściowe | Wyświetla lokalne dla Gateway i węzłowe kandydaty środowisk; tworzenie/usuwanie nie są podłączone. |
oc.rawEvents() | Gotowe | Udostępnia surowe zdarzenia Gateway dla zaawansowanych odbiorców. |
normalizeGatewayEvent() | Gotowe | Konwertuje surowe zdarzenia Gateway na stabilny kształt zdarzeń SDK. |
AgentRunParams, RunResult, RunStatus, OpenClawEvent,
OpenClawEventType, GatewayEvent, OpenClawTransport,
GatewayRequestOptions, SessionCreateParams, SessionSendParams,
ArtifactSummary, ArtifactQuery, ArtifactsListResult,
ArtifactsGetResult, ArtifactsDownloadResult,
TaskSummary, TaskStatus, TasksListParams, TasksListResult,
TasksGetResult, TasksCancelResult, RuntimeSelection,
EnvironmentSelection, WorkspaceSelection, ApprovalMode oraz powiązane
typy wyników.
Połącz z Gateway
Utwórz klienta z jawnym adresem URL Gateway albo wstrzyknij niestandardowy transport dla testów i osadzonych środowisk wykonawczych aplikacji.new OpenClaw({ gateway: "ws://..." }) jest równoważne z url. Opcja
gateway: "auto" jest akceptowana przez konstruktor, ale automatyczne
wykrywanie Gateway nie jest jeszcze osobną funkcją SDK; przekaż url, gdy aplikacja
nie wie jeszcze, jak wykryć Gateway.
W testach przekaż obiekt implementujący OpenClawTransport:
Uruchom agenta
Użyjoc.agents.get(id), gdy aplikacja chce uzyskać uchwyt agenta, a następnie wywołaj
agent.run().
openai/gpt-5.5, są dzielone na nadpisania Gateway
provider i model. timeoutMs pozostaje w SDK w milisekundach i
jest konwertowane na sekundy limitu czasu Gateway dla RPC agent.
run.wait() używa RPC Gateway agent.wait. Termin oczekiwania, który wygasa,
gdy przebieg nadal jest aktywny, zwraca status: "accepted" zamiast udawać,
że sam przebieg przekroczył limit czasu. Limity czasu środowiska wykonawczego, przerwane przebiegi i anulowane przebiegi są
normalizowane do timed_out lub cancelled.
Twórz i ponownie używaj sesji
Użyj sesji, gdy aplikacja potrzebuje trwałego stanu transkrypcji.Session.send() wywołuje sessions.send i zwraca Run. Uchwyty sesji obsługują także:
Strumieniuj zdarzenia
SDK normalizuje surowe zdarzenia Gateway do stabilnej kopertyOpenClawEvent:
| Typ zdarzenia | Zdarzenie źródłowe Gateway |
|---|---|
run.started | start cyklu życia agent |
run.completed | koniec cyklu życia agent |
run.failed | błąd cyklu życia agent |
run.cancelled | koniec cyklu życia po przerwaniu/anulowaniu |
run.timed_out | koniec cyklu życia po limicie czasu |
assistant.delta | delta strumieniowania asystenta |
assistant.message | wiadomość asystenta |
thinking.delta | strumień myślenia lub planu |
tool.call.started | start narzędzia/elementu/polecenia |
tool.call.delta | aktualizacja narzędzia/elementu/polecenia |
tool.call.completed | ukończenie narzędzia/elementu/polecenia |
tool.call.failed | niepowodzenie narzędzia/elementu/polecenia albo status zablokowany |
approval.requested | żądanie zatwierdzenia exec lub pluginu |
approval.resolved | rozwiązanie zatwierdzenia exec lub pluginu |
session.created | utworzenie sessions.changed |
session.updated | aktualizacja sessions.changed |
session.compacted | Compaction sessions.changed |
task.updated | zdarzenia aktualizacji zadania |
artifact.updated | zdarzenia strumienia łat |
raw | dowolne zdarzenie bez stabilnego mapowania SDK |
Run.events() filtruje zdarzenia do jednego identyfikatora przebiegu i odtwarza już widziane zdarzenia dla
szybkich przebiegów. Oznacza to, że udokumentowany przepływ jest bezpieczny:
oc.events(). Do surowych ramek Gateway użyj
oc.rawEvents().
Modele, narzędzia, artefakty i zatwierdzenia
Pomocniki modeli mapują się na bieżące metody Gateway:oc.tools.invoke() zwraca typowaną kopertę zamiast
zgłaszać wyjątek dla odmów polityki lub zatwierdzenia.
sessionKey, runId albo
taskId:
openclaw tasks:
Jawnie nieobsługiwane dziś
SDK zawiera nazwy dla modelu produktu, którego chcemy, ale nie udaje po cichu, że RPC Gateway istnieją. Te wywołania obecnie zgłaszają jawne błędy braku obsługi:workspace, runtime, environment i approvals dla przebiegu są typowane
jako przyszły kształt, ale obecny Gateway nie obsługuje tych nadpisań w
RPC agent. Jeśli wywołujący je przekażą, SDK zgłasza wyjątek przed przesłaniem przebiegu,
aby praca nie została przypadkowo wykonana z domyślnym obszarem roboczym, środowiskiem wykonawczym,
środowiskiem lub zachowaniem zatwierdzeń.
App SDK kontra Plugin SDK
Użyj App SDK, gdy kod działa poza OpenClaw:- skrypty Node, które uruchamiają lub obserwują przebiegi agentów
- zadania CI, które wywołują Gateway
- pulpity i panele administracyjne
- rozszerzenia IDE
- zewnętrzne mosty, które nie muszą stawać się Pluginami kanałów
- testy integracyjne z fałszywymi lub rzeczywistymi transportami Gateway
- Pluginy dostawców
- Pluginy kanałów
- hooki narzędzi lub cyklu życia
- Pluginy uprzęży agentów
- zaufane pomocniki środowiska wykonawczego
@openclaw/sdk. Kod Pluginów powinien importować z
udokumentowanych ścieżek podrzędnych openclaw/plugin-sdk/*. Nie mieszaj tych dwóch kontraktów.