[OpenCode] คู่มือตั้งค่า OpenCode: ความแตกต่างระหว่าง Project Config และ Global Config

การจัดโครงสร้างระบบสำหรับ OpenCode ถือเป็นหัวใจสำคัญที่ช่วยให้ AI Agent ทำงานร่วมกันได้อย่างเป็นระบบ ชัดเจน และยืดหยุ่นสูง บทความนี้สรุปโครงสร้างไฟล์ทั้งหมด ทั้งระดับ Global, Project และการตั้งค่า MCP

---

1. ภาพรวมโครงสร้างระดับโปรเจกต์ (Project Directory)

ตั้งอยู่ที่โฟลเดอร์ซ่อน .opencode/ บริเวณ Root ของโปรเจกต์ สำหรับควบคุมและตั้งค่าพฤติกรรมเฉพาะโปรเจกต์นั้นๆ:

my-project/
├── .opencode/
│   ├── opencode.json        # คอนฟิกหลัก (Model, mcp, agents)
│   ├── agents/              # โฟลเดอร์เก็บ Subagents (.md หรือ .json)
│   │   ├── coder.md
│   │   └── reviewer.json
│   └── commands/            # เวิร์กโฟลว์อัตโนมัติ (/commands)
│       └── build-flow.md
├── AGENTS.md                # (Optional) สรุปบทบาทเอเจนต์ฉบับย่อ
└── src/                     # ซอร์สโค้ดของโปรเจกต์

---

2. โครงสร้างระดับส่วนกลาง (Global Directory)

ตั้งอยู่ที่ไดเรกทอรีส่วนกลางของระบบปฏิบัติการ ใช้เป็นค่าเริ่มต้นสำหรับทุกโปรเจกต์บนเครื่องเพื่อไม่ต้องคอยตั้งค่าใหม่:

ระบบปฏิบัติการ	Path ของโฟลเดอร์ส่วนกลาง
macOS / Linux	~/.config/opencode/
Windows	C:\Users\{username}\.config\opencode\

โครงสร้างภายในส่วนกลาง:

~/.config/opencode/
├── opencode.json        # คอนฟิกหลักระดับเครื่อง (API Keys, Default Models, MCP)
├── tui.json             # ตั้งค่าการแสดงผล Terminal UI
├── agents/              # Subagents ที่เรียกใช้ได้จากทุกโปรเจกต์
├── commands/            # Custom Commands ระดับ Global
└── plugins/             # ปลั๊กอินเสริมระดับ Global

---

3. การตั้งค่า MCP (Model Context Protocol) ใน opencode.json

การเชื่อมต่อกับเครื่องมือภายนอกผ่าน MCP ทั้งแบบ Local Server และ Remote Server สามารถกำหนดค่าผ่าน Key "mcp" ไว้ในไฟล์ opencode.json ได้โดยตรง:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "claude-3-5-sonnet",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "enabled": true
    }
  }
}

---

4. ลำดับความสำคัญการตั้งค่า (Configuration Priority)

เมื่อ OpenCode ทำงาน จะนำค่าคอนฟิกมารวมกัน (Merge) โดยทับซ้อนเรียงลำดับจากน้อยไปมาก ดังนี้:

1. Global Config (~/.config/opencode/opencode.json): ค่าเริ่มต้นระดับเครื่อง
2. Project Config (.opencode/opencode.json): ค่าที่ตั้งในโปรเจกต์จะทับค่า Global
3. Environment Variables (OPENCODE_CONFIG): ตัวแปรระบบจะทับทุกอย่างเสมอ

---

บทสรุป

การบริหารจัดการโครงสร้างไฟล์โดยแยกการทำงานของ Subagent ไว้ในโฟลเดอร์ agents/ และรวมค่า MCP ไว้ที่ opencode.json โดยยึดหลัก Project vs Global ช่วยให้ระบบ AI Agent ทำงานได้อย่างมีประสิทธิภาพและดูแลรักษาง่ายในระยะยาว