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

# 终端提示找不到 apiyi 命令怎么办？

> npx apiyi@latest 是临时运行，不会安装 apiyi 命令。后续命令都带上 npx apiyi@latest 前缀，或用 npm i -g apiyi 装一次。

## 简短回答

`npx apiyi@latest` 是**临时下载、跑完即走**，不会在电脑上留下一个 `apiyi` 命令。所以接下来的每条命令都要写成 `npx apiyi@latest …`，例如保存 Key：

```bash theme={null}
npx apiyi@latest auth set-key
```

想以后直接敲 `apiyi`，就全局安装一次：`npm i -g apiyi`。

## 问题现象

第一次运行自检，提示没有 Key，照着提示敲命令却报错：

```text theme={null}
% npx apiyi@latest check
status:   no_key
node:     api.apiyi.com
hint:     No API key found. Copy one at https://api.apiyi.com/token, then run "apiyi auth set-key" or export APIYI_API_KEY.

% apiyi auth set-key
zsh: command not found: apiyi
```

Windows 上的报错文字不同（如「无法将 apiyi 项识别为 cmdlet」），原因一样。

## 原因

`npx` 会把 CLI 下载到 npm 的临时缓存里执行，**不会把 `apiyi` 加进系统 PATH**。0.2.1 及以前的版本，提示里写的是简写 `apiyi auth set-key`，照抄就会撞上这个报错。

从 **0.2.2** 起，CLI 会识别自己是不是通过 `npx` 运行的，提示里直接给出完整写法 `npx apiyi@latest auth set-key`；`--help` 也会说明这一点。

## 解决方法

<Tabs>
  <Tab title="一直用 npx（推荐，零安装）">
    每条命令前都带上 `npx apiyi@latest`，始终是最新版，不在电脑上留东西：

    ```bash theme={null}
    npx apiyi@latest auth set-key
    npx apiyi@latest check
    npx apiyi@latest chat "你好" -m gpt-5.4-mini
    ```
  </Tab>

  <Tab title="全局安装一次">
    装完以后就能直接用 `apiyi`：

    ```bash theme={null}
    npm i -g apiyi
    apiyi auth set-key
    apiyi check
    ```

    以后升级：`npm i -g apiyi@latest`。
  </Tab>

  <Tab title="用环境变量">
    不保存到本机配置文件，只在当前终端里生效：

    ```bash theme={null}
    export APIYI_API_KEY=sk-your-apiyi-key
    npx apiyi@latest check
    ```

    想长期生效，把 `export` 这一行写进 `~/.zshrc`（或 `~/.bashrc`）。
  </Tab>
</Tabs>

## 完整的首次配置步骤

<Steps>
  <Step title="复制 Key">
    打开 [令牌页面](https://api.apiyi.com/token)，复制一个以 `sk-` 开头的令牌；没有就先新建一个。
  </Step>

  <Step title="保存 Key">
    运行 `npx apiyi@latest auth set-key`，出现 `API key (input hidden):` 后粘贴并回车。
    输入时屏幕上不显示任何字符，这是为了防止 Key 被旁人看到，属于正常现象。
    看到 `Saved apiKey to ~/.config/apiyi/config.json (mode 0600)` 就是成功了。
  </Step>

  <Step title="重新自检">
    运行 `npx apiyi@latest check`，`status` 显示 `ok` 说明 Key 有效、节点连通。
  </Step>

  <Step title="发第一条消息">
    运行 `npx apiyi@latest chat "你好" -m gpt-5.4-mini`，能看到回复和 token 用量就全部跑通了。
  </Step>
</Steps>

## 常见问题

<AccordionGroup>
  <Accordion title="粘贴 Key 时屏幕没有任何反应，是不是没粘上？">
    是隐藏输入，粘贴后直接回车即可。不放心可以用 `npx apiyi@latest auth show` 查看，会打码显示已保存的 Key。
  </Accordion>

  <Accordion title="已经 npm i -g apiyi 了，还是 command not found？">
    说明 npm 的全局目录不在 PATH 里。运行 `npm prefix -g` 看全局目录，把它下面的 `bin` 子目录加进 PATH（写进 `~/.zshrc`），然后重开终端。用 nvm 管理 Node 时，切换 Node 版本后也需要在新版本下重新全局安装。
  </Accordion>

  <Accordion title="Key 存在哪里？怎么删除？">
    保存在 `~/.config/apiyi/config.json`，文件权限 0600，只有当前用户能读。删除用 `npx apiyi@latest auth clear`。
  </Accordion>

  <Accordion title="提示 Node 版本太低？">
    CLI 需要 Node 18.17 及以上。运行 `node -v` 查看版本，低于这个版本请先升级 Node。
  </Accordion>

  <Accordion title="查余额也报 no_key 或权限不足？">
    普通 `sk-` Key 读不到余额，查余额要用个人访问令牌（`nap_` 开头）：`npx apiyi@latest auth set-key --access-token`。详见 [什么是个人访问令牌？](/faq/personal-access-token)
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="AI 开发者套件 · CLI 命令行" icon="terminal" href="/developer-kit#cli-命令行">
    全部命令、Key 的查找顺序、退出码
  </Card>

  <Card title="API Key 无效怎么办？" icon="key" href="/faq/invalid-api-key">
    `check` 返回 invalid\_key 时看这里
  </Card>
</CardGroup>


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