Skip to content
OpenCode
app.header.homeapp.header.docs

การแก้ไขปัญหา

ปัญหาทั่วไปและวิธีแก้ปัญหา

หากต้องการแก้ไขข้อบกพร่องเกี่ยวกับ OpenCode ให้เริ่มต้นด้วยการตรวจสอบบันทึกและข้อมูลในเครื่องที่จัดเก็บไว้ในดิสก์

บันทึก

ไฟล์บันทึกถูกเขียนไปที่:

  • macOS/Linux: ~/.local/share/opencode/log/
  • Windows: กด WIN+R แล้ววาง %USERPROFILE%\.local\share\opencode\log

ไฟล์บันทึกจะถูกตั้งชื่อด้วยการประทับเวลา (เช่น 2025-01-09T123456.log) และไฟล์บันทึกล่าสุด 10 ไฟล์จะถูกเก็บไว้

คุณสามารถตั้งค่าระดับการบันทึกด้วยตัวเลือกบรรทัดคำสั่ง --log-level เพื่อรับข้อมูลการแก้ไขข้อบกพร่องโดยละเอียดเพิ่มเติม ตัวอย่างเช่น opencode --log-level DEBUG

พื้นที่จัดเก็บ

opencode เก็บข้อมูลเซสชันและข้อมูลแอปพลิเคชันอื่น ๆ ไว้บนดิสก์ที่:

  • macOS/Linux: ~/.local/share/opencode/
  • Windows: กด WIN+R แล้ววาง %USERPROFILE%\.local\share\opencode

ไดเรกทอรีนี้ประกอบด้วย:

  • auth.json - ​​ข้อมูลการตรวจสอบสิทธิ์ เช่น คีย์ API, OAuth Token
  • log/ - ​​บันทึกแอปพลิเคชัน
  • project/ - ​​ข้อมูลเฉพาะโครงการ เช่น ข้อมูลเซสชันและข้อความ
    • หากโปรเจ็กต์อยู่ภายใน repo Git มันจะถูกจัดเก็บไว้ใน ./<project-slug>/storage/
    • หากไม่ใช่ repo Git มันจะถูกเก็บไว้ใน ./global/storage/

แอปเดสก์ท็อป

OpenCode Desktop รันเซิร์ฟเวอร์ OpenCode ในเครื่อง (ไฟล์ opencode-cli sidecar) ในเบื้องหลัง ปัญหาส่วนใหญ่มีสาเหตุมาจากปลั๊กอินที่ทำงานผิดปกติ แคชเสียหาย หรือการตั้งค่าเซิร์ฟเวอร์ไม่ถูกต้อง

การตรวจสอบอย่างรวดเร็ว

  • ออกจากระบบโดยสมบูรณ์แล้วเปิดแอปใหม่อีกครั้ง
  • หากแอปแสดงหน้าจอข้อผิดพลาด ให้คลิก รีสตาร์ท และคัดลอกรายละเอียดข้อผิดพลาด
  • macOS เท่านั้น: เมนู OpenCode -> โหลด Webview ใหม่ (ช่วยได้หาก UI ว่างเปล่า/frozen)

ปิดการใช้งานปลั๊กอิน

หากแอปเดสก์ท็อปขัดข้องเมื่อเปิดใช้งาน หยุดทำงาน หรือทำงานผิดปกติ ให้เริ่มต้นด้วยการปิดใช้งานปลั๊กอิน

ตรวจสอบการกำหนดค่าส่วนกลาง

เปิดไฟล์กำหนดค่าส่วนกลางของคุณแล้วมองหาคีย์ plugin

  • macOS/Linux: ~/.config/opencode/opencode.jsonc (หรือ ~/.config/opencode/opencode.json)
  • macOS/Linux (การติดตั้งเก่ากว่า): ~/.local/share/opencode/opencode.jsonc
  • Windows: กด WIN+R แล้ววาง %USERPROFILE%\.config\opencode\opencode.jsonc

หากคุณได้กำหนดค่าปลั๊กอินไว้ ให้ปิดการใช้งานชั่วคราวโดยลบคีย์ออกหรือตั้งค่าเป็นอาร์เรย์ว่าง:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

