10. AI bot

本章是給伺服器的 owner 與 admin 使用，涵蓋 AI 機器人服務的三個設定分頁：總覽、工具管理、使用紀錄。點分頁列右側的齒輪圖示（提示「使用者設定」）打開設定面板後，左邊的設定分組清單裡有一個「AI 設定」分組，分組標題旁緊接著一個「試驗功能」標籤。分組內由上往下排著「總覽」、「工具管理」、「使用紀錄」三個分頁，本章逐一說明。owner 與 admin 看到的內容完全一致。

此功能仍在實驗階段，介面與行為可能在未來版本變動。生產環境請審慎評估後再啟用。

整章三個分頁用來設定 AI 機器人服務、查看它的使用情況；本章描述你在介面上看得到、點得到的東西。

10.1 總覽

「總覽」是「AI 設定」分組的第一個分頁，進入後內容頁頂端標題是「AI 設定」。分頁由上往下排著六個區塊，每個區塊是一張卡片，卡片標題依序是：一般、API 金鑰、機器人、限制、系統提示詞、Bash 執行。其中「Bash 執行」卡片只對持有「管理員」權限的人顯示（owner 與 admin 一律包含在內；權限見 §4.3）。

這六個區塊共用兩種儲存方式，先在這裡交代一次。需要填字或挑選的欄位，改完內容後按欄位旁的「儲存」按鈕才寫入；沒改動、或正在儲存時這顆按鈕按不下去，按下成功後按鈕文字會暫時變「已儲存」，再變回「儲存」。開關類欄位則不一樣，按一下就切換並立即生效，不必另外按儲存。

請一次改一欄、改完就按它旁邊的「儲存」：只要任何一欄儲存成功（切換開關也算），其他欄位還沒儲存的改動都會換回已儲存的內容。

一般

卡片標題「一般」，內含「AI 啟用」、「供應商」、「模型」三項；「供應商」選「OpenRouter」時，下方再多出 OpenRouter 專用的三項（見下方）。

「AI 啟用」是一顆開關，旁邊說明文字寫著「啟用或停用 AI 機器人服務。」按一下就切換並立即生效。

「供應商」是一個下拉，四個選項：「Anthropic」、「OpenAI」、「Google Gemini」、「OpenRouter」，預設選「Anthropic」。挑好後按旁邊的「儲存」寫入。

AI 機器人要「AI 啟用」開著，而且目前儲存的供應商已經在「API 金鑰」卡片存好金鑰，才會運作。把供應商換成還沒存金鑰的那一家並儲存後，AI 機器人會停止回覆，等你存好這家的金鑰就自動恢復。

「模型」決定 AI 機器人使用哪個模型。模型欄跟著「供應商」下拉目前選的那一家，有兩種填法：

• 從清單選模型：這家供應商已經在「API 金鑰」卡片存好金鑰時（OpenRouter 不必先存金鑰），模型欄會載入這家提供的模型清單，載入期間欄位下方顯示「載入模型清單中…」，完成後變成下拉清單。挑好後按旁邊「儲存」。
• 手動填寫模型 ID：模型清單出現後，模型欄右上角有一行小字「手動輸入」，按下後下拉清單換成單行文字輸入框，可以直接填入模型 ID，再按旁邊「儲存」；按「從清單選擇」換回清單。清單裡找不到要用的模型時，用這個方式。

下拉清單裡：

• 第一個選項是「供應商預設（…）」，括號裡是這家供應商的預設模型：Anthropic 為「claude-sonnet-4-20250514」、OpenAI 為「gpt-4o」、Google Gemini 為「gemini-2.0-flash」、OpenRouter 為「z-ai/glm-5.3-flash」。選它並儲存，就是不指定模型，由伺服器使用括號裡的模型。
• 清單較長時，上方多一個「篩選模型…」輸入框，輸入模型 ID 或名稱的一部分就能縮小清單。
• OpenRouter 的清單依模型 ID 開頭的廠商名稱分組（例如「z-ai」），而且只列出支援工具呼叫的模型。
• 目前的模型設定不在這家的清單裡時，會多一個「目前設定：…（不在清單中）」選項。這個設定會保留：在你重新挑選並儲存之前，AI 機器人會繼續以這個模型送出請求。換了供應商之後，原本的模型通常不在新的清單裡，這時就會看到這個選項；請重選這家的模型，或選「供應商預設」。

