Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Runtime agen adalah komponen yang memiliki satu loop model yang sudah disiapkan: komponen ini menerima prompt, menjalankan keluaran model, menangani pemanggilan tool native, dan mengembalikan turn yang selesai ke OpenClaw. Runtime mudah tertukar dengan penyedia karena keduanya muncul dekat konfigurasi model. Keduanya adalah lapisan yang berbeda:
LapisanContohArtinya
Penyediaopenai, anthropic, openai-codexCara OpenClaw mengautentikasi, menemukan model, dan menamai ref model.
Modelgpt-5.5, claude-opus-4-6Model yang dipilih untuk turn agen.
Runtime agenpi, codex, claude-cliLoop atau backend tingkat rendah yang mengeksekusi turn yang disiapkan.
ChannelTelegram, Discord, Slack, WhatsAppTempat pesan masuk dan keluar dari OpenClaw.
Anda juga akan melihat kata harness di kode. Harness adalah implementasi yang menyediakan runtime agen. Misalnya, harness Codex bawaan mengimplementasikan runtime codex. Konfigurasi publik menggunakan agentRuntime.id pada entri penyedia atau model; kunci runtime seluruh agen bersifat legacy dan diabaikan. openclaw doctor --fix menghapus pin runtime seluruh agen lama dan menulis ulang ref model runtime legacy menjadi ref penyedia/model kanonis plus kebijakan runtime berlingkup model jika diperlukan. Ada dua keluarga runtime:
  • Harness tertanam berjalan di dalam loop agen OpenClaw yang sudah disiapkan. Saat ini ini adalah runtime pi bawaan plus harness plugin terdaftar seperti codex.
  • Backend CLI menjalankan proses CLI lokal sambil mempertahankan ref model tetap kanonis. Misalnya, anthropic/claude-opus-4-7 dengan agentRuntime.id: "claude-cli" berlingkup model berarti “pilih model Anthropic, eksekusi melalui Claude CLI.” claude-cli bukan id harness tertanam dan tidak boleh diteruskan ke pemilihan AgentHarness.

​
Permukaan Codex

