首次設定

source ~/.zshrc        # Ubuntu 改 ~/.bashrc
costaff onboard

精靈會問

• PostgreSQL URI — 用預設值，會走內建的 Postgres 容器。CoStaff 強制走 Postgres，不支援 SQLite。
• Model provider — Google Gemini（要 Google AI Studio key）或 LiteLLM（OpenAI、Anthropic、Ollama，任何 OpenAI 相容）。Gemini key 會即時打 Gemini API 驗證 — key 有問題當場就警告，不會拖到第一次對話才發現。
• Model 名稱 — Gemini 預設 gemini-3-flash-preview；LiteLLM 自由填。
• 語言 — 繁中、英、日、簡中。影響 Agent 回覆語言。
• 時區 — 排程與時間戳會用，例如 Asia/Taipei、America/Los_Angeles。
• 通訊軟體 — WebChat 預設已勾選（瀏覽器聊天，不用 bot token）；可再加 Telegram、Discord、LINE、Email。之後也能用 costaff channel add 再加；已部署的 channel 會保留，不會重新 clone。
• Dashboard 管理員帳號 — 操作 dashboard（costaff dashboard）的帳密。可跳過 — dashboard 第一次開啟時也會引導設定。

產出長這樣

最後的 ~/.costaff/costaff/.env 大概長這樣：

ID_SALT=<隨機 64 字元 hex>
MCP_SECRET_KEY=<隨機 64 字元 hex>
API_HEADERS_KEY=<隨機 64 字元 hex>

COSTAFF_AGENT_MODEL_PROVIDER=gemini
GOOGLE_API_KEY=<你的 key>
COSTAFF_AGENT_GEMINI_MODEL=gemini-3-flash-preview

COSTAFF_PREFERRED_LANGUAGE=Traditional Chinese (繁體中文)
TIMEZONE=Asia/Taipei

POSTGRES_USER=costaff
POSTGRES_PASSWORD=costaff_pass
POSTGRES_DB=costaff_db

重跑 onboard

隨時都能重跑。精靈會讀現有 .env 當預設值，只覆寫你真的有改的欄位。已部署的 channel 不會被動到。

精靈結束之後

結尾會顯示「next steps」面板：costaff start，然後 costaff dashboard（開 http://localhost:8501，點 Chat）。之後若有任何異常，costaff doctor 會輸出完整診斷報告，並在結尾列出建議修復步驟。