模型欄以單行文字輸入框出現的另外兩種情況：

• 這家供應商還沒存 API 金鑰時，下方提示「先儲存此供應商的 API 金鑰，即可從模型清單選擇。」在「API 金鑰」卡片按「儲存」寫入金鑰後，清單才會出現。
• 清單載入失敗時，下方提示「無法載入模型清單（…），請手動輸入模型。」括號裡是失敗的原因。

文字輸入框留空後儲存，效果和選「供應商預設」相同。換供應商時，先按「供應商」旁的「儲存」，再挑模型並按「模型」旁的「儲存」。選好模型後，可以用「API 金鑰」卡片的「測試」確認能連線（見下方「API 金鑰」）。

「供應商」下拉選「OpenRouter」時，模型欄下方多出以下三項：

• 一行說明：「OpenRouter 的模型 ID 格式為 vendor/model（例如 z-ai/glm-5.3-flash）。請選擇支援工具呼叫的模型，「測試」按鈕會一併檢查。」
• 「推理強度（OpenRouter）」：一個下拉，說明文字寫著「推理型模型每次回覆可以思考多少。思考會計入最大 Token 數與 120 秒回覆逾時；「低」能讓回覆維持快速。」四個選項：「模型預設」、「低」、「中」、「高」，預設為「低」；選「模型預設」時，思考多少由模型自己決定。挑好後按旁邊「儲存」。
• 「拒絕資料蒐集（OpenRouter）」：一顆開關，預設關閉，旁邊說明文字寫著「只路由到不保留提示詞、也不拿提示詞訓練的供應商。部分模型可能因此無法使用。」按一下就切換並立即生效。

API 金鑰

卡片標題「API 金鑰」，提供四個金鑰欄與一顆測試按鈕。

四個金鑰欄由上往下是「Anthropic API 金鑰」、「OpenAI API 金鑰」、「Gemini API 金鑰」、「OpenRouter API 金鑰」。四欄都是遮蔽輸入框，輸入時顯示圓點不顯示明文，預先填入的提示是一串圓點「••••••••」。每欄旁邊各有一顆「儲存」按鈕寫入該欄。只需要填「一般」卡片選用的那一家，其他欄可以留空。

最下方一顆「測試」按鈕用來確認連線。按下後文字會變「測試中…」。連得上時旁邊以成功色顯示「連線成功！」；連不上時以紅色顯示「連線失敗」，後面接一個冒號與一段錯誤訊息，告訴你這次失敗的原因。

「測試」用的是「一般」卡片目前選的供應商、「模型」欄目前的內容，以及這家供應商的金鑰欄：欄位裡剛輸入、還沒儲存的金鑰也能先測，沒改動時則用已儲存的金鑰。供應商為 OpenAI、Google Gemini 或 OpenRouter 時，模型欄空白（選「供應商預設」）就以這家的預設模型測試。供應商為 Anthropic 時，請先在「模型」挑選清單中「供應商預設」以外的模型，或在文字輸入框填入模型 ID，再按「測試」。供應商選 OpenRouter 時，「測試」會套用已儲存的「推理強度（OpenRouter）」與「拒絕資料蒐集（OpenRouter）」設定，並一併檢查模型是否支援工具呼叫；檢查沒過時同樣顯示「連線失敗」與原因。

機器人

卡片標題「機器人」，內含兩項。

「機器人名稱」是一個單行文字輸入框，預先填入的提示是「hako-ai」。改完名字後按旁邊「儲存」寫入。

「成員存取」是一顆開關，旁邊說明文字寫著「允許非管理員成員使用 AI 機器人。」按一下就切換並立即生效。這顆開關預設關閉；關閉時，能和 AI 機器人對話的只有持有「管理員」權限的人（owner 與 admin 一律包含在內），其他人傳訊息給 AI 機器人，會收到它回覆的「⚠️ AI access is restricted to admins and owners.」。打開後，所有成員都能和 AI 機器人對話；它替成員做事時能用哪些工具，見 §10.2。

限制

