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

คอนเทนเนอร์ไม่เริ่มทำงาน

”Conflict. The container name is already in use”

Docker

docker rm -f devcontainer
docker compose up -d

Podman

podman rm -f devcontainer
podman-compose up -d

เครื่องมือ AI ไม่ทำงาน

”claude: command not found”

อิมเมจอาจล้าสมัย ดึงเวอร์ชันล่าสุดและรีสตาร์ท:

Docker

docker compose pull
docker compose up -d

Podman

podman-compose pull
podman-compose up -d

Claude แสดง “Not logged in”

entrypoint จะสร้างไฟล์ ~/.claude.json พร้อมค่า flag สำหรับ onboarding หากไม่มี:

echo '{"hasCompletedOnboarding": true}' > ~/.claude.json

Claude แสดง “Invalid API key”

ตรวจสอบว่าค่าที่ตั้งไว้จริง ๆ คืออะไร:

echo "$ANTHROPIC_API_KEY"

สาเหตุที่พบบ่อย:

• LiteLLM proxy key หายไปหรือไม่ถูกต้อง — หากคุณใช้โหมด proxy ตรวจสอบให้แน่ใจว่า LITELLM_API_KEY ใน .env มีข้อมูลรับรองของ proxy ที่ถูกต้อง จากนั้นรีสตาร์ทคอนเทนเนอร์เพื่อให้ entrypoint สามารถสร้าง ANTHROPIC_API_KEY ได้
• OAuth token หรือโหมด proxy ไม่ตรงกัน — ใช้โหมดการยืนยันตัวตนเพียงโหมดเดียว หาก CLAUDE_CODE_OAUTH_TOKEN ถูกตั้งค่าไว้ จะมีความสำคัญเหนือกว่าโหมด LiteLLM proxy

คำขอ API ล้มเหลวด้วยข้อผิดพลาด 401

ตรวจสอบว่า API key ของคุณถูกตั้งค่าอย่างถูกต้อง:

echo "$ANTHROPIC_API_KEY"

ตรวจสอบว่าใช้งานได้โดยเรียก API ไปยังผู้ให้บริการของคุณโดยตรง

Claude แจ้งว่า “model not found”

โมเดลจะถูกกำหนดโดยผู้ให้บริการและ API key ของคุณ ตรวจสอบเอกสารของผู้ให้บริการสำหรับโมเดลที่ใช้งานได้

GitHub CLI

”gh: not authenticated”

gh CLI ต้องการตัวแปรสภาพแวดล้อม GH_TOKEN เพิ่มลงในไฟล์ .env ของคุณ:

GH_TOKEN=ghp_your-token-here

สร้างโทเค็นได้ที่ github.com/settings/tokens ทั้ง Fine-grained tokens (แนะนำ) หรือ classic tokens ที่มีสิทธิ์ repo สามารถใช้งานได้ทั้งคู่ รีสตาร์ทคอนเทนเนอร์หลังจากอัปเดต .env

HTTPS git clone ล้มเหลวด้วยข้อผิดพลาด 401

เมื่อมีการตั้งค่า GH_TOKEN entrypoint จะรันคำสั่ง gh auth setup-git เพื่อกำหนดค่า git credential helper สำหรับ HTTPS หากการดำเนินการ HTTPS ล้มเหลว:

1. ตรวจสอบว่าโทเค็นยังใช้งานได้: gh auth status
2. ตรวจสอบว่า credential helper ถูกกำหนดค่าแล้ว: git config --global credential.helper
3. รีสตาร์ทคอนเทนเนอร์เพื่อรัน entrypoint ใหม่

SSH กับ HTTPS

ทั้งสองวิธีการยืนยันตัวตนสามารถใช้ร่วมกันในคอนเทนเนอร์ได้:

• SSH (SSH_PRIVATE_KEY ใน .env) — ใช้ URL แบบ git@github.com: จำเป็นหากองค์กรของคุณบังคับใช้ SSH
• HTTPS (GH_TOKEN ใน .env) — ใช้ URL แบบ https://github.com/ ตั้งค่าง่ายกว่า ไม่ต้องจัดการ key

หากกำหนดค่าทั้งสองแบบ git จะใช้โปรโตคอลที่ตรงกับ remote URL เพื่อเปลี่ยน clone ที่มีอยู่:

# SSH เป็น HTTPS
git remote set-url origin https://github.com/owner/repo.git

# HTTPS เป็น SSH
git remote set-url origin git@github.com:owner/repo.git

ปัญหาเรื่องสิทธิ์

”Permission denied” บน /workspace หรือ /home

sudo chown -R $(id -u):$(id -g) /workspace ~

npm install ล้มเหลวด้วย EACCES

entrypoint จะกำหนดค่า npm global prefix ที่ผู้ใช้สามารถเขียนได้ที่ ~/.npm-global โดยอัตโนมัติ ดังนั้นคำสั่ง npm install -g ในขณะรันไทม์ควรทำงานได้โดยไม่ต้องใช้ sudo หากคุณยังพบข้อผิดพลาด EACCES ให้ใช้การแก้ไขด้วยตนเอง:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

ปัญหาการ Build

การ Build ใช้เวลานานมาก

การ build ครั้งแรกจะดาวน์โหลด base image (~1 GB) การ build ครั้งต่อ ๆ ไปจะใช้แคช หากช้าทุกครั้ง:

Docker

docker builder prune

Podman

podman builder prune

“No space left on device”

Docker

