Headless mode

Headless mode คือการรัน claude-code แบบไม่มีหน้าจอโต้ตอบ คือสั่งงานครั้งเดียวจบแล้วรับผลลัพธ์ออกมาทางเอาต์พุตปกติ เพื่อเอาไปต่อในสคริปต์ ในไปป์ไลน์ CI หรือในโปรแกรมอื่น เปิดใช้ด้วยการเติมธง -p หรือ --print พร้อมคำสั่งที่ต้องการ โหมดนี้อ่านข้อมูลจาก stdin ได้ด้วย จึงต่อท่อข้อมูลเข้าไปแล้วเปลี่ยนทิศทางผลลัพธ์ออกไฟล์ได้เหมือนเครื่องมือบรรทัดคำสั่งทั่วไป ตัวอย่างที่ใช้กันจริงคือส่ง log ของการ build เข้าไปแล้วให้อธิบายสาเหตุที่พัง หรือส่ง diff เทียบกับ branch หลักเข้าไปแล้วให้รายงานจุดที่น่าสงสัย

รูปแบบผลลัพธ์เลือกได้สามแบบผ่านธง --output-format แบบ text เป็นข้อความธรรมดาซึ่งเป็นค่าเริ่มต้น แบบ json ให้โครงสร้างที่มีทั้งผลลัพธ์ รหัส session และข้อมูลประกอบ รวมถึงค่าใช้จ่ายของการเรียกครั้งนั้น ทำให้สคริปต์ติดตามต้นทุนต่อครั้งได้โดยไม่ต้องไปเปิดแดชบอร์ด และแบบ stream-json ที่ส่งออกทีละบรรทัดสำหรับงานที่ต้องแสดงผลแบบไหลตามเวลาจริง นอกจากนี้ยังบังคับให้ผลลัพธ์ตรงตามโครงสร้างที่กำหนดได้ด้วยการใส่ --json-schema ซึ่งมีประโยชน์มากเมื่อต้องเอาผลไปป้อนโปรแกรมอื่นต่อ

มีสองเรื่องที่คนตั้งระบบอัตโนมัติต้องรู้ เรื่องแรกคือธง --bare ซึ่งข้ามการโหลด hook, skill, plugin, MCP server, ความจำอัตโนมัติ และไฟล์ claude-md ทั้งหมด เอกสารระบุว่าเหมาะกับงาน CI และสคริปต์ที่ต้องการผลลัพธ์เหมือนกันทุกเครื่อง เพราะถ้าไม่ใส่ hook ที่อยู่ในเครื่องเพื่อนร่วมทีมหรือ MCP server ในโปรเจกต์ก็จะถูกโหลดมาด้วยและทำให้ผลต่างกัน เอกสารยังระบุว่าโหมด bare เป็นรูปแบบที่แนะนำสำหรับการเรียกแบบสคริปต์และจะกลายเป็นค่าเริ่มต้นของ -p ในอนาคต เรื่องที่สองคือการคุมสิทธิ์ เพราะไม่มีคนคอยกดอนุมัติ ต้องระบุเครื่องมือที่อนุญาตไว้ล่วงหน้าด้วย --allowedTools หรือใช้โหมด dontAsk ที่ปฏิเสธทุกอย่างที่ไม่ได้อนุญาตไว้ก่อน ซึ่งเอกสารแนะนำสำหรับงาน CI ที่ต้องล็อกให้แน่น (ดู permission-mode)

ตัวอย่างจากบทสนทนาจริง

วิศวกร DevOps: "ผมอยากให้ทุก pull request มี AI ช่วยอ่านหาจุดผิดพลาดก่อนคนรีวิวครับ ทำได้ไหม"

หัวหน้าทีม: "ได้ครับ ใช้โหมดที่ไม่มีหน้าจอ ต่อท่อ diff เข้าไปแล้วสั่งให้รายงานเป็น JSON ออกมา แล้วเอาไปโพสต์เป็นคอมเมนต์ใน PR สองอย่างที่ต้องใส่คือธง bare เพื่อไม่ให้มันไปโหลดการตั้งค่าที่ติดมากับเครื่องรัน ผลจะได้เหมือนกันทุกครั้ง กับต้องระบุเครื่องมือที่อนุญาตให้ชัด อย่าเปิดกว้าง เพราะไม่มีคนคอยกดอนุมัติแล้ว ถ้ามันตัดสินใจรันอะไรแปลกๆ ใน CI จะไม่มีใครห้ามทันครับ"

ระวังสับสนกับ

• agent-sdk : Agent SDK เป็นไลบรารีสำหรับเขียนโปรแกรมภาษา Python หรือ TypeScript ที่ควบคุม agent ได้เต็มที่ ส่วน headless mode คือการเรียกผ่านบรรทัดคำสั่งซึ่งง่ายกว่าและใช้จากภาษาอะไรก็ได้ เอกสารแนะนำให้รันผ่านบรรทัดคำสั่งถ้าภาษาที่ใช้ไม่ใช่สองภาษานั้น
• afk : AFK คือรูปแบบการทำงานที่ปล่อยให้ AI ทำงานยาวโดยเราไม่ได้นั่งเฝ้า ซึ่งเป็นเรื่องของวิธีทำงาน ส่วน headless mode เป็นกลไกทางเทคนิคที่ไม่มีหน้าจอให้โต้ตอบตั้งแต่แรก
• permission-mode : permission mode คุมว่าต้องขออนุญาตแค่ไหน ซึ่งใช้ได้ทั้งแบบมีหน้าจอและไม่มี แต่ในโหมดไม่มีหน้าจอมันสำคัญเป็นพิเศษ เพราะไม่มีใครกดอนุมัติ และเมื่อถูกบล็อกซ้ำๆ ระบบจะยุติการทำงานแทนที่จะหยุดถาม