Loop agen

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

Di OpenClaw, loop adalah satu eksekusi terserialisasi per sesi yang memancarkan event siklus hidup dan stream saat model berpikir, memanggil tool, dan melakukan streaming output. Dokumen ini menjelaskan bagaimana loop autentik tersebut 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), mempersistensikan metadata sesi, langsung mengembalikan { runId, acceptedAt }.
2. agentCommand menjalankan agen:
   • menyelesaikan default model + thinking/verbose/trace
   • memuat snapshot Skills
   • memanggil runEmbeddedAgent (runtime agen OpenClaw)
   • memancarkan akhir/error siklus hidup jika loop tertanam tidak memancarkannya
3. runEmbeddedAgent:
   • menserialisasi run melalui antrean per sesi + global
   • menyelesaikan model + profil auth dan membangun sesi OpenClaw
   • berlangganan event runtime dan melakukan streaming delta asisten/tool
   • menegakkan timeout -> membatalkan run jika terlampaui
   • untuk giliran app-server Codex, membatalkan giliran yang sudah diterima jika berhenti menghasilkan progres app-server sebelum event terminal
   • mengembalikan payload + metadata penggunaan
4. subscribeEmbeddedAgentSession menjembatani event runtime agen ke stream agent OpenClaw:
   • event tool => stream: "tool"
   • delta asisten => stream: "assistant"
   • event siklus hidup => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait menggunakan waitForAgentRun:
   • menunggu akhir/error siklus hidup untuk runId
   • mengembalikan { status: ok|error|timeout, startedAt, endedAt, error? }

Antrean + konkurensi

