เอเจนต์ ACP

• หากตั้งค่า plugins.allow ไว้ รายการนี้คือบัญชีรายการ Plugin แบบจำกัด และ ต้อง รวม acpx; มิฉะนั้นแบ็กเอนด์ ACP ที่ติดตั้งไว้จะถูกบล็อกโดยตั้งใจ และ /acp doctor จะรายงานรายการ allowlist ที่ขาดไป
• อะแดปเตอร์ Codex ACP ถูกจัดเตรียมมากับ Plugin acpx และจะเปิดใช้ภายในเครื่องเมื่อทำได้
• อะแดปเตอร์ตัวรันเป้าหมายอื่นอาจยังถูกดึงตามต้องการด้วย npx ในครั้งแรกที่คุณใช้งาน
• การยืนยันตัวตนของผู้ให้บริการยังต้องมีอยู่บนโฮสต์สำหรับตัวรันนั้น
• หากโฮสต์ไม่มี npm หรือการเข้าถึงเครือข่าย การดึงอะแดปเตอร์ครั้งแรกจะล้มเหลวจนกว่าจะอุ่นแคชไว้ล่วงหน้าหรือติดตั้งอะแดปเตอร์ด้วยวิธีอื่น

ACP เปิดใช้กระบวนการตัวรันภายนอกจริง OpenClaw เป็นเจ้าของการกำหนดเส้นทาง, สถานะงานเบื้องหลัง, การส่งมอบ, การผูก และนโยบาย; ตัวรันเป็นเจ้าของ การเข้าสู่ระบบผู้ให้บริการ, แค็ตตาล็อกโมเดล, พฤติกรรมระบบไฟล์ และ เครื่องมือเนทีฟของตัวเอง

ก่อนโทษ OpenClaw ให้ตรวจสอบว่า:

• /acp doctor รายงานแบ็กเอนด์ที่เปิดใช้และสุขภาพดี
• อนุญาต id เป้าหมายโดย acp.allowedAgents เมื่อมีการตั้งค่า allowlist นั้น
• คำสั่งตัวรันสามารถเริ่มบนโฮสต์ Gateway ได้
• มีการยืนยันตัวตนผู้ให้บริการสำหรับตัวรันนั้น (claude, codex, gemini, opencode, droid และอื่น ๆ)
• โมเดลที่เลือกมีอยู่สำหรับตัวรันนั้น - id โมเดลไม่สามารถใช้ข้ามตัวรันได้
• cwd ที่ร้องขอมีอยู่และเข้าถึงได้ หรือไม่ต้องระบุ cwd แล้วให้แบ็กเอนด์ใช้ค่าเริ่มต้นของตัวเอง
• โหมดสิทธิ์ตรงกับงาน เซสชันแบบไม่โต้ตอบไม่สามารถคลิกพรอมป์สิทธิ์แบบเนทีฟได้ ดังนั้นงานเขียนโค้ดที่เน้นเขียน/เรียกใช้มักต้องใช้โปรไฟล์สิทธิ์ ACPX ที่ดำเนินต่อแบบไม่มีหน้าจอได้

