ACP

Agent Client Protocol (ACP) köprüsünü çalıştırarak bir OpenClaw Gateway ile konuşmasını sağlayın.

Bu komut, IDE'ler için stdio üzerinden ACP konuşur ve istemleri WebSocket üzerinden Gateway'e iletir. ACP oturumlarını Gateway oturum anahtarlarıyla eşlenmiş halde tutar.

openclaw acp, tam ACP-yerel bir düzenleyici çalışma zamanı değil, Gateway destekli bir ACP köprüsüdür. Oturum yönlendirme, istem teslimi ve temel akış güncellemelerine odaklanır.

Bir ACP harness oturumu barındırmak yerine harici bir MCP istemcisinin doğrudan OpenClaw kanal konuşmalarıyla konuşmasını istiyorsanız bunun yerine openclaw mcp serve kullanın.

Bu ne değildir

Bu sayfa genellikle ACP harness oturumlarıyla karıştırılır.

openclaw acp şu anlama gelir:

• OpenClaw bir ACP sunucusu gibi davranır
• bir IDE veya ACP istemcisi OpenClaw'a bağlanır
• OpenClaw bu işi bir Gateway oturumuna iletir

Bu, OpenClaw'ın Codex veya Claude Code gibi harici bir harness'i acpx üzerinden çalıştırdığı ACP Agents özelliğinden farklıdır.

Kısa kural:

• düzenleyici/istemci OpenClaw ile ACP konuşmak istiyor: openclaw acp kullanın
• OpenClaw, Codex/Claude/Gemini'yi ACP harness olarak başlatmalı: /acp spawn ve ACP Agents kullanın

Uyumluluk Matrisi

Bilinen Sınırlamalar

• loadSession, tam ACP olay defteri geçmişini yalnızca köprü tarafından oluşturulmuş oturumlar için yeniden oynatabilir. Daha eski/deftersiz oturumlar hâlâ transkript geri dönüşünü kullanır ve geçmiş araç çağrılarını veya sistem bildirimlerini yeniden oluşturmaz.
• Birden fazla ACP istemcisi aynı Gateway oturum anahtarını paylaşıyorsa olay ve iptal yönlendirmesi, istemci başına sıkı yalıtılmış olmak yerine en iyi çaba düzeyindedir. Temiz düzenleyici-yerel dönüşler gerektiğinde varsayılan yalıtılmış acp:<uuid> oturumlarını tercih edin.
• Gateway durma durumları ACP durma nedenlerine çevrilir, ancak bu eşleme tam ACP-yerel bir çalışma zamanına göre daha az ifade gücüne sahiptir.
• Başlangıç oturum kontrolleri şu anda Gateway ayarlarının odaklanmış bir alt kümesini yüzeye çıkarır: düşünce düzeyi, araç ayrıntı düzeyi, akıl yürütme, kullanım ayrıntısı ve yükseltilmiş eylemler. Model seçimi ve exec-host kontrolleri henüz ACP config seçenekleri olarak sunulmaz.
• session_info_update ve usage_update, canlı ACP-yerel çalışma zamanı muhasebesinden değil Gateway oturum anlık görüntülerinden türetilir. Kullanım yaklaşıktır, maliyet verisi taşımaz ve yalnızca Gateway toplam token verisini güncel olarak işaretlediğinde yayılır.
• Araç takip verisi en iyi çaba düzeyindedir. Köprü, bilinen araç argümanları/sonuçlarında görünen dosya yollarını yüzeye çıkarabilir, ancak henüz ACP terminalleri veya yapılandırılmış dosya diff'leri yaymaz.
• Exec onayı aktarımı etkin ACP istem dönüşüyle sınırlıdır; diğer Gateway oturumlarından gelen onaylar yok sayılır.

Kullanım

openclaw acp # Remote Gatewayopenclaw acp --url wss://gateway-host:18789 --token <token> # Remote Gateway (token from file)openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # Attach to an existing session keyopenclaw acp --session agent:main:main # Attach by label (must already exist)openclaw acp --session-label "support inbox" # Reset the session key before the first promptopenclaw acp --session agent:main:main --reset-session

ACP istemcisi (hata ayıklama)

Köprüyü bir IDE olmadan doğruluk açısından kontrol etmek için yerleşik ACP istemcisini kullanın. ACP köprüsünü başlatır ve istemleri etkileşimli olarak yazmanıza izin verir.

openclaw acp client # Point the spawned bridge at a remote Gatewayopenclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # Override the server command (default: openclaw)openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

İzin modeli (istemci hata ayıklama modu):

