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，身份验证可用后自动恢复流程。

验证结果看不懂或工具响应很慢

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，也不要让用户运行。