Claude Code 安裝指南
從 ChatCut 的公開外掛市場安裝由 ChatCut 維護的 Claude Code 外掛，並固定到 main。
安裝並登入
先按順序執行下面兩條安裝命令：
claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main
claude plugin install chatcut@chatcut-inc新增外掛市場的命令會複製一個很大的倉庫，可能要等幾分鐘。把它當成長時間執行的程序，設定充足的超時時間，並持續輪詢，直到程序退出。暫時沒有輸出不代表失敗；不要只因為普通短命令的超時到了就取消。
如果這臺機器以前可能用過 ChatCut，可以先檢查是否已有獨立的 MCP 伺服器配置：
claude mcp get chatcut如果這條命令找到一個名稱恰好為 chatcut 的伺服器，請在登入前刪除舊的獨立配置：
claude mcp remove chatcut不要刪除 plugin:chatcut:chatcut；它是新安裝外掛管理的伺服器。如果 claude mcp get chatcut 提示不存在這個伺服器，照常繼續。
然後使用外掛的登入指令碼登入 ChatCut MCP 伺服器。
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 授權頁面。
完成身份驗證後，確認安裝結果：
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 或更高版本。檢查下面兩項能力：
claude --version
claude mcp login --help如果當前 shell 找不到 claude，先檢查 command -v claude 和 ~/.local/bin/claude。在 Windows 上，還要用下面的命令跨 shell 查詢：
powershell.exe -NoProfile -Command "(Get-Command claude -ErrorAction SilentlyContinue).Source"
cmd.exe /d /c where claude找到執行檔後直接執行，不要因為某個 shell 的 PATH 過期或不同就重新安裝。只安裝 Claude Code Desktop，並不代表終端 CLI 一定存在。
只有在終端裡完全找不到執行檔時，才使用 Anthropic 的官方安裝程式：
# 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：
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，但不要隨便選一個，也不要留下錯誤的代理配置。
# 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如果完整複製外掛市場時反覆斷線，就改用另一個長時間執行的程序做淺複製，輪詢直到完成，再新增本機路徑並安裝：
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 語法：
# 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 包裝後的登入命令：
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，然後使用一個臨時的真實控制台並捕獲輸出：
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 響應，屬於可以重試的服務故障，不是憑據錯誤，也不需要重新安裝。等當前登入程序退出後再重試，並逐步增加等待時間；也可以檢查服務是否可用：
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，提供錯誤資訊、大致發生時間和時區，以及當時使用的公開 IP 位址。如果已有記錄下來的請求 ID，也請一併提供；不必為了回報問題再執行一次匯入或生成。
403 需要檢查存取規則或請求頻率限制規則，不能據此認定憑證錯誤。存取恢復後，先檢查原任務的狀態，再繼續執行。
驗證結果看不懂或工具響應很慢
claude mcp get 可能會在 OAuth 成功前顯示 Connected。如果成功登入前出現 Needs authentication，返回登入迴圈。Connected · tools fetch failed 或 Request timed out 通常只是後端暫時響應慢；不要因此重新安裝或停止。
登入輸出確認身份驗證成功後，如果工具列表載入較慢，狀態可能會暫時變回 Needs authentication；新會話中的首次呼叫也可能在後端預熱時超時。對於工具探索或其他唯讀載入，可以重試，並逐步增加等待時間。如果某次逾時的工具呼叫可能已經修改專案或開始生成，請先檢查原任務的狀態，再重複呼叫。不要重新登入。只有當 ChatCut 工具反覆明確返回 connector authentication is missing，而不是超時，才把它當成真正的身份驗證問題。
更新失敗後的恢復方法
正常的更新命令是：
claude plugin marketplace update chatcut-inc
claude plugin update chatcut@chatcut-inc如果更新失敗，按照上面的對應方法處理 CLI、長時間執行的外掛市場操作、網路或代理問題，然後重新驗證。更新後的工具也只會在 新會話 中載入；不要執行 /reload-plugins，也不要讓使用者執行。