新手教學：從零到第一次對話
沒碰過 Docker、沒玩過 AI Agent？這頁全程牽著你走：每個指令、跑完應該看到什麼、要花多久、長得不一樣時怎麼辦。
總共 15–25 分鐘，大部分時間在等下載。你需要一台 Mac（macOS 12+）或 Ubuntu 機器（20.04+）、一個終端機、一個 Google 帳號。就這樣。
Manager — 你唯一對話的總管助理，負責協調其他所有人。
Agent — 專家員工（寫程式、做報表、查資料庫），Manager 派工給它們。
Channel — 你跟總管說話的門：瀏覽器頁面、Telegram bot、Discord bot。
MCP — Agent 拿工具（檔案、排程、API）時用的插座標準。
Dashboard — 瀏覽器控制台，在這裡核准使用者、看日誌。
Step 0 — 拿一把 Gemini API key （約 3 分鐘）
CoStaff 需要一個 AI 模型當大腦。最簡單的是申請一把 Google Gemini API key：
- 開 aistudio.google.com/apikey，用任何 Google 帳號登入。
- 點 Create API key（可能會先要你建一個 project — 用預設的就好）。
- 複製 key。長相是
AIzaSyD…— 39 個字元、AIza開頭的字串。 - 先貼到記事本放著，Step 2 會用到。
不會。免費額度不需要綁信用卡，也不可能默默扣款 — 超過每分鐘或每天的額度時，請求只會回 429 錯誤，等額度重置就好。個人使用 CoStaff，免費額度綽綽有餘。之後若看到助理抱怨「quota」或「429」，等一分鐘再試即可。
Step 1 — 安裝 （約 5–8 分鐘）
把這行貼進終端機：
curl -fsSL https://raw.githubusercontent.com/costaff-ai/costaff/main/install.sh | bash
你會看到一連串 ==> 進度步驟（檢查 Python、裝 Docker、clone repo、裝 CLI），最後出現這個框：
============================================ Installation complete! ============================================
接著兩種情況之一：
- 設定精靈自己跑起來了 — 很好，直接跳 Step 2。
- 它列出「manual steps」 — 通常是「先登出再登入」（Ubuntu，為了 Docker group）或「打開 Docker Desktop 等鯨魚圖示出現」（macOS 首次安裝）。照做之後執行：
source ~/.zshrc # Ubuntu 用 source ~/.bashrc costaff onboard
直接把同一行 curl … | bash 再跑一次就好 — 安裝程式是冪等的，會從斷掉的地方接著做，絕不會刪你的設定。
Step 2 — 設定精靈 （約 3 分鐘）
精靈一次問一題。每一題與建議答案如下：
| 提問 | 怎麼答 |
|---|---|
PostgreSQL URI: | 直接按 Enter — 預設值就是內建的資料庫容器。 |
Select Model Provider: | 選 Google Gemini。 |
Google API Key: | 貼上 Step 0 的 AIza… key。應該看到 ✔ Gemini API key verified.。如果說 key 被拒絕，檢查複製貼上有沒有缺字 — 現在改或之後重跑精靈都行。 |
Gemini Model Name: | 按 Enter（預設 gemini-3-flash-preview）。 |
Preferred Response Language: | 選你要的回覆語言。 |
Timezone: | 選你的時區（例如 Asia/Taipei）— 提醒會照這個時區響。 |
Select Channels to enable: | WebChat 已經幫你勾好 — 按 Enter 就好。Telegram / Discord / LINE 先跳過，之後要加只要 5 分鐘。 |
| WebChat 問登入 email、密碼、JWT secret | email + 密碼是你自己之後登入瀏覽器聊天用的，隨意設定。JWT secret 輸入一長串隨機字串即可。 |
Create the dashboard admin account now? | 選 yes，設一組帳號密碼 — 這是控制台的登入。 |
Do you want to build Docker images now? | Yes。這是最久的一段 — 3–5 分鐘的 build log 一直捲。看起來很嚇人，是正常的。 |
精靈結尾是綠色的「Setup complete — next steps」面板。之後想改任何答案，重跑 costaff onboard 就好 — 每一題都會帶出你上次的選擇當預設值。
Step 3 — 啟動全部 （首次約 2–5 分鐘）
costaff start
它會先跑 preflight 檢查驗證設定 — 缺了致命的東西會直接停下來告訴你確切修法（通常是「跑 costaff onboard」）。然後分層啟動：
🚀 Step 1: Starting Infrastructure (Postgres)... 🚀 Step 3: Starting CoStaff Manager... Waiting for 2 services to initialize... 🚀 Step 4: Starting Channel webchat... SUCCESS: CoStaff started in tiered sequence (Agents -> Manager -> Channels)!
（Step 2 要等你加了專家 Agent 之後才會出現。）確認都活著：
costaff status
每一列都該是 Up。有紅的就跑 costaff doctor — 結尾會列出建議修復步驟。
Step 4 — 打開聊天 （30 秒）
兩扇門，挑一扇：
- Dashboard 聊天 — 跑
costaff dashboard，瀏覽器開http://localhost:8501，用 Step 2 的管理員帳號登入，點側欄的 Chat。 - WebChat — 開 http://localhost:18090（WebChat 是你第一個 channel 時就是
18090；不確定就costaff channel list查），用 Step 2 設定的 email + 密碼登入。
Step 5 — 說點什麼
試試這幾句（用你設定的語言都行）：
- 「嗨，你會做什麼？」 — Manager 會自我介紹目前的能力。
- 「每天下午三點提醒我喝水。」 — 排程器接手；提醒會送回這個聊天視窗。
- 「記住我叫 Alex，職務是產品經理。」 — 跨對話記得你。
回覆通常 2–10 秒。游標在閃就是在思考。
這是預設開啟的審核門檻：任何聊天介面傳來的第一句話會建立一個待核准身份，核准前助理會拒絕執行實際工作。核准自己：costaff dashboard → Users → 找到新的那一列 → 核准。再傳一次訊息就通了。（這個機制是為了防止陌生人找到你的 Telegram bot 就能免費用你的 AI。）
完成了 — 接下來去哪
| 想要… | 去這裡 |
|---|---|
| 僱一個專家（報表、寫程式、開放資料） | 專家 Agent |
| 改用 Telegram / Discord 聊 | 通訊軟體 — 含逐步申請 token 教學 |
| 搞懂背後到底跑了什麼 | 驗證安裝 + 技術架構 |
| 看所有指令 | CLI 指令 |
| 東西壞了 | 先跑 costaff doctor，再看問題排解 |