Siklus agen

Loop agentik adalah eksekusi "nyata" penuh dari sebuah agen: intake → penyusunan konteks → inferensi model → eksekusi alat → balasan streaming → persistensi. Ini adalah jalur otoritatif yang mengubah pesan menjadi tindakan dan balasan akhir, sambil menjaga status sesi tetap konsisten.

Di OpenClaw, loop adalah satu eksekusi terserialisasi per sesi yang memancarkan peristiwa siklus hidup dan stream saat model berpikir, memanggil alat, dan melakukan streaming keluaran. Dokumen ini menjelaskan bagaimana loop autentik itu dirangkai dari ujung ke ujung.

# Titik masuk

• RPC Gateway: agent dan agent.wait.
• CLI: perintah agent.

# Cara kerjanya (tingkat tinggi)

1. RPC agent memvalidasi parameter, menyelesaikan sesi (sessionKey/sessionId), mempertahankan metadata sesi, segera mengembalikan { runId, acceptedAt }.
2. agentCommand menjalankan agen:
   • menyelesaikan model + default thinking/verbose/trace
   • memuat snapshot Skills
   • memanggil runEmbeddedPiAgent (runtime pi-agent-core)
   • memancarkan akhir/kesalahan siklus hidup jika loop tertanam tidak memancarkan salah satunya
3. runEmbeddedPiAgent:
   • menserialkan eksekusi melalui antrean per-sesi + global
   • menyelesaikan model + profil autentikasi dan membangun sesi pi
   • berlangganan peristiwa pi dan melakukan streaming delta asisten/alat
   • memberlakukan timeout -> membatalkan eksekusi jika terlampaui
   • untuk giliran server aplikasi Codex, membatalkan giliran yang diterima yang berhenti menghasilkan progres server aplikasi sebelum peristiwa terminal
   • mengembalikan payload + metadata penggunaan
4. subscribeEmbeddedPiSession menjembatani peristiwa pi-agent-core ke stream agent OpenClaw:
   • peristiwa alat => stream: "tool"
   • delta asisten => stream: "assistant"
   • peristiwa siklus hidup => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait menggunakan waitForAgentRun:
   • menunggu akhir/kesalahan siklus hidup untuk runId
   • mengembalikan { status: ok|error|timeout, startedAt, endedAt, error? }

# Pengantrean + konkurensi

• Eksekusi diserialkan per kunci sesi (jalur sesi) dan secara opsional melalui jalur global.
• Ini mencegah race alat/sesi dan menjaga riwayat sesi tetap konsisten.
• Kanal perpesanan dapat memilih mode antrean (collect/steer/followup) yang mengalirkan masukan ke sistem jalur ini. Lihat Antrean Perintah.
• Penulisan transkrip juga dilindungi oleh kunci tulis sesi pada file sesi. Kunci ini sadar proses dan berbasis file, sehingga menangkap penulis yang melewati antrean dalam-proses atau berasal dari proses lain. Penulis transkrip sesi menunggu hingga session.writeLock.acquireTimeoutMs sebelum melaporkan sesi sebagai sibuk; defaultnya adalah 60000 md.
• Kunci tulis sesi secara default tidak reentrant. Jika helper sengaja menumpuk akuisisi kunci yang sama sambil mempertahankan satu penulis logis, helper tersebut harus memilih ikut secara eksplisit dengan allowReentrant: true.

# Persiapan sesi + workspace

• Workspace diselesaikan dan dibuat; eksekusi tersandbox dapat dialihkan ke root workspace sandbox.
• Skills dimuat (atau digunakan kembali dari snapshot) dan disuntikkan ke env dan prompt.
• File bootstrap/konteks diselesaikan dan disuntikkan ke laporan prompt sistem.
• Kunci tulis sesi diperoleh; SessionManager dibuka dan disiapkan sebelum streaming. Setiap jalur penulisan ulang transkrip, Compaction, atau pemotongan nantinya harus mengambil kunci yang sama sebelum membuka atau memutasi file transkrip.

# Penyusunan prompt + prompt sistem

• Prompt sistem dibangun dari prompt dasar OpenClaw, prompt Skills, konteks bootstrap, dan override per-eksekusi.
• Batas khusus model dan token cadangan Compaction diberlakukan.
• Lihat Prompt sistem untuk mengetahui apa yang dilihat model.

# Titik kait (tempat Anda dapat mengintersepsi)

OpenClaw memiliki dua sistem kait:

