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

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

---

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): ตัวแปรระบบจะทับทุกอย่างเสมอ

---

5. การสร้าง Subagent: เลือกใช้แบบไหนดีระหว่าง Markdown และ JSON?

คุณสามารถสร้าง Subagent เก็บไว้ในโฟลเดอร์ .opencode/agents/ ได้ทั้งสองรูปแบบ โดยมีตัวอย่างการกำหนดค่าดังนี้:

แบบที่ 1: การสร้าง Subagent ด้วยไฟล์ Markdown (.md)

ใช้ YAML Frontmatter ตั้งค่า Metadata และเขียน System Prompt ไว้ที่เนื้อหาด้านล่าง อ่านง่าย เหมาะกับ Prompt ที่มีความซับซ้อน

ตัวอย่าง .opencode/agents/coder.md:

---
name: coder
description: Expert software developer agent for writing and refactoring code
model: claude-3-5-sonnet
temperature: 0.1
tools:
  - read_file
  - write_file
  - execute_command
---

# Role and Responsibilities
You are a senior software engineer. Your main focus is to write clean, maintainable, and highly efficient code.

## Coding Guidelines
1. Always write self-documenting code with clear variable names.
2. Include unit tests for any new functions created.

แบบที่ 2: การสร้าง Subagent ด้วยไฟล์ JSON (.json)

กำหนดค่าทั้งหมดในรูปแบบ Key-Value มาตรฐาน เหมาะสำหรับ Agent ขนาดเล็ก หรือถูกสร้างโดย Script อัตโนมัติ

ตัวอย่าง .opencode/agents/reviewer.json:

{
  "name": "reviewer",
  "description": "Code review agent for checking code quality, security, and performance",
  "model": "claude-3-5-sonnet",
  "temperature": 0.2,
  "tools": [
    "read_file",
    "git_operations"
  ],
  "prompt": "You are a code reviewer. Your goal is to analyze source code for bugs, security vulnerabilities, and adherence to clean code standards. Provide constructive feedback with clear examples."
}

รูปแบบไฟล์	จุดเด่น	ข้อจำกัด
Markdown (.md)	อ่านง่าย จัด Format Prompt ยาวๆ ได้ลื่นไหลด้วย Markdown	ต้องใช้ YAML Frontmatter ที่ส่วนหัวของไฟล์
JSON (.json)	โครงสร้างชัดเจน ง่ายต่อการให้ Program/Script อ่านและสร้างไฟล์	หากมี System Prompt ยาว ต้อง Escape String (เช่น \n) ทำให้อ่านยากขึ้น

---

บทสรุป

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