• Run diserialisasi per kunci sesi (lane sesi) dan secara opsional melalui lane global.
• Ini mencegah race tool/sesi dan menjaga riwayat sesi tetap konsisten.
• Kanal pesan dapat memilih mode antrean (steer/followup/collect/interrupt) yang masuk ke sistem lane ini. Lihat Antrean Perintah.
• Penulisan transkrip juga dilindungi oleh kunci tulis sesi pada file sesi. Kunci tersebut 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; run tersandbox dapat diarahkan ke root workspace sandbox.
• Skills dimuat (atau digunakan ulang 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. Jalur penulisan ulang transkrip, compaction, atau pemotongan apa pun setelahnya 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 run.
• Batas khusus model dan token cadangan Compaction ditegakkan.
• Lihat Prompt sistem untuk apa yang dilihat model.

Titik hook (tempat Anda dapat mencegat)

OpenClaw memiliki dua sistem hook:

• Hook internal (hook Gateway): skrip berbasis event untuk perintah dan event siklus hidup.
• Hook Plugin: titik ekstensi di dalam siklus hidup agen/tool dan pipeline gateway.

Hook internal (hook Gateway)

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

Lihat Hook untuk penyiapan dan contoh.

Hook Plugin (siklus hidup agen + gateway)

Ini berjalan di dalam loop agen atau pipeline gateway:

• before_model_resolve: berjalan pra-sesi (tanpa messages) untuk mengganti provider/model secara deterministik 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 harus berada di ruang prompt sistem.
• before_agent_start: hook kompatibilitas legacy yang dapat berjalan di fase mana pun; utamakan hook 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 run setelah selesai.
• before_compaction / after_compaction: mengamati atau menganotasi siklus compaction.
• before_tool_call / after_tool_call: mencegat parameter/hasil tool.
• before_install: memeriksa materi instalasi skill atau Plugin yang distage setelah kebijakan instalasi operator berjalan, ketika hook Plugin dimuat dalam proses OpenClaw saat ini.
• tool_result_persist: mentransformasi hasil tool secara sinkron sebelum ditulis ke transkrip sesi milik OpenClaw.
• message_received / message_sending / message_sent: hook pesan masuk + keluar.
• session_start / session_end: batas siklus hidup sesi.
• gateway_start / gateway_stop: event siklus hidup gateway.

Aturan keputusan hook untuk guard keluar/tool:

• before_tool_call: { block: true } bersifat terminal dan menghentikan handler dengan prioritas lebih rendah.
• before_tool_call: { block: false } adalah no-op dan tidak menghapus blokir sebelumnya.
• before_install: { block: true } bersifat terminal dan menghentikan handler dengan prioritas lebih rendah.
• before_install: { block: false } adalah no-op dan tidak menghapus blokir sebelumnya.
• Gunakan security.installPolicy, bukan before_install, untuk keputusan izinkan/blokir instalasi milik operator yang harus mencakup jalur instalasi dan pembaruan CLI.
• message_sending: { cancel: true } bersifat terminal dan menghentikan handler dengan prioritas lebih rendah.
• message_sending: { cancel: false } adalah no-op dan tidak menghapus pembatalan sebelumnya.

Lihat Hook Plugin untuk API hook dan detail registrasi.

Harness dapat mengadaptasi hook ini secara berbeda. Harness app-server Codex menjaga hook Plugin OpenClaw sebagai kontrak kompatibilitas untuk surface mirror yang terdokumentasi, sementara hook native Codex tetap menjadi mekanisme Codex tingkat lebih rendah yang terpisah.

Streaming + balasan parsial

• Delta asisten distreaming dari runtime agen dan dipancarkan sebagai event assistant.
• Streaming blok dapat memancarkan balasan parsial baik pada text_end maupun message_end.
• Streaming reasoning dapat dipancarkan sebagai stream terpisah atau sebagai balasan blok.
• Lihat Streaming untuk perilaku chunking dan balasan blok.

Eksekusi tool + tool pesan

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

Pembentukan balasan + penekanan

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

Compaction + percobaan ulang

• Auto-compaction memancarkan event stream compaction dan dapat memicu percobaan ulang.
• Pada percobaan ulang, buffer dalam memori dan ringkasan tool direset untuk menghindari output duplikat.
• Lihat Compaction untuk pipeline compaction.

Stream event (hari ini)

• lifecycle: dipancarkan oleh subscribeEmbeddedAgentSession (dan sebagai fallback oleh agentCommand)
• assistant: delta yang distreaming dari runtime agen
• tool: event tool yang distreaming dari runtime agen

Penanganan kanal chat

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

Timeout

• Default agent.wait: 30 dtk (hanya waktu tunggu). Parameter timeoutMs mengganti ini.
• Runtime agen: default agents.defaults.timeoutSeconds 172800 dtk (48 jam); ditegakkan dalam timer pembatalan runEmbeddedAgent.
• Runtime Cron: timeoutSeconds giliran agen terisolasi dimiliki oleh cron. Scheduler memulai timer tersebut saat eksekusi dimulai, membatalkan run yang mendasarinya pada tenggat yang dikonfigurasi, lalu menjalankan cleanup terbatas sebelum mencatat timeout agar sesi anak stale tidak dapat membuat lane tetap macet.
• Diagnostik keaktifan sesi: dengan diagnostik diaktifkan, diagnostics.stuckSessionWarnMs mengklasifikasikan sesi processing yang lama dan tidak memiliki balasan, tool, status, blok, atau progres ACP yang diamati. Run tertanam aktif, panggilan model, dan panggilan tool dilaporkan sebagai session.long_running; panggilan model senyap yang dimiliki juga tetap session.long_running hingga diagnostics.stuckSessionAbortMs sehingga provider lambat atau non-streaming tidak dilaporkan macet terlalu dini. Pekerjaan aktif tanpa progres terbaru dilaporkan sebagai session.stalled; panggilan model yang dimiliki beralih ke session.stalled pada atau setelah ambang pembatalan, dan aktivitas model/tool stale tanpa pemilik tidak disembunyikan sebagai berjalan lama. session.stuck dicadangkan untuk pembukuan sesi stale yang dapat dipulihkan, termasuk sesi antrean idle dengan aktivitas model/tool stale tanpa pemilik. Pembukuan sesi stale segera melepaskan lane sesi yang terdampak setelah gate pemulihan lolos; run tertanam yang stalled hanya dibatalkan-dikuras setelah diagnostics.stuckSessionAbortMs (default: setidaknya 5 menit dan 3x ambang peringatan) sehingga pekerjaan antrean dapat dilanjutkan tanpa memotong run yang sekadar lambat. Pemulihan memancarkan outcome terstruktur diminta/selesai, dan state diagnostik ditandai idle hanya jika generasi processing yang sama masih saat ini. Diagnostik session.stuck berulang melakukan backoff 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 provider lokal/self-hosted yang lambat, tetapi tetap dibatasi oleh agents.defaults.timeoutSeconds yang lebih rendah atau timeout khusus run karena keduanya mengontrol seluruh run agen. Jika tidak, OpenClaw menggunakan agents.defaults.timeoutSeconds saat dikonfigurasi, dibatasi default maksimum 120 dtk. Run model cloud yang dipicu Cron tanpa timeout model atau agen eksplisit menggunakan watchdog idle default yang sama; dengan timeout run cron eksplisit, stall stream model cloud dibatasi hingga 60 dtk sehingga fallback model yang dikonfigurasi dapat berjalan sebelum tenggat cron luar. Run model lokal atau self-hosted yang dipicu Cron menonaktifkan watchdog implisit kecuali timeout eksplisit dikonfigurasi, dan timeout run cron eksplisit tetap menjadi jendela idle untuk provider lokal/self-hosted, sehingga provider lokal lambat sebaiknya menyetel models.providers.<id>.timeoutSeconds.
• Timeout permintaan HTTP provider: models.providers.<id>.timeoutSeconds berlaku untuk fetch HTTP model provider tersebut, termasuk connect, header, body, timeout permintaan SDK, penanganan pembatalan guarded-fetch total, dan watchdog idle stream model. Gunakan ini untuk provider lokal/self-hosted yang lambat seperti Ollama sebelum menaikkan timeout seluruh runtime agen, dan jaga timeout agen/runtime setidaknya sama tinggi ketika permintaan model perlu berjalan lebih lama.

Tempat hal-hal dapat berakhir lebih awal

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

Terkait

• Alat — alat agen yang tersedia
• Hook — skrip berbasis peristiwa yang dipicu oleh peristiwa siklus hidup agen
• Compaction — cara percakapan panjang dirangkum
• Persetujuan Exec — gerbang persetujuan untuk perintah shell
• Berpikir — konfigurasi tingkat berpikir/penalaran