技術問題（進階）

這一頁面向使用命令列、接自建模型或做整合的使用者。 如果你只是想讓它幫忙處理檔案，看常見問題就夠了。

安裝與連線

怎麼設定模型？ 啟動 CLI 後輸入 /connect，依提示選擇 provider（DeepSeek / OpenAI / 自訂）、填 API Key、 選模型、設定推理強度即可。無需手寫設定檔。

API Key 存在哪裡？會不會明文外洩？ 保存在本機 ~/.config/zqagent/，加密儲存，不會明文寫入磁碟。

支援哪些模型？ 任何 OpenAI 相容端點都可以，例如 DeepSeek、OpenAI、Ollama 或自建服務。用 /connect 的「自訂」選項，或設定 OPENAI_BASE_URL。

錯誤 Required parameter(s) missing or invalid / Responses API 呼叫失敗？ 多半是選到的模型不能用於對話。閘道的模型清單（/models）往往是「全量目錄」， 裡面還包含向量（*-embedding）、重排（*-rerank）、語音（*-asr / *-tts）、 即時（*-realtime）、圖像（qwen-image* / wan*）以及專用通道（cmaas-*）等 模型，它們不接受普通的對話請求。/connect 已把這些模型排到清單末尾並標上 ⚠️ 標記，選定後還會自動自檢一次（真的送出一筆最小請求），不通就會提示你重選。 換到清單前面的對話模型（如 qwen3.8-flash、qwen-plus、deepseek-flash）即可。

自檢失敗時給出的兩類原因：

提示	含義	處理
The product is not activated	該模型在此 API Key / 帳號下未開通（或欠費、額度用盡）	到閘道主控台開通該模型，或換已開通的模型
InvalidParameter: Required parameter(s) missing or invalid	模型名稱不被對話介面接受，或多傳了該服務不支援的參數	換對話模型；仍不行就把推理強度設為「預設」

手動驗證某個模型能不能用：

curl -s <BaseURL>/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" -H "content-type: application/json" \
  -d '{"model":"<模型名>","messages":[{"role":"user","content":"hi"}]}'

安裝錯誤 command not found 或下載很慢？ 套件發佈在公共 npm，正常情況下直接安裝即可：

npm i -g @zqagent/core

下載慢通常是網路問題，可臨時換用國內鏡像（鏡像會在發佈後自動同步）：

npm i -g @zqagent/core --registry=https://registry.npmmirror.com/

其它安裝問題見安裝。

穩定版和測試版怎麼選？ 目前公共 npm 只發佈穩定版（@latest），沒有單獨的測試版標籤，直接裝最新版即可。 見安裝。

日常使用

怎麼切換執行模式？/discuss（唯讀對話）、/plan（唯讀探索 + 計畫）、/interactive（逐次審批，預設）、 /auto（全自動，高風險）。詳見 CLI 使用。

危險操作會被直接執行嗎？ 預設互動模式下不會：寫檔案、執行命令等有副作用的操作會先彈出審批卡片，由你決定放行還是拒絕。

任務執行很久，能中途改需求嗎？ 可以。任務執行中直接輸入文字並按 Enter，會作為補充資訊在下一次迭代注入。要另起任務請先中斷。

任務卡住了怎麼中斷？ 連按兩次 ESC。

長對話會超出模型的上下文視窗嗎？ 不會。達到閾值時會自動壓縮較早的對話，保留關鍵資訊，你無需手動介入。

怎麼儲存和恢復工作階段？/sessions 列出已儲存的工作階段並選擇恢復；/clear 清空目前工作階段。

節點與主控台

怎麼讓 zqagent 一直執行、還能遠端管理？ 用 zqagent serve 常駐為節點，或安裝桌面應用程式。接入使用者中心 後即可遠端查看。步驟見啟動節點。

瀏覽器能管理節點嗎？手機呢？ 可以。節點接入後，瀏覽器開啟使用者中心即可進入節點主控台；手機瀏覽器同樣支援 （響應式版面 + PWA，可「加入主畫面」）。

在哪裡看用量和成本？ 在節點主控台的用量面板（專案首頁 token 卡，或節點詳情「監控 → 查看用量」）， 支援依時間與模型統計、匯出 CSV；帳號頁還能查看跨節點彙總。

未送出的內容會遺失嗎？ 不會。主控台的輸入框草稿會自動儲存，切換工作階段或重新整理頁面後自動回填。

工作階段中途斷網或切到背景，內容會遺失嗎？ 不會。即時事件流會斷線自動重連並補齊增量，恢復後內容不遺失、不重複。

桌面應用程式

關閉視窗後任務還在執行嗎？ 在執行。關閉視窗只是隱藏到系統匣；即使從系統匣「結束」應用程式，背景的節點服務仍由 launchd / systemd 保活。

資料存在哪？ 節點資料在系統服務的資料目錄（macOS ~/Library/Application Support/zqagent/、 Linux ~/.zqagent_data/、Windows %APPDATA%\zqagent\），與 install.sh 安裝的節點共用。 桌面偏好另存在 ~/.config/zqagent-desktop/desktop.json。詳見 桌面應用程式 → 安裝細節。

遠端控制

需要一台有公網 IP 的伺服器嗎？ 不需要。手機與 QQ 遠端都走出站連線，透過第三方中轉完成。詳見遠端控制概覽。

怎麼從手機 / QQ 使用？ 見 遠端接入 與 QQ 機器人。

擴充現有工具

怎麼讓 AI 擁有更多工具？ 透過 MCP 接入外部工具伺服器，或用 /tool add 新增執行命令的工具。詳見 MCP 與工具。