Sebagian besar kebingungan berasal dari beberapa permukaan berbeda yang berbagi nama Codex:
PermukaanNama/konfigurasi OpenClawFungsinya
Runtime app-server Codex nativeref model openai/*Menjalankan turn agen tertanam OpenAI melalui app-server Codex. Ini adalah setup langganan ChatGPT/Codex biasa.
Profil auth OAuth Codexpenyedia auth openai-codexMenyimpan auth langganan ChatGPT/Codex yang digunakan harness app-server Codex.
Adapter ACP Codexruntime: "acp", agentId: "codex"Menjalankan Codex melalui control plane ACP/acpx eksternal. Gunakan hanya ketika ACP/acpx diminta secara eksplisit.
Set perintah kontrol chat Codex native/codex ...Mengikat, melanjutkan, mengarahkan, menghentikan, dan memeriksa thread app-server Codex dari chat.
Rute API OpenAI Platform untuk permukaan non-agenopenai/* plus auth kunci APIDigunakan untuk API OpenAI langsung seperti gambar, embeddings, speech, dan realtime.
Permukaan tersebut sengaja independen. Mengaktifkan plugin codex membuat fitur app-server native tersedia; openclaw doctor --fix memiliki perbaikan rute openai-codex/* legacy dan pembersihan pin sesi basi. Memilih openai/* untuk model agen sekarang berarti “jalankan ini melalui Codex” kecuali permukaan API OpenAI non-agen sedang digunakan. Setup langganan ChatGPT/Codex yang umum menggunakan OAuth Codex untuk auth, tetapi mempertahankan ref model sebagai openai/* dan memilih runtime codex: 
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
}
Itu berarti OpenClaw memilih ref model OpenAI, lalu meminta runtime app-server Codex untuk menjalankan turn agen tertanam. Itu tidak berarti “gunakan penagihan API,” dan tidak berarti channel, katalog penyedia model, atau penyimpanan sesi OpenClaw menjadi Codex. Ketika plugin codex bawaan diaktifkan, kontrol Codex bahasa alami sebaiknya menggunakan permukaan perintah /codex native (/codex bind, /codex threads, /codex resume, /codex steer, /codex stop) alih-alih ACP. Gunakan ACP untuk Codex hanya ketika pengguna secara eksplisit meminta ACP/acpx atau sedang menguji jalur adapter ACP. Claude Code, Gemini CLI, OpenCode, Cursor, dan harness eksternal serupa tetap menggunakan ACP. Ini adalah pohon keputusan yang dihadapi agen:
  1. Jika pengguna meminta bind/control/thread/resume/steer/stop Codex, gunakan permukaan perintah /codex native ketika plugin codex bawaan diaktifkan.
  2. Jika pengguna meminta Codex sebagai runtime tertanam atau menginginkan pengalaman agen Codex normal yang didukung langganan, gunakan openai/<model>.
  3. Jika pengguna secara eksplisit memilih PI untuk model OpenAI, pertahankan ref model sebagai openai/<model> dan set kebijakan runtime penyedia/model ke agentRuntime.id: "pi". Profil auth openai-codex yang dipilih dirutekan secara internal melalui transport auth Codex legacy milik PI.
  4. Jika konfigurasi legacy masih berisi ref model openai-codex/*, perbaiki menjadi openai/<model> dengan openclaw doctor --fix; doctor mempertahankan rute auth Codex dengan menambahkan agentRuntime.id: "codex" berlingkup penyedia/model ketika ref model lama menyiratkannya.
  5. Jika pengguna secara eksplisit mengatakan ACP, acpx, atau adapter ACP Codex, gunakan ACP dengan runtime: "acp" dan agentId: "codex".
  6. Jika permintaan adalah untuk Claude Code, Gemini CLI, OpenCode, Cursor, Droid, atau harness eksternal lain, gunakan ACP/acpx, bukan runtime sub-agen native.
Maksud Anda…Gunakan…
Kontrol chat/thread app-server Codex/codex ... dari plugin codex bawaan
Runtime agen tertanam app-server Codexref model agen openai/*
OAuth OpenAI Codexprofil auth openai-codex
Claude Code atau harness eksternal lainACP/acpx
Untuk pemisahan prefiks keluarga OpenAI, lihat OpenAI dan Penyedia model. Untuk kontrak dukungan runtime Codex, lihat Runtime harness Codex.

​
Kepemilikan runtime

Runtime yang berbeda memiliki bagian loop yang berbeda.
PermukaanOpenClaw PI tertanamApp-server Codex
Pemilik loop modelOpenClaw melalui runner tertanam PIApp-server Codex
Status thread kanonisTranskrip OpenClawThread Codex, plus cermin transkrip OpenClaw
Tool dinamis OpenClawLoop tool OpenClaw nativeDijembatani melalui adapter Codex
Tool shell dan file nativeJalur PI/OpenClawTool native Codex, dijembatani melalui hook native jika didukung
Mesin konteksPerakitan konteks OpenClaw nativeOpenClaw memproyeksikan konteks yang dirakit ke dalam turn Codex
CompactionOpenClaw atau mesin konteks yang dipilihCompaction native Codex, dengan notifikasi OpenClaw dan pemeliharaan cermin
Pengiriman channelOpenClawOpenClaw
Pemisahan kepemilikan ini adalah aturan desain utama:
  • Jika OpenClaw memiliki permukaan, OpenClaw dapat menyediakan perilaku hook plugin normal.
  • Jika runtime native memiliki permukaan, OpenClaw membutuhkan event runtime atau hook native.
  • Jika runtime native memiliki status thread kanonis, OpenClaw harus mencerminkan dan memproyeksikan konteks, bukan menulis ulang internal yang tidak didukung.

​
Pemilihan runtime

OpenClaw memilih runtime tertanam setelah resolusi penyedia dan model:
  1. Kebijakan runtime berlingkup model menang. Ini dapat berada di entri model penyedia yang dikonfigurasi atau di agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime.
  2. Kebijakan runtime berlingkup penyedia berikutnya di models.providers.<provider>.agentRuntime.
  3. Dalam mode auto, runtime plugin terdaftar dapat mengklaim pasangan penyedia/model yang didukung.
  4. Jika tidak ada runtime yang mengklaim turn dalam mode auto, OpenClaw menggunakan PI sebagai runtime kompatibilitas. Gunakan id runtime eksplisit ketika eksekusi harus ketat.
Pin runtime seluruh sesi dan seluruh agen diabaikan. Itu mencakup OPENCLAW_AGENT_RUNTIME, status sesi agentHarnessId/agentRuntimeOverride, agents.defaults.agentRuntime, dan agents.list[].agentRuntime. Jalankan openclaw doctor --fix untuk menghapus konfigurasi runtime seluruh agen yang basi dan mengonversi ref model runtime legacy jika OpenClaw dapat mempertahankan niatnya. Runtime plugin penyedia/model eksplisit gagal tertutup. Misalnya, agentRuntime.id: "codex" pada penyedia atau model berarti Codex atau error pemilihan/runtime yang jelas; itu tidak pernah secara diam-diam dirutekan kembali ke PI. Alias backend CLI berbeda dari id harness tertanam. Bentuk Claude CLI yang disarankan adalah: 
{
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-7",
      models: {
        "anthropic/claude-opus-4-7": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}
Ref legacy seperti claude-cli/claude-opus-4-7 tetap didukung untuk kompatibilitas, tetapi konfigurasi baru harus mempertahankan penyedia/model tetap kanonis dan menaruh backend eksekusi dalam kebijakan runtime penyedia/model. Mode auto sengaja konservatif untuk sebagian besar penyedia. Model agen OpenAI adalah pengecualian: runtime yang tidak di-set dan auto keduanya terselesaikan ke harness Codex. Konfigurasi runtime PI eksplisit tetap menjadi rute kompatibilitas opt-in untuk turn agen openai/*; ketika dipasangkan dengan profil auth openai-codex yang dipilih, OpenClaw merutekan PI secara internal melalui transport auth Codex legacy sambil mempertahankan ref model publik sebagai openai/*. Pin sesi PI OpenAI basi diabaikan oleh pemilihan runtime dan dapat dibersihkan dengan openclaw doctor --fix. Jika openclaw doctor memperingatkan bahwa plugin codex diaktifkan sementara openai-codex/* tetap ada di konfigurasi, perlakukan itu sebagai status rute legacy. Jalankan openclaw doctor --fix untuk menulis ulangnya menjadi openai/* dengan runtime Codex.

​
Kontrak kompatibilitas

Ketika runtime bukan PI, runtime tersebut harus mendokumentasikan permukaan OpenClaw yang didukungnya. Gunakan bentuk ini untuk dokumen runtime:
PertanyaanMengapa ini penting
Siapa yang memiliki loop model?Menentukan di mana percobaan ulang, kelanjutan alat, dan keputusan jawaban akhir terjadi.
Siapa yang memiliki riwayat utas kanonis?Menentukan apakah OpenClaw dapat mengedit riwayat atau hanya mencerminkannya.
Apakah alat dinamis OpenClaw berfungsi?Messaging, sesi, Cron, dan alat milik OpenClaw bergantung pada ini.
Apakah hook alat dinamis berfungsi?Plugin mengharapkan before_tool_call, after_tool_call, dan middleware di sekitar alat milik OpenClaw.
Apakah hook alat native berfungsi?Shell, patch, dan alat milik runtime memerlukan dukungan hook native untuk kebijakan dan observasi.
Apakah siklus hidup mesin konteks berjalan?Plugin memori dan konteks bergantung pada siklus hidup assemble, ingest, after-turn, dan Compaction.
Data Compaction apa yang diekspos?Sebagian plugin hanya membutuhkan notifikasi, sementara yang lain membutuhkan metadata yang dipertahankan/dibuang.
Apa yang sengaja tidak didukung?Pengguna tidak boleh mengasumsikan kesetaraan PI ketika runtime native memiliki lebih banyak status.
Kontrak dukungan runtime Codex didokumentasikan di Runtime harness Codex.

​
Label status

Output status dapat menampilkan label Execution dan Runtime sekaligus. Bacalah sebagai diagnostik, bukan sebagai nama penyedia.
  • Referensi model seperti openai/gpt-5.5 memberi tahu Anda penyedia/model yang dipilih.
  • ID runtime seperti codex memberi tahu Anda loop mana yang mengeksekusi giliran.
  • Label kanal seperti Telegram atau Discord memberi tahu Anda di mana percakapan berlangsung.
Jika suatu eksekusi masih menampilkan runtime yang tidak diharapkan, periksa kebijakan runtime penyedia/model yang dipilih terlebih dahulu. Pin runtime sesi lama tidak lagi menentukan perutean.

​
Terkait