• การสปอว์นจะสร้างหรือดำเนินเซสชันรันไทม์ ACP ต่อ, บันทึกเมทาดาทา ACP ในที่เก็บเซสชัน OpenClaw และอาจสร้างงานเบื้องหลังเมื่อการรันเป็นของพาเรนต์
• เซสชัน ACP ที่เป็นของพาเรนต์จะถูกปฏิบัติเป็นงานเบื้องหลัง แม้เมื่อเซสชันรันไทม์เป็นแบบคงอยู่; การเสร็จสิ้นและการส่งมอบข้ามพื้นผิวจะผ่านตัวแจ้งงานพาเรนต์ แทนที่จะทำตัวเหมือนเซสชันแชตที่แสดงต่อผู้ใช้ตามปกติ
• การบำรุงรักษางานจะปิดเซสชัน ACP แบบครั้งเดียวที่สิ้นสุดแล้วหรือกำพร้าและเป็นของพาเรนต์ เซสชัน ACP แบบคงอยู่จะถูกเก็บไว้ขณะที่ยังมีการผูกบทสนทนาที่ใช้งานอยู่; เซสชันแบบคงอยู่ที่ค้างโดยไม่มีการผูกที่ใช้งานอยู่จะถูกปิด เพื่อไม่ให้ดำเนินต่อแบบเงียบ ๆ หลังจากงานเจ้าของเสร็จแล้วหรือระเบียนงานหายไป
• ข้อความติดตามผลที่ผูกไว้จะไปยังเซสชัน ACP โดยตรงจนกว่าการผูกจะถูกปิด, เลิกโฟกัส, รีเซ็ต หรือหมดอายุ
• คำสั่ง Gateway ยังคงอยู่ภายในเครื่อง /acp ..., /status และ /unfocus จะไม่ถูกส่งเป็นข้อความพรอมป์ปกติไปยังตัวรัน ACP ที่ผูกไว้
• cancel ยกเลิกเทิร์นที่ใช้งานอยู่เมื่อแบ็กเอนด์รองรับการยกเลิก; ไม่ได้ลบการผูกหรือเมทาดาทาเซสชัน
• close สิ้นสุดเซสชัน ACP จากมุมมองของ OpenClaw และลบการผูก ตัวรันอาจยังเก็บประวัติต้นทางของตัวเองไว้หากรองรับการดำเนินต่อ
• เวิร์กเกอร์รันไทม์ที่ไม่ได้ใช้งานมีสิทธิ์ถูกล้างหลังจาก acp.runtime.ttlMinutes; เมทาดาทาเซสชันที่จัดเก็บไว้ยังคงพร้อมใช้งานสำหรับ /acp sessions

ทริกเกอร์ภาษาธรรมชาติที่ควรกำหนดเส้นทางไปยัง Plugin Codex แบบเนทีฟ เมื่อเปิดใช้งาน:

• "ผูกช่อง Discord นี้กับ Codex"
• "แนบแชตนี้กับเธรด Codex <id>"
• "แสดงเธรด Codex แล้วผูกอันนี้"

การผูกบทสนทนา Codex แบบเนทีฟคือเส้นทางควบคุมแชตเริ่มต้น เครื่องมือไดนามิก OpenClaw ยังคงเรียกใช้ผ่าน OpenClaw ขณะที่ เครื่องมือแบบเนทีฟของ Codex เช่น shell/apply-patch จะเรียกใช้ภายใน Codex สำหรับอีเวนต์เครื่องมือแบบเนทีฟของ Codex, OpenClaw จะแทรกตัวส่งต่อ hook แบบเนทีฟรายเทิร์น เพื่อให้ Plugin hooks สามารถบล็อก before_tool_call, สังเกต after_tool_call และกำหนดเส้นทางอีเวนต์ PermissionRequest ของ Codex ผ่านการอนุมัติของ OpenClaw hook Stop ของ Codex จะถูกส่งต่อไปยัง before_agent_finalize ของ OpenClaw ซึ่ง Plugin สามารถขอรอบโมเดลเพิ่มอีกหนึ่งครั้ง ก่อนที่ Codex จะสรุปคำตอบ การส่งต่อยังคงตั้งใจให้ระมัดระวัง: ไม่แก้ไขอาร์กิวเมนต์เครื่องมือแบบเนทีฟของ Codex หรือเขียนระเบียนเธรด Codex ใหม่ ใช้ ACP แบบชัดเจนเฉพาะเมื่อคุณต้องการโมเดลรันไทม์/เซสชันของ ACP ขอบเขตการรองรับ Codex แบบฝังตัวมีเอกสารอยู่ใน สัญญาการรองรับตัวรัน Codex v1