ตรวจสอบไดเร็กทอรีปลั๊กอิน

OpenCode ยังสามารถโหลดปลั๊กอินในเครื่องจากดิสก์ได้ ย้ายสิ่งเหล่านี้ออกไปชั่วคราว (หรือเปลี่ยนชื่อโฟลเดอร์) และรีสตาร์ทแอปเดสก์ท็อป:

  • ปลั๊กอินสากล
    • macOS/Linux: ~/.config/opencode/plugins/
    • Windows: กด WIN+R แล้ววาง %USERPROFILE%\.config\opencode\plugins
  • ปลั๊กอินโครงการ (เฉพาะในกรณีที่คุณใช้การกำหนดค่าต่อโครงการ)
    • <your-project>/.opencode/plugins/

หากแอปเริ่มทำงานอีกครั้ง ให้เปิดใช้งานปลั๊กอินอีกครั้งทีละรายการเพื่อดูว่าปลั๊กอินใดเป็นสาเหตุของปัญหา

ล้างแคช

หากการปิดใช้งานปลั๊กอินไม่ได้ผล (หรือการติดตั้งปลั๊กอินค้าง) ให้ล้างแคชเพื่อให้ OpenCode สามารถสร้างใหม่ได้

  1. ออกจาก OpenCode Desktop โดยสมบูรณ์
  2. ลบไดเรกทอรีแคช:
  • macOS: ตัวค้นหา -> Cmd+Shift+G -> วาง ~/.cache/opencode
  • Linux: ลบ ~/.cache/opencode (หรือรัน rm -rf ~/.cache/opencode)
  • Windows: กด WIN+R แล้ววาง %USERPROFILE%\.cache\opencode
  1. รีสตาร์ทเดสก์ท็อป OpenCode

แก้ไขปัญหาการเชื่อมต่อเซิร์ฟเวอร์

OpenCode Desktop สามารถเริ่มต้นเซิร์ฟเวอร์ภายในเครื่องของตนเองได้ (ค่าเริ่มต้น) หรือเชื่อมต่อกับเซิร์ฟเวอร์ URL ที่คุณกำหนดค่าไว้

หากคุณเห็นกล่องโต้ตอบ “การเชื่อมต่อล้มเหลว” (หรือแอปไม่เคยผ่านหน้าจอเริ่มต้น) ให้ตรวจสอบเซิร์ฟเวอร์ที่กำหนดเอง URL

ล้างเซิร์ฟเวอร์เริ่มต้นของเดสก์ท็อป URL

จากหน้าจอหลัก คลิกชื่อเซิร์ฟเวอร์ (ที่มีจุดสถานะ) เพื่อเปิดตัวเลือกเซิร์ฟเวอร์ ในส่วน เซิร์ฟเวอร์เริ่มต้น คลิก ล้าง

ลบ server.port / server.hostname ออกจากการกำหนดค่าของคุณ

หาก opencode.json(c) ของคุณมีส่วน server ให้ลบออกชั่วคราวแล้วรีสตาร์ทแอปเดสก์ท็อป

ตรวจสอบตัวแปรสภาพแวดล้อม

หากคุณตั้งค่า OPENCODE_PORT ในสภาพแวดล้อมของคุณ แอปเดสก์ท็อปจะพยายามใช้พอร์ตนั้นสำหรับเซิร์ฟเวอร์ภายในเครื่อง

  • ยกเลิกการตั้งค่า OPENCODE_PORT (หรือเลือกพอร์ตว่าง) แล้วรีสตาร์ท

Linux: Wayland / X11 issues

บน Linux การตั้งค่า Wayland บางอย่างอาจทำให้เกิดหน้าต่างว่างหรือข้อผิดพลาดของตัวประกอบ

  • หากคุณอยู่บน Wayland และแอปว่างเปล่า/crashing ให้ลองเปิดใช้งานด้วย OC_ALLOW_WAYLAND=1
  • หากสิ่งนั้นทำให้สิ่งต่าง ๆ แย่ลง ให้ลบออกแล้วลองเปิดใช้งานภายใต้เซสชัน X11 แทน

