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

# macOS 上使用 Sub2API 的完整指南

> 在 macOS 上配置 Python 环境、设置环境变量并验证 Sub2API 连接的完整操作指南。

本教程面向 macOS 用户，介绍如何配置 Python 环境、通过 Shell 配置文件持久化 Sub2API 环境变量，并运行第一次 API 调用验证连通性。

<Steps>
  <Step title="确认 Python 已安装">
    macOS 通常预装了 Python。打开终端（Terminal.app 或 iTerm2），运行：

    <CodeGroup>
      ```bash zsh（默认） theme={null}
      python3 --version
      ```

      ```bash bash theme={null}
      python --version
      ```
    </CodeGroup>

    若未安装，可通过 Homebrew 安装：

    ```bash theme={null}
    brew install python
    ```
  </Step>

  <Step title="设置环境变量">
    根据你使用的 Shell，编辑对应的配置文件：

    <Tabs>
      <Tab title="zsh（macOS 默认）">
        打开 `~/.zshrc` 并添加以下两行：

        ```bash theme={null}
        export OPENAI_API_KEY="YOUR_API_KEY"
        export OPENAI_BASE_URL="https://sub2api.ruilinlu.com"
        ```

        保存后执行：

        ```bash theme={null}
        source ~/.zshrc
        ```
      </Tab>

      <Tab title="bash">
        打开 `~/.bashrc` 或 `~/.bash_profile` 并添加：

        ```bash theme={null}
        export OPENAI_API_KEY="YOUR_API_KEY"
        export OPENAI_BASE_URL="https://sub2api.ruilinlu.com"
        ```

        保存后执行：

        ```bash theme={null}
        source ~/.bashrc
        ```
      </Tab>
    </Tabs>

    用 `echo $OPENAI_API_KEY` 验证变量是否加载成功。
  </Step>

  <Step title="安装 openai SDK">
    推荐使用 `pip3` 安装：

    ```bash theme={null}
    pip3 install openai
    ```

    <Tip>
      建议为每个项目创建独立的虚拟环境，避免依赖冲突：

      ```bash theme={null}
      python3 -m venv venv
      source venv/bin/activate
      pip install openai
      ```
    </Tip>
  </Step>

  <Step title="运行第一次调用">
    创建 `test.py` 并运行：

    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.getenv("OPENAI_API_KEY"),
        base_url=os.getenv("OPENAI_BASE_URL")
    )

    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello from macOS!"}]
    )

    print(response.choices[0].message.content)
    ```

    执行：

    ```bash theme={null}
    python3 test.py
    ```
  </Step>
</Steps>

## 常见问题排查

<Accordion title="zsh: command not found: python3">
  macOS 某些旧版本或精简安装可能未自带 Python。请通过 Homebrew 安装：`brew install python`。
</Accordion>

<Accordion title="pip3 install 提示 Permission denied">
  不要对系统级 Python 使用 `sudo pip3 install`。推荐创建虚拟环境后安装，或使用 `pip3 install --user openai`。
</Accordion>

<Accordion title="环境变量重启终端后丢失">
  请确认你将 `export` 写入了正确的配置文件（zsh 用 `~/.zshrc`，bash 用 `~/.bashrc`），并执行了 `source` 命令。
</Accordion>

<Accordion title="调用返回 401 Unauthorized">
  请检查 `OPENAI_API_KEY` 是否已正确导出，且 Key 未被撤销。可参考 [API Key 无效排查](/troubleshooting/api-key-invalid)。
</Accordion>