• openai-codex/* - เส้นทาง PI Codex OAuth/การสมัครใช้งาน
• openai/* บวกกับ agentRuntime.id: "codex" - รันไทม์ฝังตัวของเซิร์ฟเวอร์แอป Codex แบบเนทีฟ
• /codex ... - การควบคุมบทสนทนา Codex แบบเนทีฟ
• /acp ... หรือ runtime: "acp" - การควบคุม ACP/acpx แบบชัดเจน

ทริกเกอร์ที่ควรกำหนดเส้นทางไปยังรันไทม์ ACP:

• "เรียกใช้งานนี้เป็นเซสชัน Claude Code ACP แบบครั้งเดียว แล้วสรุปผลลัพธ์"
• "ใช้ Gemini CLI สำหรับงานนี้ในเธรด แล้วเก็บการติดตามผลไว้ในเธรดเดียวกัน"
• "เรียกใช้ Codex ผ่าน ACP ในเธรดเบื้องหลัง"

OpenClaw เลือก runtime: "acp" แก้ค่า harness agentId ผูกกับบทสนทนาหรือเธรดปัจจุบันเมื่อรองรับ และ กำหนดเส้นทางการติดตามผลไปยังเซสชันนั้นจนกว่าจะปิด/หมดอายุ Codex จะ ใช้เส้นทางนี้เฉพาะเมื่อ ACP/acpx ถูกระบุอย่างชัดเจน หรือ Plugin Codex แบบเนทีฟไม่พร้อมใช้งานสำหรับการดำเนินการที่ร้องขอ

สำหรับ sessions_spawn, runtime: "acp" จะถูกประกาศเฉพาะเมื่อเปิดใช้ ACP ผู้ร้องขอไม่ได้อยู่ใน sandbox และโหลด backend รันไทม์ ACP แล้ว acp.dispatch.enabled=false จะหยุดการ dispatch เธรด ACP อัตโนมัติ ชั่วคราว แต่จะไม่ซ่อนหรือบล็อกการเรียก sessions_spawn({ runtime: "acp" }) แบบชัดเจน โดยมีเป้าหมายเป็น id ของ ACP harness เช่น codex, claude, droid, gemini หรือ opencode อย่าส่ง id เอเจนต์ config OpenClaw ปกติจาก agents_list เว้นแต่รายการนั้นจะถูกกำหนดค่า อย่างชัดเจนด้วย agents.list[].runtime.type="acp"; ไม่เช่นนั้นให้ใช้รันไทม์ sub-agent เริ่มต้น เมื่อเอเจนต์ OpenClaw ถูกกำหนดค่าด้วย runtime.type="acp" OpenClaw จะใช้ runtime.acp.agent เป็น id ของ harness พื้นฐาน

• --bind here และ --thread ... ใช้ร่วมกันไม่ได้
• --bind here ทำงานเฉพาะบนช่องทางที่ประกาศความสามารถการผูกบทสนทนาปัจจุบัน; มิฉะนั้น OpenClaw จะส่งคืนข้อความไม่รองรับที่ชัดเจน การผูกคงอยู่ข้ามการรีสตาร์ต Gateway
• บน Discord, spawnSessions ควบคุมการสร้างเธรดลูกสำหรับ --thread auto|here - ไม่ใช่ --bind here
• หากคุณ spawn ไปยังเอเจนต์ ACP อื่นโดยไม่มี --cwd, OpenClaw จะสืบทอดพื้นที่ทำงานของ เอเจนต์เป้าหมาย โดยค่าเริ่มต้น เส้นทางที่สืบทอดมาซึ่งหายไป (ENOENT/ENOTDIR) จะ fallback ไปยังค่าเริ่มต้นของ backend; ข้อผิดพลาดการเข้าถึงอื่น ๆ (เช่น EACCES) จะแสดงเป็นข้อผิดพลาดการ spawn
• คำสั่งจัดการ Gateway จะยังคงอยู่ในเครื่องภายในบทสนทนาที่ถูกผูก - คำสั่ง /acp ... ถูกจัดการโดย OpenClaw แม้เมื่อข้อความติดตามผลปกติถูกกำหนดเส้นทางไปยังเซสชัน ACP ที่ถูกผูก; /status และ /unfocus ก็ยังอยู่ในเครื่องเช่นกันเมื่อเปิดใช้งานการจัดการคำสั่งสำหรับพื้นผิวนั้น

เมื่อเปิดใช้งานการผูกเธรดสำหรับอะแดปเตอร์ช่องทาง:

• OpenClaw ผูกเธรดกับเซสชัน ACP เป้าหมาย
• ข้อความติดตามผลในเธรดนั้นถูกกำหนดเส้นทางไปยังเซสชัน ACP ที่ถูกผูก
• เอาต์พุต ACP ถูกส่งกลับไปยังเธรดเดียวกัน
• Unfocus/close/archive/idle-timeout หรือการหมดอายุ max-age จะลบการผูกออก
• /acp close, /acp cancel, /acp status, /status และ /unfocus เป็นคำสั่ง Gateway ไม่ใช่พรอมป์ไปยัง ACP harness

feature flag ที่จำเป็นสำหรับ ACP ที่ผูกกับเธรด:

• acp.enabled=true
• acp.dispatch.enabled เปิดอยู่โดยค่าเริ่มต้น (ตั้งค่า false เพื่อหยุดการ dispatch เธรด ACP อัตโนมัติชั่วคราว; การเรียก sessions_spawn({ runtime: "acp" }) แบบชัดเจนยังคงทำงาน)
• เปิดใช้การ spawn เซสชันเธรดของอะแดปเตอร์ช่องทาง (ค่าเริ่มต้น: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

การรองรับการผูกเธรดขึ้นอยู่กับอะแดปเตอร์ หากอะแดปเตอร์ช่องทางที่ใช้งานอยู่ ไม่รองรับการผูกเธรด OpenClaw จะส่งคืนข้อความ ไม่รองรับ/ไม่พร้อมใช้งานที่ชัดเจน

• อะแดปเตอร์ช่องทางใด ๆ ที่เปิดเผยความสามารถการผูกเซสชัน/เธรด
• การรองรับในตัวปัจจุบัน: เธรด/ช่อง Discord, หัวข้อ Telegram (หัวข้อฟอรัมในกลุ่ม/supergroup และหัวข้อ DM)
• ช่องทาง Plugin สามารถเพิ่มการรองรับผ่านอินเทอร์เฟซการผูกเดียวกัน

เซสชันแบบโต้ตอบมีไว้เพื่อสนทนาต่อบนพื้นผิวแชตที่มองเห็นได้:

• /acp spawn ... --bind here ผูกการสนทนาปัจจุบันกับเซสชัน ACP
• /acp spawn ... --thread ... ผูกเธรด/หัวข้อของช่องกับเซสชัน ACP
• bindings[].type="acp" ที่กำหนดค่าแบบต่อเนื่องจะ route การสนทนาที่ตรงกันไปยังเซสชัน ACP เดียวกัน

ข้อความติดตามผลในการสนทนาที่ผูกไว้จะถูก route โดยตรงไปยัง เซสชัน ACP และผลลัพธ์ ACP จะถูกส่งกลับไปยัง ช่อง/เธรด/หัวข้อเดียวกัน

สิ่งที่ OpenClaw ส่งไปยัง harness:

• follow-up ที่ผูกไว้ตามปกติจะถูกส่งเป็นข้อความพรอมป์ พร้อมไฟล์แนบเฉพาะเมื่อ harness/backend รองรับเท่านั้น
• คำสั่งจัดการ /acp และคำสั่ง Gateway ภายในจะถูกดักก่อน dispatch ไปยัง ACP
• เหตุการณ์การทำงานเสร็จที่ runtime สร้างขึ้นจะถูก materialize ตามเป้าหมาย เอเจนต์ OpenClaw จะได้รับ envelope runtime-context ภายในของ OpenClaw; harness ACP ภายนอกจะได้รับพรอมป์ธรรมดาพร้อมผลลัพธ์ลูกและคำสั่ง envelope ดิบ <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> ไม่ควรถูกส่งไปยัง harness ภายนอกหรือ persist เป็นข้อความ transcript ของผู้ใช้ ACP
• รายการ transcript ของ ACP ใช้ข้อความ trigger ที่ผู้ใช้มองเห็นหรือพรอมป์การทำงานเสร็จแบบธรรมดา metadata เหตุการณ์ภายในจะยังคงเป็นแบบ structured ใน OpenClaw เมื่อทำได้ และไม่ถือเป็นเนื้อหาแชตที่ผู้ใช้เขียน

เซสชัน ACP แบบทำครั้งเดียวที่ spawn โดยการรันของเอเจนต์อื่นเป็นลูก เบื้องหลัง คล้ายกับ sub-agents:

• แม่ขอให้งานทำงานด้วย sessions_spawn({ runtime: "acp", mode: "run" })
• ลูกทำงานในเซสชัน ACP harness ของตนเอง
• turn ของลูกทำงานบนเลนเบื้องหลังเดียวกับที่ใช้โดยการ spawn sub-agent แบบ native ดังนั้น ACP harness ที่ช้าจะไม่บล็อกงานของ main-session ที่ไม่เกี่ยวข้อง
• รายงานการทำงานเสร็จกลับผ่านเส้นทางประกาศ task-completion OpenClaw แปลง metadata การทำงานเสร็จภายในเป็นพรอมป์ ACP ธรรมดาก่อนส่งไปยัง harness ภายนอก ดังนั้น harness จะไม่เห็น marker runtime context เฉพาะ OpenClaw
• แม่เขียนผลลัพธ์ลูกใหม่ด้วยเสียง assistant ปกติเมื่อคำตอบสำหรับผู้ใช้มีประโยชน์

อย่า ถือว่า เส้นทางนี้เป็นแชตแบบ peer-to-peer ระหว่างแม่ และลูก ลูกมีช่องทางการทำงานเสร็จกลับไปยัง แม่อยู่แล้ว

sessions_send สามารถกำหนดเป้าหมายไปยังเซสชันอื่นหลัง spawn ได้ สำหรับเซสชัน peer ปกติ OpenClaw ใช้เส้นทาง follow-up แบบ agent-to-agent (A2A) หลังจาก inject ข้อความ:

• รอคำตอบของเซสชันเป้าหมาย
• เลือกให้ผู้ร้องขอและเป้าหมายแลกเปลี่ยน turn ติดตามผลได้ในจำนวนที่จำกัด
• ขอให้เป้าหมายสร้างข้อความประกาศ
• ส่งประกาศนั้นไปยังช่องหรือเธรดที่มองเห็นได้

เส้นทาง A2A นั้นเป็น fallback สำหรับการส่งแบบ peer ที่ผู้ส่งต้องการ follow-up ที่มองเห็นได้ เส้นทางนี้ยังคงเปิดใช้เมื่อเซสชันที่ไม่เกี่ยวข้องสามารถ เห็นและส่งข้อความถึงเป้าหมาย ACP ได้ เช่นภายใต้การตั้งค่า tools.sessions.visibility แบบกว้าง

OpenClaw จะข้าม A2A follow-up เฉพาะเมื่อผู้ร้องขอเป็น แม่ของลูก ACP แบบทำครั้งเดียวที่แม่เป็นเจ้าของของตนเอง ในกรณีนั้น การรัน A2A ทับบน task completion สามารถปลุกแม่ด้วย ผลลัพธ์ของลูก ส่งต่อคำตอบของแม่กลับเข้าไปในลูก และ สร้าง echo loop ระหว่างแม่/ลูก ผลลัพธ์ sessions_send รายงาน delivery.status="skipped" สำหรับกรณี owned-child นั้น เพราะ เส้นทางการทำงานเสร็จรับผิดชอบผลลัพธ์อยู่แล้ว

ใช้ resumeSessionId เพื่อดำเนินเซสชัน ACP ก่อนหน้าต่อแทน การเริ่มใหม่ เอเจนต์จะเล่นประวัติการสนทนาซ้ำผ่าน session/load จึงเริ่มต่อด้วยบริบทเต็มของสิ่งที่เกิดขึ้นก่อนหน้า

{
  "task": "Continue where we left off - fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

กรณีใช้งานทั่วไป:

• ส่งต่อเซสชัน Codex จากแล็ปท็อปไปยังโทรศัพท์ของคุณ - บอกเอเจนต์ของคุณให้เริ่มต่อจากจุดที่คุณค้างไว้
• ดำเนินเซสชันเขียนโค้ดที่คุณเริ่มแบบโต้ตอบใน CLI ต่อ โดยตอนนี้ทำแบบ headless ผ่านเอเจนต์ของคุณ
• ทำงานต่อจากงานที่ถูกขัดจังหวะโดยการรีสตาร์ต gateway หรือ idle timeout

หมายเหตุ:

• resumeSessionId ใช้เฉพาะเมื่อ runtime: "acp"; runtime sub-agent เริ่มต้นจะละเว้นฟิลด์เฉพาะ ACP นี้
• streamTo ใช้เฉพาะเมื่อ runtime: "acp"; runtime sub-agent เริ่มต้นจะละเว้นฟิลด์เฉพาะ ACP นี้
• resumeSessionId เป็น id resume ของ ACP/harness แบบ host-local ไม่ใช่คีย์เซสชันช่องของ OpenClaw; OpenClaw ยังตรวจสอบนโยบาย ACP spawn และนโยบายเอเจนต์เป้าหมายก่อน dispatch ขณะที่ backend หรือ harness ACP เป็นเจ้าของการอนุญาตสำหรับโหลด id ต้นทางนั้น
• resumeSessionId คืนค่าประวัติการสนทนา ACP ต้นทาง; thread และ mode ยังใช้ตามปกติกับเซสชัน OpenClaw ใหม่ที่คุณกำลังสร้าง ดังนั้น mode: "session" ยังคงต้องใช้ thread: true
• เอเจนต์เป้าหมายต้องรองรับ session/load (Codex และ Claude Code รองรับ)
• หากไม่พบ session id การ spawn จะล้มเหลวพร้อมข้อผิดพลาดที่ชัดเจน - ไม่มี fallback ไปยังเซสชันใหม่อย่างเงียบ ๆ

หลัง deploy gateway ให้รันการตรวจสอบ end-to-end แบบ live แทนการ เชื่อถือ unit test:

1. ตรวจสอบเวอร์ชันและ commit ของ gateway ที่ deploy บน host เป้าหมาย
2. เปิดเซสชัน bridge ACPX ชั่วคราวไปยังเอเจนต์ live
3. ขอให้เอเจนต์นั้นเรียก sessions_spawn ด้วย runtime: "acp", agentId: "codex", mode: "run" และ task Reply with exactly LIVE-ACP-SPAWN-OK
4. ตรวจสอบ accepted=yes, childSessionKey จริง และไม่มีข้อผิดพลาด validator
5. ล้างเซสชัน bridge ชั่วคราว

คง gate ไว้ที่ mode: "run" และข้าม streamTo: "parent" - mode: "session" แบบผูกเธรดและเส้นทาง stream-relay เป็น integration pass ที่สมบูรณ์กว่าและแยกต่างหาก