Windows: WebView2 Runtime

บน Windows OpenCode Desktop ต้องใช้ Microsoft Edge WebView2 Runtime หากแอปเปิดเป็นหน้าต่างว่างหรือไม่เริ่มทำงาน ให้ติดตั้ง/update WebView2 แล้วลองอีกครั้ง

Windows: ปัญหาด้านประสิทธิภาพทั่วไป

หากคุณประสบปัญหาประสิทธิภาพการทำงานช้า ปัญหาการเข้าถึงไฟล์ หรือปัญหา terminal บน Windows ให้ลองใช้ WSL (ระบบย่อย Windows สำหรับ Linux) WSL มอบสภาพแวดล้อม Linux ที่ทำงานร่วมกับคุณสมบัติของ OpenCode ได้อย่างราบรื่นยิ่งขึ้น

การแจ้งเตือนไม่แสดง

OpenCode Desktop จะแสดงการแจ้งเตือนของระบบเฉพาะเมื่อ:

  • การแจ้งเตือนเปิดใช้งานสำหรับ OpenCode ในการตั้งค่าระบบปฏิบัติการของคุณและ
  • หน้าต่างแอพไม่ได้โฟกัส

รีเซ็ตที่เก็บข้อมูลแอปเดสก์ท็อป (วิธีสุดท้าย)

หากแอปไม่เริ่มทำงานและคุณไม่สามารถล้างการตั้งค่าจากภายใน UI ได้ ให้รีเซ็ตสถานะที่บันทึกไว้ของแอปเดสก์ท็อป

  1. ออกจากเดสก์ท็อป OpenCode
  2. ค้นหาและลบไฟล์เหล่านี้ (อยู่ในไดเร็กทอรีข้อมูลแอป OpenCode Desktop):
  • opencode.settings.dat (เซิร์ฟเวอร์เริ่มต้นของเดสก์ท็อป URL)
  • opencode.global.dat และ opencode.workspace.*.dat (สถานะ UI เช่น เซิร์ฟเวอร์ล่าสุด/projects)

หากต้องการค้นหาไดเร็กทอรีอย่างรวดเร็ว:

  • macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (จากนั้นค้นหาชื่อไฟล์ด้านบน)
  • Linux: ค้นหาภายใต้ ~/.local/share สำหรับชื่อไฟล์ด้านบน
  • Windows: กด WIN+R -> %APPDATA% (จากนั้นค้นหาชื่อไฟล์ด้านบน)

การขอความช่วยเหลือ

หากคุณประสบปัญหากับ OpenCode:

  1. รายงานปัญหาเกี่ยวกับ GitHub

    วิธีที่ดีที่สุดในการรายงานจุดบกพร่องหรือขอคุณสมบัติคือผ่านพื้นที่เก็บข้อมูล GitHub ของเรา:

    github.com/anomalyco/opencode/issues

    ก่อนที่จะสร้างปัญหาใหม่ ให้ค้นหาปัญหาที่มีอยู่เพื่อดูว่าปัญหาของคุณได้รับการรายงานแล้วหรือไม่

  2. เข้าร่วม Discord ของเรา

    สำหรับความช่วยเหลือแบบเรียลไทม์และการสนทนาในชุมชน เข้าร่วมเซิร์ฟเวอร์ Discord ของเรา:

    opencode.ai/discord

ปัญหาทั่วไป

ต่อไปนี้เป็นปัญหาทั่วไปบางประการและวิธีแก้ปัญหา

OpenCode จะไม่เริ่มทำงาน

  1. ตรวจสอบบันทึกเพื่อดูข้อความแสดงข้อผิดพลาด
  2. ลองรันด้วย --print-logs เพื่อดูเอาต์พุตใน terminal
  3. ตรวจสอบให้แน่ใจว่าคุณมีเวอร์ชันล่าสุดด้วย opencode upgrade

