ACP ajanları — kurulum

Genel bakış, operatör çalışma kılavuzu ve kavramlar için ACP aracılarına bakın.

Bu sayfa, acpx harness yapılandırmasını, MCP köprüleri için plugin kurulumunu ve izin yapılandırmasını kapsar.

Bu sayfayı yalnızca ACP/acpx yolunu kurarken kullanın. Yerel Codex app-server çalışma zamanı yapılandırması için Codex harness sayfasını kullanın. OpenAI API anahtarları veya Codex OAuth model sağlayıcısı yapılandırması için OpenAI sayfasını kullanın.

Codex'in iki OpenClaw yolu vardır:

ACP/acpx davranışına açıkça ihtiyacınız yoksa yerel yolu tercih edin.

acpx harness desteği (güncel)

Yerleşik acpx harness takma adları (sabitlenmiş acpx bağımlılığından):

factory-droid ve factorydroid de yerleşik droid bağdaştırıcısına çözümlenir.

OpenClaw acpx arka ucunu kullandığında, acpx yapılandırmanız özel aracı takma adları tanımlamıyorsa agentId için bu değerleri tercih edin. Yerel Cursor kurulumunuz ACP'yi hâlâ agent acp olarak sunuyorsa yerleşik varsayılanı değiştirmek yerine acpx yapılandırmanızdaki cursor aracı komutunu geçersiz kılın.

Doğrudan acpx CLI kullanımı, --agent <command> aracılığıyla isteğe bağlı bağdaştırıcıları da hedefleyebilir; ancak bu ham kaçış yolu bir acpx CLI özelliğidir (normal OpenClaw agentId yolu değildir).

Model denetimi, bağdaştırıcı yeteneğine bağlıdır. Codex ACP model referansları başlatılmadan önce OpenClaw tarafından normalleştirilir. Diğer harness'ler ACP models ile session/set_model desteğine ihtiyaç duyar; bir harness ne bu ACP yeteneğini ne de kendi başlangıç model bayrağını sunuyorsa OpenClaw/acpx model seçimini zorlayamaz.

Gerekli yapılandırma

Temel ACP yapılandırması:

