Nara Switch · เอกสาร

คู่มือการใช้งาน
Nara Switch

ทุกสิ่งที่คุณต้องรู้เพื่อเริ่มต้นใช้งาน — ตั้งแต่การติดตั้งจนถึงการปรับแต่งขั้นสูง

Getting Started

เริ่มต้นใช้งาน

ติดตั้ง Nara Switch และตั้งค่า CLI ตัวแรกในไม่กี่นาที

1

ดาวน์โหลดและติดตั้ง

เลือกไฟล์ติดตั้งตามระบบปฏิบัติการของคุณ — macOS (dmg), Windows (msi) หรือ Linux (AppImage/deb)

# macOS (Homebrew)
brew install nara-switch

# หรือดาวน์โหลด dmg จากหน้า download
# แล้วลากไปที่ Applications
2

เปิด Nara Switch ครั้งแรก

เมื่อเปิดครั้งแรก ระบบจะสร้าง config เริ่มต้นและแสดงหน้าหลักที่พร้อมให้คุณเพิ่ม CLI โปรไฟล์แรก

# config ถูกสร้างอัตโนมัติที่:
# macOS:
~/Library/Application Support/nara-switch/config.json

# Linux:
~/.config/nara-switch/config.json

# Windows:
%APPDATA%\nara-switch\config.json
3

เพิ่ม CLI ตัวแรก

คลิก "Add Profile" แล้วเลือก CLI ที่ต้องการ — ใส่ API key และตั้งค่าเริ่มต้น เท่านี้ก็พร้อมใช้งาน

# หรือใช้คำสั่ง CLI:
nara-switch profile add codex
nara-switch profile set codex.key sk-xxxxx
nara-switch profile use codex
4

สลับ CLI ทันที

คลิกที่โปรไฟล์ CLI ที่ต้องการ — การตั้งค่าทั้งหมดถูกนำไปใช้ทันที ไม่ต้องปิด terminal หรือเปิดใหม่

# ดู profile ที่มีอยู่:
nara-switch profile list

# สลับ profile:
nara-switch profile use claude

# ดู profile ปัจจุบัน:
nara-switch config show | grep "default"
เคล็ดลับ

หลังจากเพิ่ม CLI เสร็จ ลองรันคำสั่งของ CLI นั้นใน terminal เพื่อยืนยันว่าการตั้งค่าถูกต้อง

CLI Profiles

เพิ่ม CLI Profiles

Nara Switch รองรับ 5 CLI หลัก และเพิ่ม CLI ภายนอกผ่าน custom profile

1

เพิ่มผ่าน GUI

เปิดหน้า "Add Profile" ในแอป — เลือก CLI จากรายการหรือเลือก "Custom" สำหรับ CLI ภายนอก กรอกชื่อ, provider, model, API key

2

เพิ่มผ่าน CLI

ใช้คำสั่ง `nara-switch profile add` เพื่อเพิ่ม profile แต่ละ CLI พร้อมกำหนด key และ model

# เพิ่ม Claude Code profile:
nara-switch profile add claude
nara-switch profile set claude.key sk-ant-xxxxx
nara-switch profile set claude.model claude-sonnet-4-6

# เพิ่ม Gemini CLI profile:
nara-switch profile add gemini
nara-switch profile set gemini.key AIzaSy...

# ดู profile ทั้งหมด:
nara-switch profile list
3

เพิ่ม CLI ภายนอก (Custom Profile)

เลือก "Custom" แล้วกำหนดเอง — ระบุ path ของ config file, รูปแบบ key, environment variables และ MCP servers

# ตัวอย่าง custom profile ใน config.json:
{
  "profiles": {
    "my-custom-cli": {
      "provider": "custom",
      "config_path": "~/.my-cli/config.json",
      "key_field": "api_key",
      "env": {
        "MY_CLI_API_KEY": "sk-xxxxx",
        "MY_CLI_ENDPOINT": "https://api.example.com"
      },
      "mcp_servers": [
        { "name": "filesystem", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] }
      ]
    }
  }
}
4

ตั้งค่าเริ่มต้นและสลับ

กำหนด profile เริ่มต้นที่ต้องการใช้ และสลับเมื่อต้องการเปลี่ยน — รองรับ per-workspace profile

