openclaw agent

Jalankan giliran agen melalui Gateway (gunakan --local untuk tertanam). Gunakan --agent <id> untuk menargetkan agen terkonfigurasi secara langsung.

Berikan setidaknya satu pemilih sesi:

• --to <dest>
• --session-key <key>
• --session-id <id>
• --agent <id>

Terkait:

• Alat kirim agen: Kirim agen

Opsi

• -m, --message <text>: isi pesan
• --message-file <path>: baca isi pesan dari file UTF-8
• -t, --to <dest>: penerima yang digunakan untuk menurunkan kunci sesi
• --session-key <key>: kunci sesi eksplisit yang digunakan untuk perutean
• --session-id <id>: id sesi eksplisit
• --agent <id>: id agen; mengesampingkan ikatan perutean
• --model <id>: pengesampingan model untuk proses ini (provider/model atau id model)
• --thinking <level>: tingkat berpikir agen (off, minimal, low, medium, high, ditambah tingkat khusus yang didukung penyedia seperti xhigh, adaptive, atau max)
• --verbose <on|off>: simpan tingkat verbose untuk sesi
• --channel <channel>: kanal pengiriman; hilangkan untuk menggunakan kanal sesi utama
• --reply-to <target>: pengesampingan target pengiriman
• --reply-channel <channel>: pengesampingan kanal pengiriman
• --reply-account <id>: pengesampingan akun pengiriman
• --local: jalankan agen tertanam secara langsung (setelah pramuat registri Plugin)
• --deliver: kirim balasan kembali ke kanal/target yang dipilih
• --timeout <seconds>: kesampingkan batas waktu agen (default 600 atau nilai konfigurasi)
• --json: keluarkan JSON

Contoh

openclaw agent --to +15555550123 --message "status update" --deliveropenclaw agent --agent ops --message "Summarize logs"openclaw agent --agent ops --message-file ./task.mdopenclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"openclaw agent --agent ops --session-key incident-42 --message "Summarize status"openclaw agent --session-id 1234 --message "Summarize inbox" --thinking mediumopenclaw agent --to +15555550123 --message "Trace logs" --verbose on --jsonopenclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"openclaw agent --agent ops --message "Run locally" --local

Catatan

• Berikan tepat salah satu dari --message atau --message-file. --message-file mempertahankan konten file multi-baris setelah menghapus BOM UTF-8 opsional, dan menolak file yang bukan UTF-8 valid.
• Mode Gateway kembali ke agen tertanam ketika permintaan Gateway gagal. Gunakan --local untuk memaksa eksekusi tertanam sejak awal.
• --local tetap memuat registri Plugin terlebih dahulu, sehingga penyedia, alat, dan kanal yang disediakan Plugin tetap tersedia selama proses tertanam.
• --local dan proses fallback tertanam diperlakukan sebagai proses sekali jalan. Resource loopback MCP bawaan dan sesi stdio Claude hangat yang dibuka untuk proses lokal itu dihentikan setelah balasan, sehingga pemanggilan berskrip tidak membiarkan proses anak lokal tetap hidup.
• Proses yang didukung Gateway meninggalkan resource loopback MCP milik Gateway di bawah proses Gateway yang berjalan; klien lama mungkin masih mengirim tanda pembersihan historis, tetapi Gateway menerimanya sebagai no-op kompatibilitas.
• --channel, --reply-channel, dan --reply-account memengaruhi pengiriman balasan, bukan perutean sesi.
• --session-key memilih kunci sesi eksplisit. Kunci berprefiks agen harus menggunakan agent:<agent-id>:<session-key>, dan --agent harus cocok dengan id agen milik kunci ketika keduanya diberikan. Kunci non-sentinel polos dicakupkan ke --agent ketika disediakan, atau ke agen default terkonfigurasi jika tidak; misalnya, --agent ops --session-key incident-42 dirutekan ke agent:ops:incident-42. Literal global dan unknown tetap tidak dicakupkan hanya ketika tidak ada --agent yang disediakan; dalam kasus itu, fallback tertanam dan kepemilikan penyimpanan menggunakan agen default terkonfigurasi.
• --json menjaga stdout khusus untuk respons JSON. Diagnostik Gateway, Plugin, dan fallback tertanam dirutekan ke stderr sehingga skrip dapat mengurai stdout secara langsung.
• JSON fallback tertanam menyertakan meta.transport: "embedded" dan meta.fallbackFrom: "gateway" sehingga skrip dapat membedakan proses fallback dari proses Gateway.
• Jika Gateway menerima proses agen tetapi CLI kehabisan waktu saat menunggu balasan akhir, fallback tertanam menggunakan id sesi/proses eksplisit gateway-fallback-* yang baru dan melaporkan meta.fallbackReason: "gateway_timeout" ditambah bidang sesi fallback. Ini menghindari perebutan kunci transkrip milik Gateway atau penggantian diam-diam sesi percakapan terute asli.
• Untuk proses yang didukung Gateway, SIGTERM dan SIGINT menginterupsi permintaan CLI yang sedang menunggu. Jika Gateway sudah menerima proses, CLI juga mengirim chat.abort untuk id proses yang diterima itu sebelum keluar. Proses --local lokal dan proses fallback tertanam menerima sinyal abort yang sama, tetapi tidak mengirim chat.abort. Jika duplikat --run-id mencapai Gateway saat proses agen asli masih aktif, respons duplikat melaporkan status: "in_flight" dan CLI non-JSON mencetak diagnostik stderr alih-alih balasan kosong. Untuk pembungkus cron/systemd eksternal, pertahankan penahan hard-kill luar seperti timeout -k 60 600 openclaw agent ... agar supervisor tetap dapat menuai proses jika penghentian tidak dapat selesai.
• Ketika perintah ini memicu regenerasi models.json, kredensial penyedia yang dikelola SecretRef disimpan sebagai penanda non-rahasia (misalnya nama variabel env, secretref-env:ENV_VAR_NAME, atau secretref-managed), bukan plaintext rahasia yang terselesaikan.
• Penulisan penanda bersifat otoritatif sumber: OpenClaw menyimpan penanda dari snapshot konfigurasi sumber aktif, bukan dari nilai rahasia runtime yang terselesaikan.

