> ## Documentation Index
> Fetch the complete documentation index at: https://evolink.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI 安装与登录

> 环境检查、五步安装、浏览器登录、免费验证、升级及 SSH 回调

<span id="cli-install" />

## CLI 安装、登录与验证

CLI 支持 macOS、Windows、Linux，需要 **Node.js 22+**。推荐在 Agent 实际执行命令的机器和用户环境安装。普通终端用户也可按手动步骤操作。

### 让 Agent 帮您安装

把下面整段复制到当前 Agent 的**对话框**。提示词与官网介绍页一致；浏览器登录和权限确认仍由您完成。

```text theme={null}
帮我设置 EvoLink，让我可以直接在这里生成图片、视频和音频。
1. 安装 CLI：运行 `npm install -g @evolinkai/cli`。
2. 完成登录：运行 `evolink auth login`。
3. 安装配套技能：运行 `evolink skills install`。
4. 验证连接，成功后告诉我可以开始了。
```

如果 Agent 不能执行终端命令，按下面的步骤手动安装。下方 `bash` 代码块放在**终端**执行，一次完成一个步骤；不用把两套安装流程都执行一遍。

### 手动安装：按顺序完成五步

<Steps>
  <Step title="检查 Node.js 和执行环境">
    在 Agent 实际运行的机器、同一个用户下打开终端。macOS 用“终端”，Windows 可用 PowerShell 或命令提示符，Cursor 可用内置终端。

    ```bash theme={null}
    node --version
    npm --version
    ```

    **成功标志**：两条命令都显示版本，Node.js 主版本为 22 或更高。没有安装或版本太旧时，从 [Node.js 官网](https://nodejs.org/en/download)安装符合要求的版本，关闭并重新打开终端后再检查。Windows 的 WSL、远程 SSH、容器与本机是不同环境，必须在 Agent 使用的环境安装。
  </Step>

  <Step title="安装 CLI 并确认命令可用">
    ```bash theme={null}
    npm install -g @evolinkai/cli
    evolink --version
    ```

    **成功标志**：安装命令结束且没有错误，`evolink --version` 显示 CLI 版本。`-g` 表示安装到当前 Node/npm 的全局命令目录，不要求克隆 MCP 或插件仓库。若提示找不到命令、权限不足或下载超时，先处理[安装问题](/docs/cn/cli/billing#cli-install)，再继续登录。
  </Step>

  <Step title="登录 EvoLink 账户">
    ```bash theme={null}
    evolink auth login
    ```

    1. 保持这个命令运行；它会打开浏览器，或给出本次登录链接。
    2. 在浏览器登录 EvoLink，核对账户、客户端和申请的权限，再点同意。
    3. 回到原终端，等待登录命令报告完成后执行：

    ```bash theme={null}
    evolink auth status --json
    ```

    **成功标志**：返回 `authenticated: true`。CLI 自动使用系统安全凭据存储，不需要您手工创建或粘贴 API Key。浏览器完成回调后，终端仍需完成登录；余额连接将在最后一步验证。浏览器未打开、超时或 Linux 安全存储报错，见[登录排错](/docs/cn/cli/billing#login)。
  </Step>

  <Step title="安装并让 Agent 读取技能">
    ```bash theme={null}
    evolink skills install
    evolink skills status --json
    ```

    不指定 `--agent` 时，安装到 CLI 支持的全部目标技能目录；它不会替您安装这些 Agent。只用一个客户端时，可以使用下文列出的 `--agent`。

    **成功标志**：状态为 `current: true`。然后回到 Agent 对话，发送：

    ```text theme={null}
    请确认当前会话能发现并读取 evolink-cli 技能。先验证连接，不要生成媒体。
    ```

    技能指导助手查模型、读参数、报价确认、上传素材、查询任务和下载原件。它不注册原生 MCP 服务，也不替您完成登录。`assistant_discovery: not_checked` 表示 CLI 无法代替宿主确认技能加载；请让 Agent 确认，必要时刷新技能或新开对话。具体排错见[技能未加载](/docs/cn/cli/billing#skills-discovery)。
  </Step>

  <Step title="免费验证，确认可以开始">
    ```bash theme={null}
    evolink balance --json
    evolink doctor --json
    ```

    **成功标志**：余额查询返回账户数据；`doctor` 的 `ok`、`connection_verified` 和 `model_discovery_verified` 为 `true`，并且 Agent 确认能读取技能。余额为 0 也可以证明查询已连接，但生成前需要足够余额。

    安装、登录、技能和这些查询不会创建付费媒体任务。全部完成后，助手可以告诉您“可以开始了”。如果某项 `failed`，修复对应步骤再验证；不要通过生成一张图来替代免费验证。
  </Step>
</Steps>

### 只为当前 Agent 安装技能

官网提示词的 `evolink skills install` 默认覆盖支持的目标目录。只使用一个客户端时，用下列名称选择目标，命令中的 `AGENT_NAME` 替换为表格里的值：

| 客户端 | AGENT\_NAME | 技能目录 |
| - | - | - |
| Codex CLI | `codex` | `~/.agents/skills/evolink-cli` |
| Claude Code | `claude-code` | `~/.claude/skills/evolink-cli` |
| Cursor | `cursor` | `~/.agents/skills/evolink-cli` |
| OpenClaw | `openclaw` | `~/.openclaw/skills/evolink-cli` |
| Hermes | `hermes` | `~/.hermes/skills/evolink-cli` |
| Gemini CLI | `gemini` | `~/.agents/skills/evolink-cli` |
| OpenCode | `opencode` | `~/.agents/skills/evolink-cli` |
| GitHub Copilot CLI | `copilot` | `~/.agents/skills/evolink-cli` |

```text theme={null}
evolink skills install --agent AGENT_NAME
evolink doctor --agent AGENT_NAME --json
```

例如 Gemini 使用：

```bash theme={null}
evolink skills install --agent gemini
evolink doctor --agent gemini --json
```

这只说明 CLI 的技能安装目标，不保证每个宿主的所有版本都自动加载该目录。需要宿主允许命令执行并发现技能；失败时按[技能与权限排错](/docs/cn/cli/billing#skills-discovery)处理。未列出的助手可读取[Agent 可读资料](/docs/cn/cli/skills)，不要编造 `--agent` 名称。

### 更新 CLI 与技能

```bash theme={null}
npm install -g @evolinkai/cli@latest
evolink --version
evolink skills install
evolink skills status --json
```

检查 `current: true`，让 Agent 重新读取技能。个人修改默认保留；决定替换后才使用 `--replace-modified`，旧内容备份到 `~/.evolink-media/skill-backups/`。旧 `@evolinkai/media-cli` / `evolink-media` 不用于新安装。

### 查看登录或退出

只检查当前登录：

```bash theme={null}
evolink auth status --json
```

确定要退出时，单独执行：

```bash theme={null}
evolink auth logout
```

退出只撤销当前 CLI 会话；原生 MCP 的授权在对应宿主管理。切换账户前保存已有任务 ID，旧报价不能直接在新账户提交。

<span id="ssh-login" />

### Linux 与 SSH：浏览器在另一台机器

Linux 持久登录需要当前用户会话中的 **D-Bus 和已解锁的 Secret Service**。先确认这项条件；没有时会报 `credential_store_unavailable`，root 权限不能代替它。没有可用安全存储的环境，请先完成系统配置，或在具备安全存储的本机运行 CLI。

<Steps>
  <Step title="在远端开始登录并保持等待">
    ```bash theme={null}
    evolink auth login --no-browser --timeout 600
    ```

    记下终端显示的本次授权链接。`--no-browser` 只是不自动打开浏览器，仍等待回调，**不是设备码登录**。等待范围为 30–900 秒，默认 180 秒。
  </Step>

  <Step title="在本机另开终端转发回调端口">
    从本次链接的 `redirect_uri` 找到实际回调端口，用它替换两处 `CALLBACK_PORT`，并替换 `USER`、`HOST`。例如 `redirect_uri` 为 `http://127.0.0.1:54321/callback` 时，两处都填 `54321`。不要把完整授权链接发到公开聊天或日志。

    ```bash theme={null}
    ssh -N -L CALLBACK_PORT:127.0.0.1:CALLBACK_PORT USER@HOST
    ```

    保持转发终端运行。它不显示命令提示符是正常现象；端口已占用时先处理冲突，不改授权链接里的端口。
  </Step>

  <Step title="打开本次链接并在远端验证">
    在本机浏览器打开第一步的链接，登录、同意，等远端登录命令完成。在远端同一用户环境执行：

    ```bash theme={null}
    evolink auth status --json
    evolink balance --json
    ```

    成功后可以结束本次 SSH 转发。超时后重新开始登录并为新链接的实际端口建立转发；旧链接不可复用。原生 MCP 的回调由宿主自己管理，不套用 CLI 选项。
  </Step>
</Steps>

## 安装完成后

先按[首次生成流程](/docs/cn/cli/workflows#workflows)描述需求，让 Agent 查询可用模型、核对参数和费用，等您确认后提交。完整命令见 [CLI 命令参考](/docs/cn/cli/reference#cli-reference)，安装、登录、权限与下载问题见[集中排错](/docs/cn/cli/billing#faq)。

需要原生远程 MCP 或本地 stdio 时，使用[MCP 独立指南](/docs/cn/mcp/overview)，不把 CLI 登录选项套用到 MCP。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.