วินิจฉัยเอเจนต์

คู่มือนี้แสดงวิธีค้นหาสาเหตุที่เอเจนต์ไม่สร้างการรัน

ไต่จากบนลงล่าง: การรันของเอเจนต์เองก่อน จากนั้นแบ็กเอนด์ของมัน แล้วจึงเซิร์ฟเวอร์ และสุดท้ายโฮสต์

1. ตรวจสอบประวัติการรันของเอเจนต์

การตั้งค่า → เวิร์กสเปซ → เอเจนต์ → เลือกเอเจนต์ → บันทึก

การรันแต่ละครั้งแสดงป้ายสถานะ ระยะเวลา (“Running…” ขณะกำลังดำเนินอยู่) เวลาเริ่มและเวลาสิ้นสุด PID และอะแดปเตอร์ที่ใช้ ดู เปิดสตรีมเหตุการณ์ดิบของการรันนั้น หยุด ฆ่าโปรเซสที่กำลังรันและทำเครื่องหมายการรันว่า “Killed by user”; ฆ่าที่กำลังรัน ในส่วนหัวทำแบบเดียวกันกับการรันที่กำลังดำเนินอยู่ทุกตัวของเอเจนต์นั้น

อ่านแบบนี้:

ไม่มีการรันเลย — การสั่งงานไม่เคยเกิดขึ้น การกล่าวถึงในคอมโพเซอร์คือ @ บวกอักขระคำ (ตัวอักษร ตัวเลข ขีดล่าง) การจับคู่ชื่อเป็นแบบตรงทั้งหมดหรือตรงคำนำหน้า ดังนั้น @code-reviewer จึงถูกแยกวิเคราะห์เป็น code และยังปลุกเอเจนต์ที่ชื่อ code-reviewer ได้ ชื่อที่มีช่องว่างไม่อาจกล่าวถึงเป็นโทเคนเดียวได้ จากนั้นไปที่ขั้นตอนที่ 2
การรันที่จบลงด้วยข้อผิดพลาดทันที — เปิด ดู ความล้มเหลวในการเรียกแบ็กเอนด์จะปรากฏที่นี่เป็นข้อผิดพลาดของโปรเซส
การรันที่ค้างอยู่ที่ “Running…” — หยุดมัน แล้วตรวจสอบ หมดเวลาเงียบ ของเอเจนต์ในแท็บการตั้งค่า ไทม์เอาต์ที่ไม่ได้ตั้งไว้จะใช้ค่าเริ่มต้นของแต่ละโหมด
การรันที่เสร็จสมบูรณ์แต่ไม่มีเอาต์พุตที่มีประโยชน์ — สถานะในบันทึกการรันยังคงเป็น completed สำหรับการรันที่จบลงโดยไม่มีสิ่งที่ประกาศไว้ว่าต้องส่งมอบ สัญญาณที่ตรงไปตรงมาคือข้อความสรุป ไม่ใช่ป้ายสถานะ

แท็บบันทึกไม่แสดงค่าใช้จ่าย หากต้องการดูค่าใช้จ่าย ให้ใช้ตารางรายเอเจนต์ใน การสังเกตการณ์ → ข้อมูลเชิงลึก

2. ตรวจสอบแบ็กเอนด์ของเอเจนต์

การตั้งค่า → เซิร์ฟเวอร์ → ผู้ให้บริการโมเดล (/settings/server/providers)

รายการ ตัวรันที่ตรวจพบ แสดงอะแดปเตอร์ทุกตัวพร้อมผลการตรวจสอบ — เวอร์ชันที่ติดตั้งแล้ว “กำลังตรวจ…” หรือ “ไม่พบ” — รวมถึงพาธที่แปลงแล้วและชิปความสามารถสำหรับ CLI ที่ตรวจพบ คลิก รีเฟรช ในส่วนหัวของหน้าเพื่อตรวจใหม่

การตรวจสอบรันบนเครื่องที่โฮสต์ cc_server ไม่ใช่บนเครื่องที่คุณกำลังดูอยู่ หากคุณใช้เว็บไคลเอนต์หรืออุปกรณ์ที่จับคู่ไว้ “ไม่พบ” หมายความว่า CLI หายไปจากโฮสต์ของเซิร์ฟเวอร์

มีสองอย่างที่ต้องยืนยัน:

เอเจนต์มีการตั้งค่าอะแดปเตอร์หรือไม่ เอเจนต์ที่อะแดปเตอร์ว่างเปล่าจะถูกส่งงานไปที่ Control Center (built-in) และบันทึกการรันจะบันทึก cc-harness ทรานสคริปต์จึงระบุได้ว่าอะไรเป็นตัวรัน หากไม่มีโมเดลด้วย มันจะขอค่าเริ่มต้นจาก Anthropic — ซึ่งล้มเหลวด้วย No credential for provider "anthropic" เว้นแต่คุณจะเชื่อมต่อบัญชี Anthropic ไว้ ผู้เชี่ยวชาญที่มาพร้อมระบบถูกส่งมาโดยไม่มีอะแดปเตอร์
อะแดปเตอร์ในตัวมีโมเดลหรือไม่ รายการโมเดลของมันดึงสด ๆ จากผู้ให้บริการที่เชื่อมต่ออยู่ถัดลงไปในหน้าเดียวกันนี้ ผู้ให้บริการที่ไม่มีข้อมูลรับรองจัดเก็บไว้จึงเพิ่มโมเดลให้เป็นศูนย์