Status pengiriman JSON

Ketika --json --deliver digunakan, respons JSON CLI dapat menyertakan deliveryStatus tingkat atas sehingga skrip dapat membedakan pengiriman yang terkirim, ditekan, sebagian, dan gagal:

{  "payloads": [{ "text": "Report ready", "mediaUrl": null }],  "meta": { "durationMs": 1200 },  "deliveryStatus": {    "requested": true,    "attempted": true,    "status": "sent",    "succeeded": true,    "resultCount": 1  }}

deliveryStatus.status adalah salah satu dari sent, suppressed, partial_failed, atau failed. suppressed berarti pengiriman sengaja tidak dikirim, misalnya hook pengiriman pesan membatalkannya atau tidak ada hasil yang terlihat; ini tetap merupakan hasil terminal tanpa coba ulang. partial_failed berarti setidaknya satu payload dikirim sebelum payload berikutnya gagal. failed berarti tidak ada pengiriman tahan lama yang selesai atau preflight pengiriman gagal.

Respons CLI yang didukung Gateway juga mempertahankan bentuk hasil mentah Gateway, tempat objek yang sama tersedia di result.deliveryStatus.

Bidang umum:

• requested: selalu true ketika objek ada.
• attempted: true setelah jalur pengiriman tahan lama berjalan; false untuk kegagalan preflight atau tidak ada payload yang terlihat.
• succeeded: true, false, atau "partial"; "partial" berpasangan dengan status: "partial_failed".
• reason: alasan snake-case huruf kecil dari pengiriman tahan lama atau validasi preflight. Alasan yang diketahui mencakup cancelled_by_message_sending_hook, no_visible_payload, no_visible_result, channel_resolved_to_internal, unknown_channel, invalid_delivery_target, dan no_delivery_target; pengiriman tahan lama yang gagal juga dapat melaporkan tahap yang gagal. Perlakukan nilai tidak dikenal sebagai opaque karena himpunannya dapat bertambah.
• resultCount: jumlah hasil pengiriman kanal jika tersedia.
• sentBeforeError: true ketika kegagalan sebagian mengirim setidaknya satu payload sebelum kesalahan.
• error: boolean true untuk pengiriman yang gagal atau sebagian gagal.
• errorMessage: disertakan hanya ketika pesan kesalahan pengiriman yang mendasari tertangkap. Kegagalan preflight membawa error dan reason tetapi tanpa errorMessage.
• payloadOutcomes: hasil opsional per-payload dengan index, status, reason, resultCount, error, stage, sentBeforeError, atau metadata hook jika tersedia.

Terkait

• Referensi CLI
• Runtime agen