卡片標題「限制」，提供四個數字輸入框，每個都可填的最小值是 1，各帶預先填入的提示與一顆「儲存」按鈕。

由上往下四欄是：「上下文訊息數」（提示「50」）、「最大 Token 數」（提示「4096」）、「每日 Token 限額」（提示「100000」）、「頻率限制」（提示「10」）。改完任一欄按該欄旁的「儲存」寫入。

四欄的意思：

• 「上下文訊息數」：AI 機器人每次回覆時，參考這段私訊最近的幾則訊息（含它自己的回覆）。
• 「最大 Token 數」：AI 機器人每次呼叫模型時，回覆長度的上限（以 token 計）。
• 「每日 Token 限額」：整個伺服器（不分成員）每天的 token 用量上限，以 UTC 午夜換日；AI 機器人停止後再恢復運作時（例如伺服器重新啟動，或「AI 啟用」關掉再打開），當天的用量會重新計算。AI 機器人每次呼叫模型前都會檢查用量；達到上限後，成員再傳訊息給 AI 機器人，會收到它回覆的「⚠️ Daily token limit reached. AI will be available again tomorrow.」。
• 「頻率限制」：每位成員一分鐘內最多能讓 AI 機器人處理幾則訊息；超過時，會收到它回覆的「⚠️ Rate limit exceeded. Please wait a moment before sending another message.」。

被「每日 Token 限額」或「頻率限制」擋下的使用，都會記在「使用紀錄」，狀態為「被擋下」（見 §10.3）。

系統提示詞

卡片標題「系統提示詞」。這裡是一個較高的多行文字框（約 8 行），可以上下拉高來填入給 AI 機器人的系統提示詞。

下方兩顆按鈕。「儲存」把目前內容寫入，沒改動時按不下去。「重置為預設」按下後會跳出系統確認對話框，內文寫著「確定要將系統提示詞重置為預設值嗎？」按確認後把系統提示詞清空並儲存。

Bash 執行

卡片標題「Bash 執行」，只對持有「管理員」權限的人顯示（owner 與 admin 一律包含在內）。最上方是一顆總開關「Bash 執行」，旁邊說明文字寫著「允許 AI 機器人在伺服器上執行 Bash 指令。」按一下就切換並立即生效。開啟後，AI 機器人只在 owner 本人和它對話時才會執行 Bash 指令。

開啟「Bash 執行」開關後，下方會出現以下四項。

「Bash 模式」是一個下拉，三個選項：「Confirm」（預設）、「Whitelist」、「Blacklist」。挑好後按旁邊「儲存」寫入。

「允許 Sudo」是一顆開關，旁邊說明文字寫著「允許 AI 機器人使用 sudo 執行指令。」按一下就切換並立即生效。

「Bash 逾時 (秒)」是一個數字輸入框，預先填入的提示是「30」，可填 5 至 300 秒。改完後按旁邊「儲存」寫入。

「Bash 白名單」標籤下一行說明寫著「以逗號分隔的允許指令列表。」下方是一個多行文字框（約 3 行，可拉高），填入允許的指令後按旁邊「儲存」寫入。

10.2 工具管理

「工具管理」是「AI 設定」分組的第二個分頁，進入後內容頁頂端標題是「工具管理」。整個分頁是單一一張卡片。

卡片標題「工具管理」右側有一行計數，呈現目前已啟用的工具數與總數，後接「啟用中」（例如「3/8 啟用中」）。標題下方說明寫著「切換 AI 機器人可使用的工具。停用的工具將無法被機器人使用。」

說明下方是一份工具清單，每個工具一列。每一列左邊是工具名稱，名稱下方一行較小的工具說明（過長會截斷）；右邊是一顆開關，按一下就切換這個工具的啟用或停用。切換進行中該開關會半透明、暫時按不下去，待這次切換完成後恢復。

工具清單在 AI 機器人運作時才會列出（運作的條件見 §10.1「一般」）；其他時候清單是空的，計數顯示「0/0 啟用中」。「bash_execute」這一列只在 §10.1 的「Bash 執行」開關打開後出現；它的開關只有持有「管理員」權限的人能切換，其他人看到的開關是半透明、按不下去的。

