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