• Kait internal (kait Gateway): skrip berbasis peristiwa untuk perintah dan peristiwa siklus hidup.
• Kait Plugin: titik ekstensi di dalam siklus hidup agen/alat dan pipeline Gateway.

# Kait internal (kait Gateway)

• agent:bootstrap: berjalan saat membangun file bootstrap sebelum prompt sistem difinalisasi. Gunakan ini untuk menambah/menghapus file konteks bootstrap.
• Kait perintah: /new, /reset, /stop, dan peristiwa perintah lain (lihat dokumen Kait).

Lihat Kait untuk penyiapan dan contoh.

# Kait Plugin (siklus hidup agen + gateway)

Ini berjalan di dalam loop agen atau pipeline gateway:

• before_model_resolve: berjalan pra-sesi (tanpa messages) untuk secara deterministik menimpa penyedia/model sebelum resolusi model.
• before_prompt_build: berjalan setelah pemuatan sesi (dengan messages) untuk menyuntikkan prependContext, systemPrompt, prependSystemContext, atau appendSystemContext sebelum pengiriman prompt. Gunakan prependContext untuk teks dinamis per-giliran dan field konteks sistem untuk panduan stabil yang seharusnya berada di ruang prompt sistem.
• before_agent_start: kait kompatibilitas lama yang dapat berjalan di salah satu fase; utamakan kait eksplisit di atas.
• before_agent_reply: berjalan setelah tindakan inline dan sebelum panggilan LLM, memungkinkan Plugin mengklaim giliran dan mengembalikan balasan sintetis atau membisukan giliran sepenuhnya.
• agent_end: memeriksa daftar pesan akhir dan metadata eksekusi setelah selesai.
• before_compaction / after_compaction: mengamati atau menganotasi siklus Compaction.
• before_tool_call / after_tool_call: mengintersepsi parameter/hasil alat.
• before_install: memeriksa temuan pemindaian bawaan dan secara opsional memblokir instalasi skill atau Plugin.
• tool_result_persist: secara sinkron mentransformasi hasil alat sebelum ditulis ke transkrip sesi milik OpenClaw.
• message_received / message_sending / message_sent: kait pesan masuk + keluar.
• session_start / session_end: batas siklus hidup sesi.
• gateway_start / gateway_stop: peristiwa siklus hidup gateway.

Aturan keputusan kait untuk penjaga keluar/alat:

• before_tool_call: { block: true } bersifat terminal dan menghentikan handler berprioritas lebih rendah.
• before_tool_call: { block: false } adalah no-op dan tidak menghapus blok sebelumnya.
• before_install: { block: true } bersifat terminal dan menghentikan handler berprioritas lebih rendah.
• before_install: { block: false } adalah no-op dan tidak menghapus blok sebelumnya.
• message_sending: { cancel: true } bersifat terminal dan menghentikan handler berprioritas lebih rendah.
• message_sending: { cancel: false } adalah no-op dan tidak menghapus pembatalan sebelumnya.

Lihat Kait Plugin untuk API kait dan detail pendaftaran.

Harness dapat mengadaptasi kait ini secara berbeda. Harness server aplikasi Codex mempertahankan kait Plugin OpenClaw sebagai kontrak kompatibilitas untuk permukaan cermin yang terdokumentasi, sementara kait native Codex tetap menjadi mekanisme Codex tingkat lebih rendah yang terpisah.

# Streaming + balasan parsial

• Delta asisten di-streaming dari pi-agent-core dan dipancarkan sebagai peristiwa assistant.
• Streaming blok dapat memancarkan balasan parsial baik pada text_end maupun message_end.
• Streaming penalaran dapat dipancarkan sebagai stream terpisah atau sebagai balasan blok.
• Lihat Streaming untuk perilaku pemotongan chunk dan balasan blok.

# Eksekusi alat + alat perpesanan

• Peristiwa mulai/perbarui/akhir alat dipancarkan pada stream tool.
• Hasil alat disanitasi untuk ukuran dan payload gambar sebelum dicatat/dipancarkan.
• Pengiriman alat perpesanan dilacak untuk menekan konfirmasi asisten duplikat.

# Pembentukan balasan + penekanan

• Payload akhir disusun dari:
  • teks asisten (dan penalaran opsional)
  • ringkasan alat inline (saat verbose + diizinkan)
  • teks kesalahan asisten saat model mengalami kesalahan