AI 機器人替某位成員做事時，只會使用開著、而且那位成員本身有權限做的工具，例如建立或修改頻道需要「管理頻道」權限；每次使用工具前都會重新確認權限。「delete_channel」、「kick_user」、「bash_execute」三個工具只在 owner 本人和 AI 機器人對話時使用。

10.3 使用紀錄

「使用紀錄」是「AI 設定」分組的第三個分頁，進入後內容頁頂端標題是「AI 使用紀錄」。這一頁記錄誰在什麼時候使用了 AI 機器人：AI 機器人運作期間（見 §10.1「一般」），它每處理一則成員傳來的私訊，就記為一次使用，包括被「頻率限制」、「每日 Token 限額」或「成員存取」擋下的那些。

頁面由上往下是：時間範圍與篩選、摘要卡片、用量圖表、排行、逐筆紀錄、逐筆紀錄保留；伺服器裡還留有使用紀錄功能加入之前的工具呼叫紀錄時，最下方另有一個收合區塊。

時間範圍與篩選

最上方一張卡片，左上角的說明寫著「誰在什麼時候使用了 AI 助理，用了哪個供應商的哪個模型。成員傳給 AI 的訊息不會被記錄；工具呼叫會連同參數與結果一起顯示。」右上角有兩顆按鈕：

• 「重新整理」：重新讀取摘要、圖表、排行與逐筆紀錄。
• 「匯出 CSV」：依目前的時間範圍與篩選（包括「逐筆紀錄」的「狀態」），把逐筆紀錄下載成 CSV 檔，新的在前，檔案裡的時間以 UTC 記錄。符合條件的紀錄太多時，只會匯出最新的一部分，並提示「只匯出了最新的 10,000 筆。縮小時間範圍，才能匯出其餘紀錄。」匯出失敗時顯示「無法匯出使用紀錄。」

「時間範圍」下方一排按鈕：「今天」、「7 天」、「30 天」、「90 天」、「全部」、「自訂」，進入時選的是「7 天」；「7 天」、「30 天」、「90 天」都含今天。選「自訂」會多出「起」與「迄」兩個日期欄，日期不合理時提示「請選擇有效的日期範圍：2000-01-01 以後，且起日不晚於迄日。」時間範圍這一區的最下方，一行小字寫著「日期以 UTC 計算，與每日 token 上限的換日時間相同。」

再往下是「成員」、「供應商」、「模型」三個下拉，預設都是「全部」；選了之後，摘要、圖表、排行與逐筆紀錄都只看符合的資料。供應商以英文代號顯示，例如「openrouter」。

資料讀取失敗時，這張卡片會顯示「無法載入使用紀錄。」

摘要卡片

篩選下方一排摘要卡片：

• 「使用次數」：這段期間的使用次數，包括失敗與被擋下的。
• 「Token」：輸入與輸出的 token 合計，下方小字寫著「輸入 … · 輸出 …」。
• 「使用成員」：這段期間有使用紀錄的成員人數。
• 「失敗 / 被擋」：失敗次數與被擋下次數，中間以「/」隔開；兩種狀態的意思見下方「逐筆紀錄」。

這段期間有 OpenRouter 回報費用的使用時，下方多一張「費用（OpenRouter）」卡，以美元顯示費用，卡內附註「只有 OpenRouter 會回報每次呼叫的實際費用，其他供應商只顯示 token。」

用量圖表

摘要卡片下方是用量長條圖。標題依時間範圍長短顯示「每日用量」、「每週用量」或「每月用量」；範圍較長時，一根長條代表一週或一個月。右上角可以切換長條顯示「使用次數」或「Token」。

長條依模型分色，有兩個以上的模型時附圖例，用量較少的模型合併為「其他」。

把滑鼠移到長條上，可以看到那段時間的數值。這段期間沒有資料時，顯示「這段期間沒有使用紀錄。」

排行

有資料時，圖表下方有兩張卡片：「用量最多的成員」與「模型」。每一列是一位成員或一個模型（模型下方一行小字是供應商代號），後面接使用次數「… 次」與 token 數「… token」。

逐筆紀錄