# ตั้ง profile เริ่มต้น:
nara-switch profile use codex

# ตั้ง per-workspace profile:
cd ~/projects/my-app
echo "{\"default\": \"claude\"}" > .nara-switch.json

# ดู profile ปัจจุบันของ workspace:
nara-switch config show
เคล็ดลับ

คุณสามารถ import การตั้งค่าจาก CLI config เดิมได้ — Nara Switch จะอ่านไฟล์ config ที่มีอยู่และสร้าง profile ให้อัตโนมัติ

Proxy Configuration

ตั้งค่า Proxy & Failover

Nara Switch รัน proxy server ในเครื่องที่รับ request จาก AI CLI แล้วส่งต่อไปยัง provider ที่เลือก

1

เปิดใช้งาน proxy

proxy รันที่ localhost:11434 โดยค่าเริ่มต้น — เปลี่ยนพอร์ตได้ตามต้องการใน config

# เปิด/ปิด proxy:
nara-switch config set proxy.enabled true

# เปลี่ยนพอร์ต:
nara-switch config set proxy.port 8080

# ดูสถานะ proxy:
nara-switch config show | grep proxy
2

ตั้งค่า failover

เมื่อ CLI ตัวใดไม่ตอบ (rate limit, downtime, timeout) ระบบส่งต่อไปยัง CLI ตัวถัดไปในลำดับ failorder โดยอัตโนมัติ

# เปิด failover:
nara-switch config set proxy.failover.enabled true

# ตั้งลำดับ failover (ลอง codex ก่อน -> claude -> gemini):
nara-switch config set proxy.failover.order '["codex","claude","gemini"]'

# ดู failover config ปัจจุบัน:
nara-switch config show | grep failover
3

ตั้งค่า proxy สำหรับ CLI แต่ละตัว

แต่ละ CLI profile สามารถชี้ไปที่ proxy endpoint นี้ — ทำให้ request ทั้งหมดผ่าน Nara Switch

# CLI ที่รองรับ proxy endpoint:
# Codex:
export CODEX_BASE_URL=http://localhost:11434

# Claude Code:
export CLAUDE_BASE_URL=http://localhost:11434

# หรือตั้งค่าใน GUI: Settings > Proxy > Copy Endpoint
# แล้ววางใน terminal ที่ใช้ CLI
4

ทดสอบ proxy

ใช้คำสั่งต่อไปนี้เพื่อตรวจสอบว่า proxy ทำงานถูกต้อง

# ทดสอบว่า proxy รันอยู่:
curl http://localhost:11434/health
# => {"status":"ok","active_provider":"codex"}

# ดูสถิติ proxy:
nara-switch proxy stats
# => requests: 142, failover: 3, avg_latency: 1.2s
เคล็ดลับ

ถ้าพอร์ต 11434 ถูกใช้งานอยู่ ให้เปลี่ยนเป็นพอร์ตอื่นที่ไม่ชนกับบริการในเครื่องของคุณ

Usage Tracking

ติดตามการใช้งาน

บันทึกและดูสถิติการใช้งานของแต่ละ CLI ในที่เดียว — จำนวน request, token, ค่าใช้จ่าย และ latency

1

เปิด tracking

การติดตามการทำงานถูกเปิดโดยค่าเริ่มต้น — ข้อมูลทั้งหมดเก็บในเครื่องของคุณ ไม่ส่งออกไปไหน

# ดูสถานะ tracking:
nara-switch config show | grep tracking

# เปิด/ปิด:
nara-switch config set tracking.enabled true

# เปลี่ยนตำแหน่งไฟล์ log:
nara-switch config set tracking.log_file ~/my-logs/nara-usage.log
2

ดูสถิติ

เปิดหน้า Usage ในแอปเพื่อดูกราฟและตารางสถิติ — หรือใช้คำสั่ง CLI เพื่อดูข้อมูลแบบสรุป

# ดูสรุปการใช้งานวันนี้:
nara-switch usage today
# => codex:    142 req | 23.4K tok | $1.24
# => claude:    89 req | 41.2K tok | $2.10

# ดูสรุปสัปดาห์นี้:
nara-switch usage week

# ดูรายละเอียดตามวันที่:
nara-switch usage --date 2026-06-25

