# Claude Code 安裝指南 — ChatCut Source: [Claude Code 安裝指南 — ChatCut]() Content index: [llms.txt]() ## Claude Code 安裝指南 從 ChatCut 的公開外掛市場安裝由 ChatCut 維護的 Claude Code 外掛，並固定到 `main`。 ## 安裝並登入 先按順序執行下面兩條安裝命令： ```text claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main claude plugin install chatcut@chatcut-inc ``` 新增外掛市場的命令會複製一個很大的倉庫，可能要等幾分鐘。把它當成長時間執行的程序，設定充足的超時時間，並持續輪詢，直到程序退出。暫時沒有輸出不代表失敗；不要只因為普通短命令的超時到了就取消。 如果這臺機器以前可能用過 ChatCut，可以先檢查是否已有獨立的 MCP 伺服器配置： ```text claude mcp get chatcut ``` 如果這條命令找到一個名稱恰好為 `chatcut` 的伺服器，請在登入前刪除舊的獨立配置： ```text claude mcp remove chatcut ``` 不要刪除 `plugin:chatcut:chatcut`；它是新安裝外掛管理的伺服器。如果 `claude mcp get chatcut` 提示不存在這個伺服器，照常繼續。 然後使用外掛的登入指令碼登入 ChatCut MCP 伺服器。 ```text sh "${CLAUDE_PLUGIN_ROOT}/skills/chatcut-plugin-basics-claude/login-chatcut.sh" > /tmp/chatcut-login.log 2>&1 & ``` 立即讀取並持續輪詢 `/tmp/chatcut-login.log`。Claude Code 會開啟 ChatCut 授權頁面。 完成身份驗證後，確認安裝結果： ```text claude plugin list claude mcp get plugin:chatcut:chatcut ``` 外掛列表中必須顯示 `chatcut@chatcut-inc` 已啟用。OAuth 成功的權威訊號是登入輸出 `Authenticated with "plugin:chatcut:chatcut"`，不能只看 `Connected`。 最後，說明 ChatCut 支援影片編輯、動效圖形，以及生成影片、配音、音樂、音效和其他專案素材。外掛工具只會在會話啟動時載入，所以請讓使用者點選 **New session**，再用自然語言發出一條點名 ChatCut 的請求，例如“使用 ChatCut 幫我……”。不要在安裝會話中嘗試呼叫 ChatCut 工具，也不要規定一條固定的提示詞。 Claude Code 的 CLI 和桌面應用共用 `~/.claude`，因此外掛和 OAuth 會話兩邊都能用，並會自動重新整理會話。 ## 排查故障 把整個設定過程當成一次連續操作。外掛只裝了一半，或裝好但尚未驗證身份，都算失敗狀態：根據下面對應的現象排查並恢復，再從中斷的步驟繼續。無法避免的瀏覽器確認、系統密碼輸入或安裝程式確認都屬於正在等待的狀態，不代表任務結束。 ### 找不到 `claude` 或版本太舊 登入命令要求 Claude Code `2.1.210` 或更高版本。檢查下面兩項能力： ```text claude --version claude mcp login --help ``` 如果當前 shell 找不到 `claude`，先檢查 `command -v claude` 和 `~/.local/bin/claude`。在 Windows 上，還要用下面的命令跨 shell 查詢： ```text powershell.exe -NoProfile -Command "(Get-Command claude -ErrorAction SilentlyContinue).Source" cmd.exe /d /c where claude ``` 找到執行檔後直接執行，不要因為某個 shell 的 `PATH` 過期或不同就重新安裝。只安裝 Claude Code Desktop，並不代表終端 CLI 一定存在。 只有在終端裡完全找不到執行檔時，才使用 Anthropic 的官方安裝程式： ```text # macOS / Linux / WSL curl -fsSL https://claude.ai/install.sh | bash # Windows PowerShell irm https://claude.ai/install.ps1 | iex ``` 如果 CLI 已存在但版本太舊，不要問使用者想用哪種升級方式。用充足的超時時間執行 `claude update`，然後重新檢查上面兩條命令。如果命令卡住、失敗，或 `claude mcp login --help` 仍不可用，執行 `npm install -g @anthropic-ai/claude-code@latest` 後再次檢查。原生更新可能需要 TTY： ```text python3 -c 'import pty,sys; pty.spawn(sys.argv[1:])' claude update ``` 如果安裝程式要求輸入系統或管理員密碼，準確說明一次需要使用者執行的操作，繼續等待，完成後自動恢復流程。如果使用代理，請在重試前設定使用者實際使用的 `HTTPS_PROXY`。 ### 新增外掛市場很慢 `claude plugin marketplace add` 會執行一次耗時較長的複製。啟動時要給大型倉庫預留充足的超時時間，並輪詢這個程序，不要反覆重新啟動。除非當前程序報錯退出，或明顯示卡住並超過充足的超時時間，否則等它自己完成。不要併發執行多次新增外掛市場。 如果程序還活著但沒有輸出，繼續等待。如果執行環境的超時時間很短，就在後臺或可長時間執行的 shell 中執行，把輸出寫入日誌，同時輪詢程序狀態和日誌；只有上一個程序退出後才能重試。 ### 新增外掛市場時網路失敗 超時、TLS/DNS 錯誤、`fatal: early EOF`，以及容易誤導人的 `fatal: Invalid path ...`，通常說明 GitHub 傳輸中斷，不是倉庫檔名錯誤。保持安裝任務繼續執行，並在重試時逐步增加等待時間。 如果使用者已有代理，就用現有代理。讀取 `HTTPS_PROXY` 和 `HTTP_PROXY`，或找出正在執行的代理工具及其實際埠；常見本地埠包括 `7890`、`7897`、`1080`、`8080` 和 `8888`，但不要隨便選一個，也不要留下錯誤的代理配置。 ```text # macOS / Linux example; substitute the user's actual proxy HTTPS_PROXY=http://127.0.0.1:7890 ALL_PROXY=http://127.0.0.1:7890 claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main # Windows PowerShell example $env:HTTPS_PROXY='http://127.0.0.1:7890'; $env:ALL_PROXY=$env:HTTPS_PROXY; claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main ``` 如果完整複製外掛市場時反覆斷線，就改用另一個長時間執行的程序做淺複製，輪詢直到完成，再新增本機路徑並安裝： ```text git clone --depth 1 --branch main https://github.com/ChatCut-Inc/agent-plugin.git claude plugin marketplace add /path/to/agent-plugin claude plugin install chatcut@chatcut-inc ``` 如果新增外掛市場時報 `program not found`，確認 `git --version`。儘量用 `brew install git`、`winget install Git.Git`、`apt-get install -y git` 或 `dnf install -y git` 非互動式安裝 Git，確保它在 `PATH` 中，然後重試。如果出現無法避免的作業系統安裝程式確認，就繼續等待。 ### 登入提示 stdin 不是終端 外掛登入指令碼會啟動自己的 PTY。按正常路徑執行它，不要直接呼叫 `claude mcp login`。 如果必須直接登入，但沒有 `python3`，請使用各平臺對應的 `script` 語法： ```text # macOS (BSD script) script -q /tmp/chatcut-login.log claude mcp login plugin:chatcut:chatcut & # Linux (util-linux script) script -qc "claude mcp login plugin:chatcut:chatcut" /tmp/chatcut-login.log & ``` 不要把一個作業系統的 `script` 用法照搬到另一個系統。 在 Windows 上，先儘量在能執行 `python3` 的 shell 中執行 PTY 包裝後的登入命令： ```text python3 -c 'import pty,sys; pty.spawn(sys.argv[1:])' claude mcp login plugin:chatcut:chatcut > /tmp/chatcut-login.log 2>&1 & ``` 如果這個 shell 無法執行 `python3` 或該命令，先確認 `cmd.exe /d /c where claude`，然後使用一個臨時的真實控制台並捕獲輸出： ```text Start-Process cmd -ArgumentList '/c','claude mcp login plugin:chatcut:chatcut > %TEMP%\chatcut-login.log 2>&1' ``` 因為輸出已重定向，控制台可能是空白的。輪詢 `$env:TEMP\chatcut-login.log`；可直接開啟的授權 URL 一齣現就立即開啟，並繼續輪詢。 ### 舊版 ChatCut MCP 伺服器和外掛衝突 使用 `claude mcp list` 區分名為 `chatcut` 的獨立伺服器和名為 `plugin:chatcut:chatcut` 的外掛託管伺服器。只用 `claude mcp remove chatcut` 刪除獨立配置，然後確認 `claude mcp get plugin:chatcut:chatcut` 仍能解析。清理時絕不能刪除帶名稱空間的外掛伺服器。 ### 登入超時或返回 5xx 如果登入輸出 `Authentication timeout`，立即執行登出命令，啟動一個全新的登入程序，顯示新的授權 URL，並繼續輪詢。絕不能同時執行多個登入嘗試。 身份驗證成功前，在 OAuth 發現、註冊、回撥處理或令牌交換期間出現 HTTP 502 或其他 5xx 響應，屬於可以重試的服務故障，不是憑據錯誤，也不需要重新安裝。等當前登入程序退出後再重試，並逐步增加等待時間；也可以檢查服務是否可用： ```text curl -fsS https://api.chatcut.io/.well-known/oauth-authorization-server ``` 在 Windows 上使用 `curl.exe`。發現端點返回成功，只能證明該端點可訪問；請繼續等待，直到登入程序輸出已通過身份驗證的那一行。 ### `claude mcp login` 不存在 按照前面的恢復步驟升級 Claude Code。偽終端包裝可以解決非互動式 shell 錯誤，所以只有 CLI 版本過舊時才需要退回到應用介面。 只有在拿到兩種升級方式都失敗的確切證據後，才能讓使用者輸入 `/mcp`，選擇 `chatcut`（`plugin:chatcut:chatcut`），再選擇 **Authenticate**。繼續輪詢 `claude mcp get plugin:chatcut:chatcut`，身份驗證可用後自動恢復流程。 ### API 或 MCP 請求返回 403 只要仍然返回 403，就暫停自動重試。保留目前的專案和本機媒體。聯絡 [team@chatcut.io](mailto:team@chatcut.io)，提供錯誤資訊、大致發生時間和時區，以及當時使用的公開 IP 位址。如果已有記錄下來的請求 ID，也請一併提供；不必為了回報問題再執行一次匯入或生成。 403 需要檢查存取規則或請求頻率限制規則，不能據此認定憑證錯誤。存取恢復後，先檢查原任務的狀態，再繼續執行。 ### 驗證結果看不懂或工具響應很慢 `claude mcp get` 可能會在 OAuth 成功前顯示 `Connected`。如果成功登入前出現 `Needs authentication`，返回登入迴圈。`Connected · tools fetch failed` 或 `Request timed out` 通常只是後端暫時響應慢；不要因此重新安裝或停止。 登入輸出確認身份驗證成功後，如果工具列表載入較慢，狀態可能會暫時變回 `Needs authentication`；新會話中的首次呼叫也可能在後端預熱時超時。對於工具探索或其他唯讀載入，可以重試，並逐步增加等待時間。如果某次逾時的工具呼叫可能已經修改專案或開始生成，請先檢查原任務的狀態，再重複呼叫。不要重新登入。只有當 ChatCut 工具反覆明確返回 `connector authentication is missing`，而不是超時，才把它當成真正的身份驗證問題。 ## 更新失敗後的恢復方法 正常的更新命令是： ```text claude plugin marketplace update chatcut-inc claude plugin update chatcut@chatcut-inc ``` 如果更新失敗，按照上面的對應方法處理 CLI、長時間執行的外掛市場操作、網路或代理問題，然後重新驗證。更新後的工具也只會在 **新會話** 中載入；不要執行 `/reload-plugins`，也不要讓使用者執行。