# @cartanova/qgrid-cli 中文文档

规范地址：https://npmcn.com/package/%40cartanova/qgrid-cli/

版本：2\.18\.0
npm 元数据更新时间：2026-11-09T06:58:06.835Z
中文译文更新时间：2026-11-09T05:51:54.887Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cartanova/qgrid-cli
原文对照：https://npmcn.com/package/%40cartanova/qgrid-cli/?lang=original
源码仓库：https://github.com/cartanova-ai/qgrid

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：11.7 MB，592 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：23 个
- 首次发布：2026-04-13T05:10:07.374Z
- 最新版本发布：2026-11-09T06:58:06.451Z
- 近 30 天下载量：5718（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：125（近 12 个月 125 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @cartanova/qgrid-cli
```

也可以使用：`pnpm add @cartanova/qgrid-cli`、`yarn add @cartanova/qgrid-cli`、`bun add @cartanova/qgrid-cli`

## README

# @cartanova/克格丽德-克利

**联合国** • 妇女 [한국어](https://npmcn.com/package/%40cartanova/qgrid-cli/README.ko.md)

用一行运行 Qgrid 服务器 。 一个LLM代理将OpenAI/Anthropic订阅信用披露为HTTP API+仪表板.

## 安装

```bash
npm i -g @cartanova/qgrid-cli
```

安装还自动同步 qgrid 技能 :

-   全局安装 : `~/.codex/skills/qgrid`, (中文(简体) ), `~/.claude/skills/qgrid`
-   项目安装 : `.agents/skills/qgrid`, (中文(简体) ), `.claude/skills/qgrid`

工程安装会创建并联,当并联失败时会倒回复制.

## 正在准备 PostgreSQL

Qgrid需要PostgreSQL来存储OAuth令牌并请求日志. 如果您已经有一个可到达的 PostgreSQL,请与 `--db` 或 `QGRID_DB_*` 环境变量. 如果本地没有,你可以和多克一起旋转:

```bash
docker run --name qgrid-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=qgrid \
  -p 5432:5432 \
  -d postgres:18
```

## 使用量

```bash
# Run with a DB URL
qgrid --db postgres://user:password@host:port/dbname

# Specify a port
qgrid --db postgres://... -p 3000

# Configure the DB with environment variables (flags can be omitted)
export QGRID_DB_HOST=dev.example.com
export QGRID_DB_PORT=5432
export QGRID_DB_USER=postgres
export QGRID_DB_PASSWORD=postgres
export QGRID_DB_NAME=qgrid
qgrid
```

CLI翻译公众 `QGRID_DB_*` 设置到索纳穆的内部 `SONAMU_DB_*` 变量。 包装的 CLI 默认为 `NODE_ENV=production`· ; 设定 `NODE_ENV=staging` 只当它被故意作为遥控器运行 非生产服务。 此配置选择从未创建或重命名为 数据库 `QGRID_DB_NAME`。包装的 CLI 拒绝 `development` 财务报告和审定财务报表 `test`,需要源发展布局.

一旦服务器打开,打开仪表盘 `http://localhost:44900` —通过OAuth登录注册符. 与 `-p, --port` 设置,在端口连接.

服务器端口仅由默认确定 `44900` 或者说 `--port`编辑 `PORT` 环境变量不读取为 CLI 服务器端口输入. 如果选中的端口已经在使用中,则CLI会以出错退出,而不是杀死已存在的进程或倒回另一个端口.

停止使用 Ctrl+C.

## 选项

```
qgrid [options]

  --db <url>         PostgreSQL connection URL
  -p, --port <port>  Server port (default: 44900)
  --skip-update      Skip the automatic update check
  -V, --version      Print version
  -h, --help         Help
```

在启动时,CLI会检查npm上的最新版本和每当安装版本不同时的自更新,包括补丁发布. 更新器安装它刚刚解决的准确的已公布版本,并从更新的二进制中重新启动.

## 环境变量

没有 `--db` 旗下, DB 连接信息读取自 :