# Export เป็น CSV:
nara-switch usage export ~/usage-report.csv
3

ตั้งค่า budget alert

แจ้งเตือนเมื่อค่าใช้จ่ายถึงเกณฑ์ที่กำหนด — ป้องกันค่าใช้จ่ายเกินควบคุม

# ตั้ง budget รายเดือน:
nara-switch config set tracking.budget.monthly 50

# ตั้ง alert ที่ 80%:
nara-switch config set tracking.budget.alert_at 80

# ตั้ง budget แยกตาม provider:
nara-switch config set tracking.budget.per_provider.codex 20
nara-switch config set tracking.budget.per_provider.claude 30
4

ดูประวัติการ failover

ตรวจสอบประวัติการ failover — รู้ว่าเมื่อไหร่ที่ provider ตัวหลักไม่ทำงาน และถูกส่งต่อไปตัวไหน

# ดู log failover:
nara-switch failover log
# => 2026-06-26 14:23: codex -> claude (rate_limit)
# => 2026-06-26 16:45: claude -> gemini (timeout)

# ดูสถิติ failover:
nara-switch failover stats
# => total failovers: 14
# => top reason: rate_limit (8), timeout (4), downtime (2)
เคล็ดลับ

ข้อมูล tracking เก็บอยู่ในเครื่องเท่านั้น — ไม่มีข้อมูลใดถูกส่งไปยัง server ภายนอก คุณสามารถลบ log ได้ทุกเมื่อ

Best Practices

แนวทางปฏิบัติที่ดี

เคล็ดลับและคำแนะนำสำหรับการใช้ Nara Switch อย่างมีประสิทธิภาพ

1

ใช้ per-workspace profile

แต่ละโปรเจกต์สามารถมี profile ของตัวเอง — วางไฟล์ .nara-switch.json ใน root ของโปรเจกต์ แล้ว Nara Switch จะสลับให้อัตโนมัติเมื่อคุณ cd เข้าไป

cd ~/projects/frontend-app
# (Nara Switch ตรวจจับ .nara-switch.json)
# ใช้ profile "claude" โดยอัตโนมัติ

cd ~/projects/backend-api
# ใช้ profile "codex" โดยอัตโนมัติ
2

กำหนด failover order อย่างมีกลยุทธ์

เรียง provider จาก cost-effective ไปหาแพงที่สุด — ใช้ตัวที่ถูกที่สุดเป็น default และสำรองด้วยตัวที่มีความสามารถใกล้เคียงกัน

# กลยุทธ์: ใช้ codex (ถูก) -> claude (แม่นยำ) -> gemini (context ยาว)
nara-switch config set proxy.failover.order '["codex","claude","gemini"]'

# หรือใช้ตัวที่มี context มากที่สุดก่อน:
nara-switch config set proxy.failover.order '["gemini","claude","codex"]'
3

ตั้งค่า budget alert ตั้งแต่แรก

กำหนดวงเงินรายเดือนและเปอร์เซ็นต์แจ้งเตือนตั้งแต่เริ่มใช้ — ป้องกันค่าใช้จ่ายเกินโดยไม่รู้ตัว

# แนะนำ: ตั้ง budget และ alert ตั้งแต่ setup ครั้งแรก
nara-switch config set tracking.budget.monthly 100
nara-switch config set tracking.budget.alert_at 75
nara-switch config set tracking.budget.notify_email [email protected]
4

ตรวจสอบ log เป็นประจำ

ดูสถิติการใช้งานสัปดาห์ละครั้งเพื่อปรับปรุงการเลือก provider — อาจพบว่าบางตัวถูกกว่าแต่ประสิทธิภาพเทียบเท่า

# คำสั่งที่ควรใช้เป็นประจำ:

# ดูสรุปประจำสัปดาห์
nara-switch usage week

# ดู failover stats
nara-switch failover stats

# ดูค่าใช้จ่ายแยกตาม provider
nara-switch usage cost --period month

# Export ไปวิเคราะห์ต่อ
nara-switch usage export ~/nara-usage-$(date +%Y-%m).csv

ต้องการความช่วยเหลือ?

ถามคำถามใน GitHub Issues หรือดู FAQ สำหรับคำถามที่พบบ่อย

ไปหน้า FAQ GitHub Issues →