# Node.js 环境

部分安装方式(npm 全局安装)需要 Node.js。

> **可以跳过吗?** 如果你用 [CLI 镜像](#/cli-mirror) 的 `install.sh` 一键安装(快速开始里用的方式),装的是**独立二进制,不依赖 Node.js**,可以直接跳过本页。只有当你打算用 `npm install -g` 安装,或工具明确要求 Node 时,才需要装它。

下面以安装 **LTS(长期支持)** 版本为准。

---

## Windows

**推荐:winget 一键安装。** 打开 PowerShell,执行:

```powershell
winget install OpenJS.NodeJS.LTS
```

过程中若提示确认,输入 `Y`。也可以前往 [Node.js 官网](https://nodejs.org/zh-cn/download/) 下载安装包,双击一路下一步。

---

## macOS

**推荐:Homebrew。**

```bash
brew install node
```

没有 Homebrew 的话,到 [Node.js 官网](https://nodejs.org/zh-cn/download/) 下载 macOS 安装包安装即可。

---

## Linux

**Ubuntu / Debian:**

```bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
```

---

## 验证安装

```bash
node -v
npm -v
```

两个命令都输出版本号,即安装成功。

如果是为了安装 `claude` / `codex` / 相关 VS Code 扩展 CLI,再确认 npm 全局命令目录可执行:

```bash
npm bin -g 2>/dev/null || npm prefix -g
```

Node.js 只影响 npm 安装和本地 CLI 是否能启动,**不决定 Base URL 规则**:Claude Code 仍用不带 `/v1` 的 Anthropic 根地址;Codex/OpenAI-compatible 仍用带 `/v1` 的地址。

---

## 用 Node.js 调 OpenAI SDK

Node.js 不是 Base URL 规则的一部分。只有当你在项目里用 npm 包或 SDK 时才需要它。OpenAI SDK 接 Clomio 的最小示例:

```bash
npm install openai
export CLOMIO_API_KEY="你的 OpenAI/Codex 分组密钥"
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CLOMIO_API_KEY,
  baseURL: "https://api.clomio.ai/v1",
});

const result = await client.responses.create({
  model: "控制台里的 OpenAI/Codex 模型名",
  input: "ping",
  max_output_tokens: 16,
});

console.log(result.output_text);
```

建议把 `baseURL` 显式写出来，不要依赖 SDK 默认值或项目里残留的 `OPENAI_BASE_URL`：

```javascript
const client = new OpenAI({
  apiKey: process.env.CLOMIO_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL ?? "https://api.clomio.ai/v1",
});
```

SDK 会自己在 `baseURL` 后拼 `/responses`、`/images/*` 等具体路径，所以这里写到 `/v1` 即止；不要写成 `https://api.clomio.ai/v1/responses`。Responses 流式事件以 `response.completed` / `response.failed` / `response.cancelled` 判断结束；只有 Chat Completions SSE 才沿用 `data: [DONE]` 习惯。

排障时不要只打印 `err.message`。OpenAI SDK 错误对象通常带 `status`、`headers`、`request_id` / `_request_id` 等字段；把它们打出来，工单才能和网关 `request_id` 对上：

```javascript
try {
  const resp = await client.responses.create({
    model: "控制台里的 OpenAI/Codex 模型名",
    input: "ping",
  });
  console.log(resp.output_text);
} catch (err) {
  console.error("status:", err.status);
  console.error("request_id:", err.request_id ?? err._request_id ?? err.headers?.["x-request-id"]);
  console.error("body:", err.error ?? err.message);
  throw err;
}
```

如果要调用图片,仍用同一个 `baseURL: "https://api.clomio.ai/v1"`,但 Key 和模型要属于 OpenAI 图片能力或 Grok 图片能力。Embeddings 只用 OpenAI/Codex 分组；视频能力单独只走 Grok 分组 Key。

---

## 用 Node.js 调 Claude / Gemini REST

不想引入额外 SDK 时,Node 18+ 的 `fetch` 就能做最小验证。Claude / Anthropic-compatible 的配置根地址不带 `/v1`,但实际 HTTP 路径仍是 `/v1/messages`:

```bash
export CLOMIO_CLAUDE_KEY="你的Claude分组密钥"
```

```javascript
const resp = await fetch("https://api.clomio.ai/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CLOMIO_CLAUDE_KEY}`,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-6",
    max_tokens: 16,
    messages: [{ role: "user", content: "ping" }],
  }),
});

console.log(resp.status, resp.headers.get("x-request-id"));
console.log(await resp.text());
```

Gemini 原生入口用根地址 + `/v1beta/...`,可用 `x-goog-api-key`:

```bash
export CLOMIO_GEMINI_KEY="你的Gemini分组密钥"
```

```javascript
const resp = await fetch("https://api.clomio.ai/v1beta/models", {
  headers: { "x-goog-api-key": process.env.CLOMIO_GEMINI_KEY },
});

console.log(resp.status);
console.log(await resp.text());
```

如果你使用对应厂商 SDK,规则仍相同:Claude/Anthropic-compatible 的 base URL 写 `https://api.clomio.ai`;OpenAI-compatible/Codex/Grok 写 `https://api.clomio.ai/v1`;Gemini 原生不要写成 OpenAI `/v1/models`。

---

## 国内加速:切换 npm 镜像源

如果用 `npm install` 装依赖时很慢或超时,切到国内镜像源:

```bash
npm config set registry https://registry.npmmirror.com
```

验证:

```bash
npm config get registry
```

输出 `https://registry.npmmirror.com` 即生效。想切回官方源,把地址换成 `https://registry.npmjs.org` 再执行一次即可。

---

> 装 Node 过程中遇到报错?多半和代理环境有关,见 [故障排查](#/troubleshooting)。