| 变量 | 默认 |
| --- | --- |
| `QGRID_DB_HOST` | `localhost` |
| `QGRID_DB_PORT` | `5432` |
| `QGRID_DB_USER` | `postgres` |
| `QGRID_DB_PASSWORD` | `postgres` |
| `QGRID_DB_NAME` | `qgrid` |
| `SLACK_BOT_TOKEN` | \- (未设置禁用符号过期通知) |
| `SLACK_CHANNEL_ID` | —— 说 |
| `SLACK_EXPIRY_REMINDER_INTERVAL_MINUTES` | \-(未设置禁用会话 - 重复) |
| `SLACK_USER_MAP` | —— (中文(简体) )`tokenName:SlackUserId` (对) |

服务器行为变量 :

| 变量 | 说明 | 默认 |
| --- | --- | --- |
| `NODE_ENV` | 索纳穆运行时间简介. 设定 `staging` 用于远程非生产部署 | `production` |

## 先决条件

-   节点.js 22
-   邮递SQL
-   多克( 如果在本地运行 PostgreSQL 作为容器)
-   [克劳德代码](https://www.anthropic.com/claude-code) (用于Anthropic模型)

## 如何运作

CLI将基于Sonamu的服务器作为内置的捆绑船. 发射时:

1.  校验 DB 连接
2.  启动服务器( API + 仪表板网络 UI)
3.  从 DB 装入注册符 。 以后通过 PostgreSQL UNSTEN/NOTIFY 实时向运行中的服务器传播符号添加/更改
4.  **OpenAI 令牌**: 调用 `https://chatgpt.com/backend-api/codex/responses` 直接通过HTTPS并解码SSE. 托肯级并行许可使用平滑加权路由;50个项目排队最多等待60秒. 完整历史被不透明地重放 `sessionKey`\- 产生的快切亲和,和 `AbortSignal` 取消已队列或活动的工作
5.  **炭相符号**:每个请求产生一个新鲜的、孤立的 claude 过程(`stream-json` (b) 将有关费用列入/列入) 托肯被选为使用最少的先行. OAuth 令牌自动刷新
6.  超过其配额阈值(默认为 80%) 的被排除于路由( 使用- 检查失败无法打开)

Qgrid应用本身并不依赖于多克克克,但PostgreSQL是需要的. 如果不在当地运行PostgreSQL,在多克运行是最简单的设置.

OpenAI 登录使用直接的 PKCE OAuth, 配额检查使用私人 `wham/usage` 直接用 Codex CLI 身份头来结尾. 这些 ChatGPT 后端接口没有记录,可能不经通知而更改. 模拟测试不能确定现场提供者的兼容性.

## SDK 整合

服务器运行后,请使用 [`@cartanova/qgrid-ai-sdk`](https://npmcn.com/package/%40cartanova/ai-sdk/README.md)数字 :

```typescript
import { generateText } from "ai";
import { qgrid } from "@cartanova/qgrid-ai-sdk";

const { text } = await generateText({
  model: qgrid("openai/gpt-6-luna"),
  prompt: "What's the weather in Seoul?",
});
```

见 [`@cartanova/qgrid-ai-sdk` 读取](https://npmcn.com/package/%40cartanova/ai-sdk/README.md) 详细情况.

## 常见问题

### 如何安装 @cartanova/qgrid-cli？

在项目目录运行 npm install @cartanova/qgrid-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 qgrid，可以用 npx qgrid 直接运行。

### @cartanova/qgrid-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cartanova\_\_qgrid-cli 是否存在。

### @cartanova/qgrid-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cartanova/qgrid-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cartanova/qgrid-cli 可以商用吗？

@cartanova/qgrid-cli 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @cartanova/qgrid-cli 的下载量有多少？

根据 npm 官方下载统计，@cartanova/qgrid-cli 在 2026/10/09 – 2026/11/07 这 30 天内被下载 5,718 次，日均约 191 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cartanova/qgrid-cli 还在维护吗？

最新版本 2\.18\.0 发布于 2026/11/09（今天）；至今共发布 125 个版本，其中过去 12 个月发布了 125 个；首次发布于 2026/04/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。