Metadata-Version: 2.4
Name: rmodel-cli
Version: 0.2.0
Summary: One-click configure free-tier / pay-as-you-go LLM providers (QianWen, Volcengine Ark) for OpenClaw/Codex
Author: rmodel contributors
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/rmodel-cli/
Project-URL: Documentation, https://platform.qianwenai.com/docs/api-reference/preparation/cli#usage-free-tier
Keywords: llm,rmodel,qianwen,dashscope,openclaw,codex,free-tier,quota,probe,volcengine
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# rmodel

探测商用大模型可用性，并一键把免费额度/按量模型写入 OpenClaw / Codex（当前支持千问/DashScope、火山方舟按量 API）。

> PyPI 包名是 **`rmodel-cli`**（裸名 `rmodel` 已被占用）；安装后命令仍是 **`rmodel`**。

> 可用性探测 ≠ 账单状态。`qwen-free` 以 [千问 CLI `usage free-tier`](https://platform.qianwenai.com/docs/api-reference/preparation/cli#usage-free-tier) 为准。

## 安装（PyPI）

```bash
pip install rmodel-cli
rmodel --help
```

升级：

```bash
pip install -U rmodel-cli
```

开发安装：

```bash
git clone <your-repo>
cd rmodel   # 或本地仓库目录
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

只需本机有 **Node.js / npm（>=18）**。

### 千问（`qwen-free`）

`rmodel qwen-free` 会在需要时自动：

1. `npm install -g @qianwenai/qianwen-cli`
2. 拉起 `qianwen auth login`（浏览器授权）
3. 拉取免费额度模型并写入 OpenClaw / Codex

### 火山方舟（`ark-free`）

`rmodel ark-free` 会在需要时自动：

1. `npm install -g @volcengine/ark-cli`
2. 拉起 `arkcli auth login volc-sso`（浏览器 SSO）
3. 从模型广场拉取文本对话候选，HTTP 探测后写入 OpenClaw / Codex

**说明：** 方舟没有与千问 `usage free-tier` 对等的 CLI 命令；`ark-free` 走按量 `/api/v3`，**不包含** Coding Plan / Agent Plan（`/api/coding/`、`/api/plan/` 会被排除）。

## 一键配置千问免费模型

```bash
rmodel qwen-free
```

控制台以**下拉列表**方式多选（每页 10 个，最多选 10 个），并标注模型类型：

- `↑↓` 切换当前项
- `空格` 勾选 / 取消
- `Enter` 确认已选
- `n` / `r` 下一页刷新，`p` 上一页
- `a` 全选本页，`q` 取消

展示示例：`qwen-plus  [文本推理]  额度 ...` / `qwen-vl-max  [文本推理+视觉理解]` / `wan2.6-t2i  [视觉生图]`

可选：

```bash
rmodel qwen-free --dry-run
rmodel qwen-free --set-primary --agent main
rmodel qwen-free --api-key sk-xxx
rmodel qwen-free --text-only
rmodel qwen-free --yes --models qwen-plus,qwen-turbo   # 非交互选模型；若无 Key 仍会在终端提示输入
rmodel qwen-free --no-install
rmodel qwen-free --no-login
rmodel qwen-free --target codex   # 一键写 Codex（等同 OpenClaw 效果）
```

### OpenClaw

| 场景 | 行为 |
|------|------|
| 已有 DashScope/千问 **API** provider | 复用 Key，补充仍有免费额度的模型选项 |
| 没有 API provider | 引导创建/填写 API Key，新建 `dashscope` provider 并写入 |
| 订阅 Plan（`qianwen-plan` 等） | 不当作 API 配置复用 |

### Codex（`--target codex`）

写入 `~/.codex/config.toml`，效果与 OpenClaw 对齐、可直接 `codex`：

1. `model` + `model_provider = "dashscope"`
2. `[model_providers.dashscope]`：`base_url`（兼容模式）、`wire_api = "responses"`
3. `experimental_bearer_token`（有可用 Key 时写入；此时不写 `env_key`，避免 Codex 仍要求 export）
4. `~/.codex/model-catalog.local.json`（所选模型元数据）

**注意：** 当前 Codex CLI 只走 Responses API。`kimi-*` 等仅支持 Chat Completions 的模型会被隐藏/探测拒绝；请选 `qwen3.8-max`、`qwen3-coder-plus`、`qwen-plus` 等。否则会出现 `stream disconnected before response.completed`。

优先复用 OpenClaw 里已有的 DashScope API Key / `DASHSCOPE_API_KEY`。

`qianwen auth login`（CLI 会话）与 DashScope **API Key** 是两套凭证。  
API Key 控制台：https://bailian.console.aliyun.com/?tab=model#/api-key

## 一键配置火山方舟按量模型

```bash
rmodel ark-free
```

交互选择与 `qwen-free` 相同（每页 10 个，最多 10 个）。列表项显示 `按量 · 写入前 HTTP 探测`（方舟无免费额度 CLI，以探测结果为准）。

可选：

```bash
rmodel ark-free --dry-run
rmodel ark-free --set-primary --agent main
rmodel ark-free --api-key 907f-...
rmodel ark-free --text-only
rmodel ark-free --yes --models deepseek-v4-flash-ga-260731,glm-5-2-260617
rmodel ark-free --no-install
rmodel ark-free --no-login
rmodel ark-free --target codex
```

### OpenClaw

| 场景 | 行为 |
|------|------|
| 已有 `volcengine-ark` 等 **API** provider | 复用 Key / baseUrl，补充探测通过的模型 |
| 没有 API provider | 新建 `volcengine-ark`，`baseUrl=https://ark.cn-beijing.volces.com/api/v3` |
| Coding/Agent Plan | 不当作 API 配置复用 |

### Codex（`--target codex`）

与千问路径一致：写入 `model` + `[model_providers.volcengine-ark]`（`wire_api=responses`）+ `experimental_bearer_token` + 本地 catalog。

API Key 优先级：`--api-key` → OpenClaw 已有 provider → `ARK_API_KEY` → arkcli 登录后本地 Key → 终端粘贴。

控制台：https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey

未开通的模型会探测失败；可用 `arkcli models activate <model>` 开通后再试。

## 通用探测

```bash
rmodel probe --source openclaw
rmodel apply --target openclaw --agent main --to dashscope/qwen-plus
```

## 发布到 PyPI（维护者）

首次配置凭证（写入 macOS 钥匙串，之后不用再 `export`）：

```bash
./scripts/setup-pypi-auth.sh
```

日常发布：

```bash
./scripts/publish.sh
```

## 开发

```bash
pytest
```