{  acp: {    enabled: true,    // İsteğe bağlı. Varsayılan değer true'dur; /acp denetimlerini koruyarak ACP gönderimini duraklatmak için false olarak ayarlayın.    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "codex",    allowedAgents: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "qwen",    ],    stream: {      deliveryMode: "live",    },  },}

İleti dizisi bağlama yapılandırması, desteklenen kanal bağdaştırıcıları arasında paylaşılır:

{  session: {    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,      spawnSessions: true,    },  },}

İleti dizisine bağlı ACP oluşturma çalışmıyorsa önce bağdaştırıcı özellik bayrağını doğrulayın:

• Discord: session.threadBindings.spawnSessions=true

Geçerli konuşma bağlamaları, alt ileti dizisi oluşturulmasını gerektirmez. Etkin bir konuşma bağlamı ve ACP konuşma bağlamalarını sunan bir kanal bağdaştırıcısı gerektirir.

Yapılandırma Referansı sayfasına bakın.

acpx arka ucu için plugin kurulumu

Paketlenmiş kurulumlar, ACP için resmî @openclaw/acpx çalışma zamanı plugin'ini kullanır. ACP harness oturumlarını kullanmadan önce bunu kurun ve etkinleştirin:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Kaynak kod çıkışları, pnpm install sonrasında yerel çalışma alanı plugin'ini de kullanabilir.

Şununla başlayın:

/acp doctor

acpx seçeneğini devre dışı bıraktıysanız, plugins.allow / plugins.deny aracılığıyla reddettiyseniz veya paketlenmiş plugin'e geri dönmek istiyorsanız açık paket yolunu kullanın:

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

Geliştirme sırasında yerel çalışma alanı kurulumu:

openclaw plugins install ./path/to/local/acpx-plugin

Ardından arka uç durumunu doğrulayın:

/acp doctor

acpx çalışma zamanı başlangıç yoklaması

acpx plugin'i ACP çalışma zamanını doğrudan gömer (yapılandırılacak ayrı bir acpx ikili dosyası veya sürümü yoktur). Varsayılan olarak gömülü arka ucu Gateway başlangıcı sırasında kaydeder ve gateway ready sinyalinden önce bir başlangıç yoklamasını bekler. OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 veya OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 değerini yalnızca başlangıç yoklamasını bilinçli olarak devre dışı tutan betikler veya ortamlar için ayarlayın. Açık bir isteğe bağlı yoklama için /acp doctor komutunu çalıştırın.

Bir yolun veya bayrak değerinin tek bir argv belirteci olarak kalması gerektiğinde, tek bir ACP aracısının komutunu yapılandırılmış bağımsız değişkenlerle geçersiz kılın:

{  "plugins": {    "entries": {      "acpx": {        "enabled": true,        "config": {          "agents": {            "claude": {              "command": "node",              "args": ["/path/to/custom adapter.mjs", "--verbose"]            }          }        }      }    }  }}

• agents.<id>.command, bu ACP aracısı için çalıştırılabilir dosya veya mevcut komut dizesidir.
• agents.<id>.args isteğe bağlıdır. OpenClaw, her dizi öğesini geçerli acpx komut dizesi kayıt defteri üzerinden geçirmeden önce kabuk için tırnak içine alır.

Plugin'ler sayfasına bakın.

Otomatik bağdaştırıcı indirme

acpx, ACP bağdaştırıcılarını (örneğin Claude ve Codex ACP köprülerini) ilk kullanımda npx aracılığıyla otomatik olarak indirir. Bağdaştırıcı paketlerini elle kurmanız gerekmez ve OpenClaw'ın kendisi için ayrı bir kurulum sonrası adımı yoktur. Bir bağdaştırıcı indirme veya oluşturma işlemi başarısız olursa /acp doctor hatayı bildirir.

Plugin araçları MCP köprüsü

Varsayılan olarak ACPX oturumları, OpenClaw plugin'leri tarafından kaydedilen araçları ACP harness'ine sunmaz.

Codex veya Claude Code gibi ACP aracılarının bellekten geri çağırma/depolama gibi kurulu OpenClaw plugin araçlarını çağırmasını istiyorsanız özel köprüyü etkinleştirin:

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

Bunun yaptıkları:

• ACPX oturumu önyüklemesine openclaw-plugin-tools adlı yerleşik bir MCP sunucusu ekler.
• Kurulu ve etkin OpenClaw plugin'leri tarafından önceden kaydedilmiş plugin araçlarını sunar.
• Etkin ACP oturumu kimliğini plugin aracı fabrikalarına iletir; böylece aracı kapsamlı araçlar o aracının ad alanında kalır.
• Özelliği açıkça etkinleştirilmesi gereken ve varsayılan olarak kapalı durumda tutar.

Güvenlik ve güven notları:

• Bu, ACP harness araç yüzeyini genişletir.
• ACP aracıları yalnızca gateway'de zaten etkin olan plugin araçlarına erişebilir.
• Bunu, söz konusu plugin'lerin OpenClaw'ın içinde yürütülmesine izin vermekle aynı güven sınırı olarak değerlendirin.
• Etkinleştirmeden önce kurulu plugin'leri inceleyin.

Özel mcpServers eskisi gibi çalışmaya devam eder. Yerleşik plugin araçları köprüsü, genel MCP sunucusu yapılandırmasının yerine geçen bir çözüm değil, isteğe bağlı ek bir kolaylıktır.

OpenClaw araçları MCP köprüsü

Varsayılan olarak ACPX oturumları, yerleşik OpenClaw araçlarını da MCP üzerinden sunmaz. Bir ACP aracısının cron gibi seçili yerleşik araçlara ihtiyaç duyması durumunda ayrı çekirdek araçları köprüsünü etkinleştirin:

openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true

Bunun yaptıkları:

• ACPX oturumu önyüklemesine openclaw-tools adlı yerleşik bir MCP sunucusu ekler.
• Seçili yerleşik OpenClaw araçlarını sunar. İlk sunucu cron aracını sunar.
• Çekirdek araçların sunulmasını açıkça etkinleştirilmesi gereken ve varsayılan olarak kapalı durumda tutar.

Çalışma zamanı işlemi zaman aşımı yapılandırması

acpx plugin'i, gömülü çalışma zamanı başlatma ve denetim işlemlerine varsayılan olarak 120 saniye tanır. Bu, Gemini CLI gibi daha yavaş harness'lerin ACP başlatma ve ilklendirme işlemlerini tamamlaması için yeterli süreyi sağlar. Ana makinenizin farklı bir işlem sınırına ihtiyacı varsa bunu geçersiz kılın:

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

Çalışma zamanı turları, /acp timeout dâhil olmak üzere OpenClaw aracı/çalıştırma zaman aşımlarını kullanır. sessions_spawn, çağrı başına zaman aşımı geçersiz kılmalarını kabul etmez; operatör yolu agents.defaults.subagents.runTimeoutSeconds değeridir. timeoutSeconds değerini değiştirdikten sonra gateway'i yeniden başlatın.

Durum yoklaması aracısı yapılandırması

/acp doctor veya başlangıç yoklaması arka ucu denetlediğinde, paketlenmiş acpx plugin'i bir harness aracısını yoklar. acp.allowedAgents ayarlanmışsa varsayılan olarak izin verilen ilk aracı kullanılır; aksi takdirde varsayılan değer codex olur. Dağıtımınızın durum denetimleri için farklı bir ACP aracısına ihtiyacı varsa yoklama aracısını açıkça ayarlayın:

openclaw config set plugins.entries.acpx.config.probeAgent claude

Bu değeri değiştirdikten sonra gateway'i yeniden başlatın.

İzin yapılandırması

ACP oturumları etkileşimsiz olarak çalışır; dosyaya yazma ve kabuk yürütme izin istemlerini onaylayacak veya reddedecek bir TTY yoktur. acpx plugin'i, izinlerin nasıl işleneceğini denetleyen iki yapılandırma anahtarı sağlar:

Bu ACPX çalıştırma ortamı izinleri, OpenClaw yürütme onaylarından ve Claude CLI --permission-mode bypassPermissions gibi CLI arka ucu sağlayıcı atlama bayraklarından ayrıdır. ACPX approve-all, ACP oturumları için çalıştırma ortamı düzeyindeki acil durum geçersiz kılma anahtarıdır.

OpenClaw tools.exec.mode, Codex Guardian onayları ve ACPX çalıştırma ortamı izinleri arasındaki daha kapsamlı karşılaştırma için İzin modları bölümüne bakın.

permissionMode

Çalıştırma ortamı aracısının istem göstermeden hangi işlemleri gerçekleştirebileceğini denetler.

nonInteractivePermissions

Bir izin isteminin gösterilmesi gerektiğinde ancak etkileşimli TTY kullanılamadığında (ACP oturumlarında her zaman böyledir) ne olacağını denetler.

Yapılandırma

Plugin yapılandırması aracılığıyla ayarlayın:

openclaw config set plugins.entries.acpx.config.permissionMode approve-allopenclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Bu değerleri değiştirdikten sonra Gateway'i yeniden başlatın.

İlgili

• ACP aracıları — genel bakış, operatör çalışma kılavuzu, kavramlar
• Alt aracılar
• Çok aracılı yönlendirme