แค็ตตาล็อกอะแดปเตอร์เองนั้นตายตัว — ไม่มีวิธีลงทะเบียนอะแดปเตอร์ใหม่ สิ่งที่คุณเปลี่ยนได้ต่ออะแดปเตอร์ตรงนี้คืออาร์กิวเมนต์สำหรับเรียกใช้และตัวแปรสภาพแวดล้อมของมัน โปรดทราบว่าการแทนที่ตัวแปรสภาพแวดล้อมรายอะแดปเตอร์จะชนะบัญชีผู้ให้บริการที่เชื่อมต่ออยู่อย่างเงียบ ๆ เมื่อมีการแก้ข้อมูลรับรอง

3. ตรวจสอบเซิร์ฟเวอร์

การตั้งค่า → เซิร์ฟเวอร์ → การเชื่อมต่อและสถานะ (/settings/server/connection) แสดงว่าไคลเอนต์นี้กำลังคุยกับเซิร์ฟเวอร์ตัวใดและเซิร์ฟเวอร์รายงานอะไร

สำหรับเซิร์ฟเวอร์แบบไม่มีส่วนติดต่อ GET /healthz ให้ข้อมูลชุดเดียวกันโดยไม่ต้องมีไคลเอนต์ มันไม่ต้องยืนยันตัวตนและเปิด CORS โดยเจตนา:

curl http://localhost:9030/healthz

มันคืนสถานะของเซิร์ฟเวอร์ เวลาทำงานเป็นวินาที จำนวนการเชื่อมต่อที่ใช้งานอยู่ พอร์ตที่ผูกไว้ เวอร์ชันบิลด์และ git SHA เวอร์ชันสคีมาของเวิร์กสเปซ เวอร์ชันแค็ตตาล็อก RPC id ชื่อ และลายนิ้วมือระบุตัวตนของเซิร์ฟเวอร์ ว่าการผูกไม่ปลอดภัยหรือไม่ และบล็อก codeGraph ที่มีจำนวน watching / indexing / pending เมื่อแคชเคยรับทราฟฟิกแล้ว มันยังมีบล็อก caches ด้วย ส่วนเซิร์ฟเวอร์เดโมจะเพิ่ม demo: true

สองสิ่งที่ควรรู้เมื่อการเปลี่ยนแปลง “ทำงานได้ในการทดสอบแต่ไม่ทำงานในแอป”:

เดสก์ท็อปเรียกไบนารี cc_server ที่บิลด์ไว้ล่วงหน้าออกมาก่อนซอร์ส RPC op ใหม่หรือเครื่องมือ MCP ใหม่จะยังไม่ปรากฏจนกว่าจะบิลด์ไบนารีใหม่ และบันทึกการบูตจะเตือนเมื่อ git SHA ของโปรเซสลูกแตกต่างจากของแอป
เดสก์ท็อปจะฆ่าเซิร์ฟเวอร์ที่มันเปิดขึ้นซึ่งยังไม่พิมพ์แบนเนอร์พร้อมทำงานภายใน 20 วินาที แล้วตกลงสู่หน้าจอข้อผิดพลาด

4. ตรวจสอบโฮสต์

การตั้งค่า → เซิร์ฟเวอร์ → การวินิจฉัยและความเป็นส่วนตัว (/settings/server/diagnostics) คือหน้าในระดับโฮสต์ ประกอบด้วย:

แซนด์บ็อกซ์ — สวิตช์หลัก แบ็กเอนด์ที่ตรวจพบ และคำแนะนำการติดตั้ง มีเพียงแบ็กเอนด์ที่ตรวจพบเท่านั้นที่มาจากเซิร์ฟเวอร์ โปรดดูคำเตือนด้านล่าง ไม่มีตัวควบคุมสำหรับรีเซ็ต
ค้นหาเชิงความหมาย — วงจรชีวิตของโมเดลฝังตัวบนอุปกรณ์: ติดตั้งแล้ว กำลังดาวน์โหลดพร้อมเปอร์เซ็นต์ ยังไม่ได้ติดตั้ง หรือเกิดข้อผิดพลาดในการติดตั้ง จนกว่าจะติดตั้ง หน่วยความจำและการค้นหาโค้ดจะยังเป็นแบบคำสำคัญเท่านั้น
พฤติกรรมระบบ — ทำให้คอมพิวเตอร์ตื่นอยู่ขณะเอเจนต์รัน
ระดับบันทึก — เพิ่มระดับก่อนจำลองความล้มเหลว
ความเป็นส่วนตัว — ว่าเนื้อหา diff ดิบอาจถูกส่งต่อไปยังโมเดลของเอเจนต์ได้หรือไม่ และว่ารายงานข้อขัดข้องถูกส่งหรือไม่