docker system prune -a --volumes

Podman

podman system prune -a --volumes

คำเตือน: คำสั่งนี้จะลบคอนเทนเนอร์ อิมเมจ และ volume ที่ไม่ได้ใช้ทั้งหมด — ไม่ใช่เฉพาะของโปรเจกต์นี้เท่านั้น

เครือข่าย

ไม่สามารถเข้าถึงอินเทอร์เน็ตจากภายในคอนเทนเนอร์

ping -c 1 8.8.8.8
nslookup google.com
curl -I https://github.com

Docker

หาก DNS ล้มเหลว ให้เพิ่มใน /etc/docker/daemon.json บนเครื่อง host:

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

จากนั้นรีสตาร์ท Docker

Podman

หาก DNS ล้มเหลว ให้กำหนดค่า DNS ภายใน Podman machine:

podman machine ssh
sudo sh -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
exit

หรือเพิ่มการตั้งค่า DNS ใน ~/.config/containers/containers.conf บนเครื่อง host:

[containers]
dns_servers = ["8.8.8.8", "8.8.4.4"]

จากนั้นรีสตาร์ท Podman: podman machine stop && podman machine start

จอแสดงผลระยะไกล (noVNC)

หน้าจอดำใน noVNC

Xvfb อาจยังไม่เริ่มทำงาน ตรวจสอบภายในคอนเทนเนอร์:

ps aux | grep Xvfb

หากไม่ทำงาน ตรวจสอบว่า ENABLE_VNC ไม่ได้ถูกตั้งค่าเป็น false แล้วรีสตาร์ทคอนเทนเนอร์

ข้อผิดพลาด “Cannot open display” หรือ “No display”

ตัวแปรสภาพแวดล้อม DISPLAY อาจไม่ได้ถูกตั้งค่า ตรวจสอบ:

echo "$DISPLAY"

ควรเป็น :99 หากว่างเปล่า ให้เพิ่ม DISPLAY=:99 ใน .env หรือ devcontainer.json แล้วรีสตาร์ท

พอร์ต 6080 ปฏิเสธการเชื่อมต่อ

noVNC อาจไม่ทำงาน ตรวจสอบภายในคอนเทนเนอร์:

ps aux | grep -E 'novnc|websockify'

หากไม่ทำงาน ตรวจสอบว่า ENABLE_VNC เป็น true (ค่าเริ่มต้น) และตรวจสอบ log ของคอนเทนเนอร์:

Docker

docker compose logs dev | grep -i vnc

Podman

podman-compose logs dev | grep -i vnc

พอร์ต 6080 ถูกใช้งานอยู่แล้ว

เปลี่ยนพอร์ตฝั่ง host ใน docker-compose.yml:

ports:
  - "127.0.0.1:16080:6080"

Chrome DevTools MCP

Chrome remote debugging ไม่ตอบสนอง

อินสแตนซ์ Chrome ที่ใช้ร่วมกันควรทำงานบนพอร์ต 9222 ตรวจสอบภายในคอนเทนเนอร์:

# Chrome ทำงานอยู่หรือไม่?
curl http://localhost:9222/json/version

# ตรวจสอบ log ของ Chrome
cat ~/.local/share/chrome-browser/chrome.log

# ตรวจสอบ symlink
ls -la /opt/google/chrome/chrome

# รีสตาร์ท Chrome ด้วยตนเอง
. /usr/local/lib/chrome-browser.sh
start_chrome_browser

หาก symlink หายไป ให้ดึงอิมเมจล่าสุดแล้วรีสตาร์ทคอนเทนเนอร์

ข้อผิดพลาด Browser profile lock

ด้วยสถาปัตยกรรมเบราว์เซอร์ที่ใช้ร่วมกัน ข้อผิดพลาด profile lock ไม่ควรเกิดขึ้น หากพบ อาจมีกระบวนการ Chrome ที่ค้างอยู่ถือ lock ไว้:

# หยุดกระบวนการ Chrome ที่ค้างอยู่
pkill -f 'chrome.*remote-debugging-port' || true

# ลบไฟล์ lock
rm -f ~/.cache/chrome-devtools-mcp/chrome-profile/SingletonLock

# รีสตาร์ท Chrome
. /usr/local/lib/chrome-browser.sh
start_chrome_browser

เครื่องมือ chrome-devtools-mcp ซ้ำกัน

เซิร์ฟเวอร์ chrome-devtools-mcp ถูกลงทะเบียนไว้ในระดับ global ใน ~/.claude/settings.json หากคุณมี .mcp.json ระดับ repo ที่ลงทะเบียนไว้ด้วย คุณจะเห็นเครื่องมือซ้ำกัน ลบรายการ chrome-devtools-mcp ออกจากไฟล์ .mcp.json ระดับ repo:

# ตรวจสอบการกำหนดค่าระดับ repo
cat .mcp.json

ลบคีย์ chrome-devtools-mcp ออกจาก .mcp.json ระดับ repo เพื่อใช้การลงทะเบียนแบบ global

รีเซ็ตทั้งหมด

Docker

docker compose down -v
docker rm -f devcontainer 2>/dev/null
docker compose pull
docker compose up -d

Podman

podman-compose down -v
podman rm -f devcontainer 2>/dev/null
podman-compose pull
podman-compose up -d

คำสั่งนี้จะลบข้อมูลทั้งหมดใน volume คุณจะต้อง clone repo ใหม่และกำหนดค่าเครื่องมือใหม่อีกครั้ง