• Otomatik onay, izin listesi tabanlıdır ve yalnızca güvenilir çekirdek araç ID'leri için geçerlidir.
• read otomatik onayı geçerli çalışma diziniyle sınırlıdır (--cwd ayarlandığında).
• ACP yalnızca dar salt okunur sınıfları otomatik onaylar: etkin cwd altındaki kapsamlı read çağrıları ve salt okunur arama araçları (search, web_search, memory_search). Bilinmeyen/çekirdek olmayan araçlar, kapsam dışı okumalar, exec yapabilen araçlar, control-plane araçları, değiştiren araçlar ve etkileşimli akışlar her zaman açık istem onayı gerektirir.
• Sunucu tarafından sağlanan toolCall.kind, güvenilmeyen metadata olarak ele alınır (yetkilendirme kaynağı değildir).
• Bu ACP köprü politikası ACPX harness izinlerinden ayrıdır. OpenClaw'ı acpx backend'i üzerinden çalıştırırsanız plugins.entries.acpx.config.permissionMode=approve-all, o harness oturumu için acil durum "yolo" anahtarıdır.

Protokol smoke testi

Protokol düzeyinde hata ayıklama için yalıtılmış durumla bir Gateway başlatın ve bir ACP JSON-RPC istemcisiyle stdio üzerinden openclaw acp çalıştırın. initialize, session/new, mutlak bir cwd ile session/list, session/resume, session/close, yinelenen close ve eksik resume kapsanmalıdır.

Kanıt; duyurulan yaşam döngüsü yeteneklerini, Gateway destekli bir oturum satırını, güncelleme bildirimlerini ve Gateway sessions.list günlüğünü içermelidir:

{  "initialize": {    "protocolVersion": 1,    "agentCapabilities": {      "sessionCapabilities": {        "list": {},        "resume": {},        "close": {}      }    }  },  "listSessions": {    "sessions": [      {        "sessionId": "agent:main:acp-smoke",        "cwd": "/path/to/workspace",        "_meta": {          "sessionKey": "agent:main:acp-smoke",          "kind": "direct"        }      }    ],    "nextCursor": null  },  "notifications": ["session_info_update", "available_commands_update", "usage_update"],  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]}

Tek ACP kanıtı olarak openclaw gateway call sessions.list kullanmaktan kaçının. Bu CLI yolu, fresh-token operatör kapsamı yükseltmesi isteyebilir; ACP köprüsü doğruluğu, ACP stdio frame'leri ve Gateway sessions.list günlüğüyle kanıtlanır.

Bunu nasıl kullanırsınız

Bir IDE (veya başka bir istemci) Agent Client Protocol konuştuğunda ve onun bir OpenClaw Gateway oturumunu sürmesini istediğinizde ACP kullanın.