การตรวจจับและการบังคับใช้สอดคล้องกันแล้ว: เมื่อตัวตรวจจับรายงานว่าเป็นแบ็กเอนด์เนทีฟ การรันเอเจนต์บนโฮสต์นั้นก็ถูกห่อหุ้มด้วยมันจริง แต่ตัวตรวจจับคือสิ่งเดียวที่มีชีวิตในส่วนนี้ สวิตช์หลักและตัวเลือกแบ็กเอนด์เป็นค่ากำหนดที่จัดเก็บบนอุปกรณ์ของคุณ และเซิร์ฟเวอร์ไม่อ่านค่าใดในนั้นเลย — สวิตช์ของเซิร์ฟเวอร์เองคือ --sandbox (on โดยค่าเริ่มต้น, off เพื่อเลือกไม่ใช้)

คำเตือนตรงนี้จึงควรค่าแก่การลงมือ แต่โดยปกติไม่ใช่สาเหตุที่เอเจนต์ล้มเหลว หากต้องการยืนยันว่าเซิร์ฟเวอร์อยู่ในสถานะใด ให้อ่านบันทึกตอนเริ่มทำงานของมัน: มันพิมพ์ agent sandbox ON พร้อมหมายเหตุแบ็กเอนด์, no OS-native agent sandbox on this host พร้อมคำแนะนำการติดตั้ง หรือ agent sandbox DISABLED by --sandbox off ส่วน GET /healthz ไม่มีฟิลด์แซนด์บ็อกซ์

เมื่อไม่มีแบ็กเอนด์ — Windows เสมอ ส่วน Linux หรือ WSL2 ที่ไม่มี bwrap และ socat — การรันจะ ไม่ ถูกแซนด์บ็อกซ์ และสิ่งที่จำกัดมันคือเช็คเอาท์ของบทสนทนาเอง โทเคนโฮสต์โค้ดแบบอ่านอย่างเดียวและเกตเวย์การพุช กฎคุมการกระทำ การทำสภาพแวดล้อมให้ปลอดภัย และชุดเครื่องมือที่โหมดของมันอนุญาต

ความล้มเหลวที่พบบ่อย

การรันไม่เริ่มเลยและอะแดปเตอร์ขึ้นว่า “ไม่พบ”

ติดตั้ง CLI บนโฮสต์ของเซิร์ฟเวอร์ แล้วคลิก รีเฟรช บนหน้าผู้ให้บริการโมเดล หรือสลับเอเจนต์ไปใช้อะแดปเตอร์ในตัวซึ่งไม่ต้องใช้ CLI แล้วเชื่อมต่อผู้ให้บริการบนหน้าเดียวกัน

เอเจนต์ push หรือเปิด pull request ไม่ได้

ดูว่า git หรือเอเจนต์พิมพ์อะไรออกมา Control Center policy: … หมายความว่ากฎการกระทำปฏิเสธ หรือการอนุมัติไม่ได้รับคำตอบ: ตรวจ พุชไปยังรีโมต และ เปิด pull request ใน การตั้งค่า → เวิร์กสเปซ → สิทธิ์ของเอเจนต์ หาก git บอกว่า Control Center ไม่มีข้อมูลรับรอง GitHub ที่พุชได้ ให้ติดตั้ง GitHub App บนรีโปนั้น หรือเชื่อม GitHub

ค้นหาเชิงความหมายไม่คืนผลที่มีประโยชน์

ตรวจสอบ การตั้งค่า → เซิร์ฟเวอร์ → การวินิจฉัยและความเป็นส่วนตัว → ค้นหาเชิงความหมาย จนกว่าจะติดตั้งโมเดลฝังตัว การค้นหาจะเป็นแบบคำสำคัญเท่านั้น แถวที่เขียนไว้ก่อนติดตั้งโมเดลจะไม่ถูกเติมย้อนหลัง จึงยังเป็นแบบคำสำคัญเท่านั้นแม้หลังจากนั้น

เซิร์ฟเวอร์บูตไม่ขึ้นเลย

ไลบรารีเนทีฟเป็นสิ่งจำเป็นและไม่มีโหมดลดความสามารถ dylib ที่หายไปทำให้ cc_server ไม่ยอมเริ่มทำงานและระบุตัวที่ก่อปัญหาในข้อความข้อผิดพลาด เตรียมเนทีฟด้วย scripts/natives/build_natives.sh แล้วบิลด์ไบนารีเซิร์ฟเวอร์ใหม่

การกระทำถูกปฏิเสธอย่างเงียบ ๆ

คำตัดสิน prompt ของกฎคุมที่ไม่มีผู้อนุมัติเชื่อมต่ออยู่จะถูกปฏิเสธ โดยเจตนา ตรวจสอบกฎของเวิร์กสเปซได้ที่ การตั้งค่า → เวิร์กสเปซ → สิทธิ์ของเอเจนต์