ปัญหาการรับรองความถูกต้อง

  1. ลองตรวจสอบความถูกต้องอีกครั้งด้วยคำสั่ง /connect ใน TUI
  2. ตรวจสอบว่าคีย์ API ของคุณถูกต้อง
  3. ตรวจสอบให้แน่ใจว่าเครือข่ายของคุณอนุญาตการเชื่อมต่อกับ API ของผู้ให้บริการ

ไม่มีรุ่น

  1. ตรวจสอบว่าคุณได้รับการรับรองความถูกต้องกับผู้ให้บริการแล้ว
  2. ตรวจสอบชื่อรุ่นในการกำหนดค่าของคุณถูกต้อง
  3. บางรุ่นอาจต้องมีการเข้าถึงหรือสมัครสมาชิกโดยเฉพาะ

หากคุณพบ ProviderModelNotFoundError เป็นไปได้มากว่าคุณจะคิดผิด อ้างอิงแบบจำลองที่ไหนสักแห่ง ควรอ้างอิงโมเดลดังนี้: <providerId>/<modelId>

ตัวอย่าง:

  • openai/gpt-4.1
  • openrouter/google/gemini-2.5-flash
  • opencode/kimi-k2

หากต้องการทราบว่าคุณมีสิทธิ์เข้าถึงรุ่นใด ให้เรียกใช้ opencode models

ProviderInitError

หากคุณพบ ProviderInitError คุณอาจมีการกำหนดค่าที่ไม่ถูกต้องหรือเสียหาย

เพื่อแก้ไขปัญหานี้:

  1. ขั้นแรก ตรวจสอบให้แน่ใจว่าผู้ให้บริการของคุณตั้งค่าอย่างถูกต้องโดยทำตาม คู่มือผู้ให้บริการ

  2. หากปัญหายังคงอยู่ ให้ลองล้างการกำหนดค่าที่เก็บไว้:

    Terminal window
    rm -rf ~/.local/share/opencode

    บน Windows กด WIN+R และลบ: %USERPROFILE%\.local\share\opencode

  3. ตรวจสอบความถูกต้องอีกครั้งกับผู้ให้บริการของคุณโดยใช้คำสั่ง /connect ใน TUI

AI_APICallError and provider package issues

หากคุณพบข้อผิดพลาดในการโทร API อาจเนื่องมาจากแพ็คเกจผู้ให้บริการที่ล้าสมัย opencode จะติดตั้งแพ็คเกจของผู้ให้บริการแบบไดนามิก (OpenAI, Anthropic, Google ฯลฯ) ตามความจำเป็น และแคชไว้ในเครื่อง

ในการแก้ไขปัญหาแพ็คเกจผู้ให้บริการ:

  1. ล้างแคชแพ็คเกจผู้ให้บริการ:

    Terminal window
    rm -rf ~/.cache/opencode

    บน Windows กด WIN+R และลบ: %USERPROFILE%\.cache\opencode

  2. รีสตาร์ท opencode เพื่อติดตั้งแพ็คเกจผู้ให้บริการล่าสุดอีกครั้ง

การดำเนินการนี้จะบังคับให้ opencode ดาวน์โหลดแพ็คเกจผู้ให้บริการเวอร์ชันล่าสุด ซึ่งมักจะแก้ไขปัญหาความเข้ากันได้กับพารามิเตอร์โมเดลและการเปลี่ยนแปลง API

Copy/paste ไม่ทำงานบน Linux

ผู้ใช้ Linux จำเป็นต้องติดตั้งยูทิลิตี้คลิปบอร์ดตัวใดตัวหนึ่งต่อไปนี้เพื่อให้ฟังก์ชัน copy/paste ทำงาน:

สำหรับระบบ X11:

Terminal window
apt install -y xclip
# or
apt install -y xsel

สำหรับระบบ Wayland:

Terminal window
apt install -y wl-clipboard

สำหรับสภาพแวดล้อมที่ไม่มีหัว:

Terminal window
apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

opencode จะตรวจพบว่าคุณใช้ Wayland และชอบ wl-clipboard หรือไม่เช่นนั้นจะพยายามค้นหาเครื่องมือคลิปบอร์ดตามลำดับ: xclip และ xsel