• Token diam persis NO_REPLY / no_reply difilter dari payload keluar.
• Duplikat alat perpesanan dihapus dari daftar payload akhir.
• Jika tidak ada payload yang dapat dirender tersisa dan alat mengalami kesalahan, balasan kesalahan alat fallback dipancarkan (kecuali alat perpesanan sudah mengirim balasan yang terlihat oleh pengguna).

# Compaction + percobaan ulang

• Compaction otomatis memancarkan peristiwa stream compaction dan dapat memicu percobaan ulang.
• Saat percobaan ulang, buffer dalam memori dan ringkasan alat direset untuk menghindari keluaran duplikat.
• Lihat Compaction untuk pipeline Compaction.

# Stream peristiwa (saat ini)

• lifecycle: dipancarkan oleh subscribeEmbeddedPiSession (dan sebagai fallback oleh agentCommand)
• assistant: delta streaming dari pi-agent-core
• tool: peristiwa alat streaming dari pi-agent-core

# Penanganan kanal chat

• Delta asisten dibuffer menjadi pesan delta chat.
• final chat dipancarkan pada akhir/kesalahan siklus hidup.

# Timeout

• Default agent.wait: 30 dtk (hanya penantian). Parameter timeoutMs menimpa ini.
• Runtime agen: default agents.defaults.timeoutSeconds 172800 dtk (48 jam); diberlakukan di timer pembatalan runEmbeddedPiAgent.
• Runtime Cron: timeoutSeconds giliran-agen terisolasi dimiliki oleh cron. Penjadwal memulai timer itu saat eksekusi dimulai, membatalkan eksekusi yang mendasarinya pada tenggat yang dikonfigurasi, lalu menjalankan pembersihan berbatas sebelum mencatat timeout agar sesi anak yang stale tidak dapat membuat jalur tetap tersangkut.
• Diagnostik keaktifan sesi: dengan diagnostik diaktifkan, diagnostics.stuckSessionWarnMs mengklasifikasikan sesi processing yang lama yang tidak memiliki balasan, alat, status, blok, atau progres ACP yang diamati. Eksekusi tertanam, panggilan model, dan panggilan alat yang aktif dilaporkan sebagai session.long_running; pekerjaan aktif tanpa progres terbaru dilaporkan sebagai session.stalled; session.stuck dicadangkan untuk pencatatan sesi stale tanpa pekerjaan aktif. Pencatatan sesi stale segera melepaskan jalur sesi yang terdampak; eksekusi tertanam yang macet hanya dibatalkan-dikuras setelah diagnostics.stuckSessionAbortMs (default: setidaknya 10 menit dan 5x ambang peringatan) agar pekerjaan yang mengantre dapat dilanjutkan tanpa memutus eksekusi yang hanya lambat. Pemulihan memancarkan hasil requested/completed terstruktur, dan status diagnostik ditandai idle hanya jika generasi pemrosesan yang sama masih berjalan. Diagnostik session.stuck berulang melakukan back off selama sesi tetap tidak berubah.
• Timeout idle model: OpenClaw membatalkan permintaan model ketika tidak ada chunk respons yang tiba sebelum jendela idle. models.providers.<id>.timeoutSeconds memperpanjang watchdog idle ini untuk penyedia lokal/self-hosted yang lambat; jika tidak, OpenClaw menggunakan agents.defaults.timeoutSeconds saat dikonfigurasi, dibatasi pada 120 dtk secara default. Eksekusi yang dipicu Cron tanpa timeout model atau agen eksplisit menonaktifkan watchdog idle dan mengandalkan timeout luar cron.
• Timeout permintaan HTTP penyedia: models.providers.<id>.timeoutSeconds berlaku untuk pengambilan HTTP model penyedia tersebut, termasuk koneksi, header, body, timeout permintaan SDK, penanganan pembatalan guarded-fetch total, dan watchdog idle stream model. Gunakan ini untuk penyedia lokal/self-hosted yang lambat seperti Ollama sebelum menaikkan seluruh timeout runtime agen.

# Tempat hal dapat berakhir lebih awal

• Timeout agen (batal)
• AbortSignal (batal)
• Pemutusan Gateway atau timeout RPC
• Timeout agent.wait (hanya menunggu, tidak menghentikan agen)

# Terkait

• Alat — alat agen yang tersedia
• Kait — skrip berbasis peristiwa yang dipicu oleh peristiwa siklus hidup agen
• Compaction — bagaimana percakapan panjang diringkas
• Persetujuan Exec — gerbang persetujuan untuk perintah shell
• Thinking — konfigurasi tingkat berpikir/penalaran