「逐筆紀錄」卡片列出這段期間的每一次使用，新的在上。標題列右側的「狀態」下拉有「全部」、「已回覆」、「失敗」、「被擋下」、「進行中」五個選項，只影響這張卡片的清單與「匯出 CSV」，上方的摘要、圖表與排行維持不變。

四種狀態的意思：

• 「已回覆」：AI 機器人完成了回覆。
• 「失敗」：AI 機器人沒能完成回覆，例如供應商回傳錯誤；供應商的內容審核擋下訊息、回應逾時，也算在這一類。
• 「被擋下」：HakoSpace 自己的限制擋下了這次使用，包括成員超過「頻率限制」、伺服器達到「每日 Token 限額」、「成員存取」沒有開放給這位成員，或對話進行中成員被移除、失去使用權限。
• 「進行中」：AI 機器人還在處理。

每一列由左到右是：時間（依你裝置的時區顯示）、成員名稱、供應商與模型（中間以「·」隔開）、這次用掉的 token 數，以及狀態。帳號已刪除的成員顯示為「已刪除的成員」，後面括號裡是一段識別碼。沒有符合條件的紀錄時顯示「沒有符合條件的使用紀錄。」；清單底部出現「載入更多」時，按下去可以繼續往下列出。

點任一列就會展開，先是一行摘要，例如「呼叫模型 2 次 · 工具 1 次」，後面接輸入與輸出的 token 數、費用（有回報時）與耗時。失敗或被擋下的使用，下一行寫出原因；失敗時，原因後面可能還會接上錯誤代碼與錯誤訊息。原因有以下幾種：

• 被擋下：「成員超過每分鐘的次數上限。」、「已達伺服器每日 token 上限。」、「AI 未開放給這位成員。」、「中途停止：成員已被移除或失去 AI 使用權限。」
• 失敗：「供應商回傳錯誤。」、「HakoSpace 無法準備這次請求。」、「工具呼叫輪數達上限而停止。」、「回覆完成前伺服器重新啟動了。」

再往下，依發生的先後列出這次使用的每一步：

• 每次呼叫模型各一格，標題為「第 1 次呼叫模型」、「第 2 次呼叫模型」……，旁邊是實際回應的模型與耗時；用 OpenRouter 時，另外顯示「由 … 提供」，也就是 OpenRouter 這次實際交給哪一家處理。下方是「輸入 … / 輸出 …」的 token 數，有的話再列出「快取 …」、「推理 …」（分別算在輸入與輸出裡）、費用與「結束原因：…」，最下面一行是「回應 ID …」。
• 每次呼叫工具各一列，顯示工具名稱、參數摘要、耗時與時間；點一下展開，可以看到這次呼叫的「參數」與「結果」。

沒有呼叫過模型的使用（例如被「頻率限制」或「成員存取」擋下的），展開後顯示「沒有呼叫模型。」；詳細資料讀取失敗時，顯示「無法載入這次使用的詳細資料。」

逐筆紀錄保留

逐筆紀錄下方一張卡片。「逐筆紀錄保留」下拉有「30 天」、「90 天」、「180 天」、「365 天」四個選項，預設為「90 天」，選了就儲存：成功時顯示「已儲存。」，失敗時顯示「無法儲存保留期限。」下拉下方的說明寫著「超過期限的逐筆紀錄會自動刪除；總數、圖表和排行仍會把它們算進去。」

把期限改短時，會先跳出系統確認對話框，例如改成 30 天時寫著「確定只保留 30 天？超過 30 天的逐筆紀錄會在下次每日清理時刪除，無法復原。」按確認後才會儲存。這個期限也套用到下方「使用紀錄功能加入前的工具呼叫」。

使用紀錄功能加入前的工具呼叫

伺服器裡還留有使用紀錄功能加入之前的工具呼叫紀錄時，頁面最下方會多一個可以收合的區塊「使用紀錄功能加入前的工具呼叫」。點開後先是一行說明「這些工具呼叫記錄於本功能加入之前，無法歸到個別的使用次數下，會隨保留期限自動刪除。」下面列出最近的這類紀錄，每一列顯示工具名稱、參數摘要、成員、耗時與時間，點一下可以展開看「參數」與「結果」。這個區塊不受上方的時間範圍與篩選影響。