問題排解
常見地雷與復原方式。
一次檢查容器、網路、.env、資料庫，結尾列出建議修復步驟（每個問題都配好對應的修復指令），並存一份帶時間戳的報告，開 GitHub issue 直接附上。
costaff start 因設定錯誤中止
這是 preflight 檢查在正常運作 — 它在 .env 找到致命問題（缺 API key、缺 DB URI）並印出確切修法。多數情況跑 costaff onboard 就能解（既有設定會保留為預設值）。真的要硬啟動：costaff start --no-preflight。
Bot 回「your account has not been approved」
不是壞掉 — 這是預設開啟的審核門檻。任何聊天帳號的第一句話會建立待核准身份。修法：costaff dashboard → Users → 核准新的那一列 → 再傳一次。
助理提到「quota」、「429」或「RESOURCE_EXHAUSTED」
撞到 Gemini 免費額度的每分鐘或每日上限了。沒壞、也不會被收錢 — 等一分鐘（或等每日重置）再試。常常撞到的話，用 costaff onboard 換成付費 Gemini key 或其他 provider。
Docker permission denied（Ubuntu）
症狀：docker: Got permission denied while trying to connect to the Docker daemon socket。
原因：當下 shell 還沒生效 docker group。
修法：先登出再登入，或開新 shell 跑 newgrp docker。
Port 18080 被佔用
別的服務佔走了 Manager 的 port。停掉那個服務，或在 ~/.costaff/costaff/.env 改 port：
COSTAFF_AGENT_PORT=18180
接著 costaff restart。Channel 與 Agent 的 port 是從空檔自動分配的（18090–18099 / 18100–18199），自己會閃開衝突。
costaff agent list 顯示 Agent 不健康
看容器 log：
docker logs costaff-agent-<name> --tail 50
常見原因：
- 缺 API key — 編
~/.costaff/costaff-agent/<name>/.env設好之後跑costaff agent rebuild <name>。 - Model 名稱錯 — 用
costaff agent model <name>查，改成已知可用的 model，再 rebuild。 - Port 衝突 — Agent 自動分配的 port 被佔了；先 remove 再 add。
Manager 沒抓到新 Agent
跑完 costaff agent add 後 Manager 會被重啟以重新讀取子 Agent 清單。如果沒成功，強制一次：
costaff agent restart costaff
# 或如果你改過 env var，整個 rebuild manager
docker compose -f ~/.costaff/costaff/docker-compose.yaml \
up -d --build --force-recreate costaff-agent-costaff
整個重來
costaff stop docker compose -f ~/.costaff/costaff/docker-compose.yaml down -v rm -rf ~/.costaff/workspace/* costaff start
這會清掉 Postgres volume 與所有 Agent 工作目錄，但 .env、已註冊的 Agent、channel 設定都會留下。
還是卡住
到 主 repo 開 issue，附上 costaff doctor 輸出，或寄信到 simonliuyuwei@gmail.com。