1. Gateway'in çalıştığından emin olun (yerel veya uzak).
2. Gateway hedefini yapılandırın (config veya flag'ler).
3. IDE'nizi stdio üzerinden openclaw acp çalıştıracak şekilde ayarlayın.

Örnek config (kalıcı):

openclaw config set gateway.remote.url wss://gateway-host:18789openclaw config set gateway.remote.token <token>

Örnek doğrudan çalıştırma (config yazmadan):

openclaw acp --url wss://gateway-host:18789 --token <token># preferred for local process safetyopenclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

Ajanları seçme

ACP ajanları doğrudan seçmez. Gateway oturum anahtarına göre yönlendirir.

Belirli bir ajanı hedeflemek için ajan kapsamlı oturum anahtarları kullanın:

openclaw acp --session agent:main:mainopenclaw acp --session agent:design:mainopenclaw acp --session agent:qa:bug-123

Her ACP oturumu tek bir Gateway oturum anahtarıyla eşleşir. Bir ajanın birçok oturumu olabilir; anahtarı veya etiketi geçersiz kılmadığınız sürece ACP varsayılan olarak yalıtılmış bir acp:<uuid> oturumu kullanır.

Oturum başına mcpServers, köprü modunda desteklenmez. Bir ACP istemcisi bunları newSession veya loadSession sırasında gönderirse köprü, sessizce yok saymak yerine açık bir hata döndürür.

ACPX destekli oturumların OpenClaw Plugin araçlarını veya cron gibi seçili yerleşik araçları görmesini istiyorsanız oturum başına mcpServers geçirmeye çalışmak yerine Gateway tarafındaki ACPX MCP köprülerini etkinleştirin. Bkz. ACP Ajanları ve OpenClaw araçları MCP köprüsü.

acpx üzerinden kullanım (Codex, Claude, diğer ACP istemcileri)

Codex veya Claude Code gibi bir kodlama ajanının OpenClaw botunuzla ACP üzerinden konuşmasını istiyorsanız yerleşik openclaw hedefiyle acpx kullanın.

Tipik akış:

1. Gateway'i çalıştırın ve ACP köprüsünün ona erişebildiğinden emin olun.
2. acpx openclaw komutunu openclaw acp hedefine yönlendirin.
3. Kodlama ajanının kullanmasını istediğiniz OpenClaw oturum anahtarını hedefleyin.

Örnekler:

# One-shot request into your default OpenClaw ACP sessionacpx openclaw exec "Summarize the active OpenClaw session state." # Persistent named session for follow-up turnsacpx openclaw sessions ensure --name codex-bridgeacpx openclaw -s codex-bridge --cwd /path/to/repo \  "Ask my OpenClaw work agent for recent context relevant to this repo."

acpx openclaw komutunun her seferinde belirli bir Gateway'i ve oturum anahtarını hedeflemesini istiyorsanız ~/.acpx/config.json içindeki openclaw ajan komutunu geçersiz kılın:

{  "agents": {    "openclaw": {      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"    }  }}

Depoya yerel bir OpenClaw checkout'u için, ACP akışının temiz kalması adına dev çalıştırıcısı yerine doğrudan CLI giriş noktasını kullanın. Örneğin:

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

Bu, Codex, Claude Code veya ACP destekli başka bir istemcinin terminali kazımadan bir OpenClaw ajanından bağlamsal bilgi çekmesini sağlamanın en kolay yoludur.

Zed düzenleyici kurulumu

~/.config/zed/settings.json içine özel bir ACP ajanı ekleyin (veya Zed'in Ayarlar kullanıcı arayüzünü kullanın):

{  "agent_servers": {    "OpenClaw ACP": {      "type": "custom",      "command": "openclaw",      "args": ["acp"],      "env": {}    }  }}

Belirli bir Gateway'i veya ajanı hedeflemek için:

{  "agent_servers": {    "OpenClaw ACP": {      "type": "custom",      "command": "openclaw",      "args": [        "acp",        "--url",        "wss://gateway-host:18789",        "--token",        "<token>",        "--session",        "agent:design:main"      ],      "env": {}    }  }}

Zed'de Ajan panelini açın ve bir ileti dizisi başlatmak için "OpenClaw ACP" seçeneğini seçin.

Oturum eşleme

Varsayılan olarak ACP oturumları, acp: önekine sahip yalıtılmış bir Gateway oturum anahtarı alır. Bilinen bir oturumu yeniden kullanmak için bir oturum anahtarı veya etiketi geçirin:

• --session <key>: belirli bir Gateway oturum anahtarını kullanın.
• --session-label <label>: mevcut bir oturumu etikete göre çözümleyin.
• --reset-session: bu anahtar için yeni bir oturum kimliği üretin (aynı anahtar, yeni transcript).

ACP istemciniz metadata destekliyorsa oturum başına geçersiz kılabilirsiniz:

{  "_meta": {    "sessionKey": "agent:main:main",    "sessionLabel": "support inbox",    "resetSession": true  }}

Oturum anahtarları hakkında daha fazla bilgiyi /concepts/session adresinde bulabilirsiniz.

Seçenekler

• --url <url>: Gateway WebSocket URL'si (yapılandırıldığında varsayılan olarak gateway.remote.url).
• --token <token>: Gateway kimlik doğrulama token'ı.
• --token-file <path>: Gateway kimlik doğrulama token'ını dosyadan okuyun.
• --password <password>: Gateway kimlik doğrulama parolası.
• --password-file <path>: Gateway kimlik doğrulama parolasını dosyadan okuyun.
• --session <key>: varsayılan oturum anahtarı.
• --session-label <label>: çözümlenecek varsayılan oturum etiketi.
• --require-existing: oturum anahtarı/etiketi yoksa başarısız olun.
• --reset-session: ilk kullanımdan önce oturum anahtarını sıfırlayın.
• --no-prefix-cwd: istemleri çalışma diziniyle öneklemeyin.
• --provenance <off|meta|meta+receipt>: ACP provenance metadata'sını veya alındılarını dahil edin.
• --verbose, -v: stderr'e ayrıntılı günlükleme.

Güvenlik notu:

• --token ve --password, bazı sistemlerde yerel süreç listelerinde görünür olabilir.
• --token-file/--password-file veya ortam değişkenlerini (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD) tercih edin.
• Gateway kimlik doğrulama çözümlemesi, diğer Gateway istemcileri tarafından kullanılan paylaşılan sözleşmeyi izler:
  • yerel mod: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> yalnızca gateway.auth.* ayarlanmamışsa gateway.remote.* geri dönüşü (yapılandırılmış ama çözümlenmemiş yerel SecretRef'ler kapalı şekilde başarısız olur)
  • uzak mod: uzak öncelik kurallarına göre env/config geri dönüşüyle gateway.remote.*
  • --url geçersiz kılmaya güvenlidir ve örtük config/env kimlik bilgilerini yeniden kullanmaz; açık --token/--password (veya dosya varyantlarını) geçirin
• ACP çalışma zamanı backend alt süreçleri OPENCLAW_SHELL=acp alır; bu, bağlama özgü shell/profil kuralları için kullanılabilir.
• openclaw acp client, oluşturulan köprü sürecinde OPENCLAW_SHELL=acp-client ayarlar.

acp client seçenekleri

• --cwd <dir>: ACP oturumu için çalışma dizini.
• --server <command>: ACP sunucu komutu (varsayılan: openclaw).
• --server-args <args...>: ACP sunucusuna geçirilen ek bağımsız değişkenler.
• --server-verbose: ACP sunucusunda ayrıntılı günlüklemeyi etkinleştirin.
• --verbose, -v: ayrıntılı istemci günlüklemesi.

İlgili

• CLI başvurusu
• ACP ajanları