---
name: token4ai
description: Manage the user's Token4AI tenant workspace with the token4ai CLI, including API keys, usage, balance, billing, files and support. Use for Token4AI account operations from an agent.
---

# Token4AI CLI Skill

token4ai-cli 是 Token4AI 面向客户的命令行工具,供你(或你的 agent)访问自己的租户后台:管理带计费
分组的 API Key、查询用量 / 钱包 / 账单、上传下载资产、进入 Agent 项目和加密社群、提交支持工单、切换数据区域等 ——
与网页版后台功能对齐。授权采用设备授权流(RFC 8628,类 `gh auth login`):必须由**账户拥有者在浏
览器中确认**后才能获得访问令牌 —— agent 不能自行授权。

## 1. 安装(按你的平台选一条)
```bash
# macOS · Apple Silicon
mkdir -p "$HOME/.local/bin" &&
curl --fail --show-error --location https://dash.token4ai.cloud/api/cli/download/darwin-arm64 -o "$HOME/.local/bin/token4ai" &&
chmod +x "$HOME/.local/bin/token4ai" &&
export PATH="$HOME/.local/bin:$PATH" &&
token4ai --help

# macOS · Intel
mkdir -p "$HOME/.local/bin" &&
curl --fail --show-error --location https://dash.token4ai.cloud/api/cli/download/darwin-x64 -o "$HOME/.local/bin/token4ai" &&
chmod +x "$HOME/.local/bin/token4ai" &&
export PATH="$HOME/.local/bin:$PATH" &&
token4ai --help

# Linux · x64 / WSL2
mkdir -p "$HOME/.local/bin" &&
curl --fail --show-error --location https://dash.token4ai.cloud/api/cli/download/linux-x64 -o "$HOME/.local/bin/token4ai" &&
chmod +x "$HOME/.local/bin/token4ai" &&
export PATH="$HOME/.local/bin:$PATH" &&
token4ai --help

# Linux · ARM64
mkdir -p "$HOME/.local/bin" &&
curl --fail --show-error --location https://dash.token4ai.cloud/api/cli/download/linux-arm64 -o "$HOME/.local/bin/token4ai" &&
chmod +x "$HOME/.local/bin/token4ai" &&
export PATH="$HOME/.local/bin:$PATH" &&
token4ai --help
```
安装到 `~/.local/bin/token4ai`。在新终端中将 `export PATH="$HOME/.local/bin:$PATH"` 加入 shell 配置,
或使用完整路径运行。Windows 使用 WSL2 中对应的 Linux 版本。

## 2. 登录(需要账户拥有者在浏览器授权)
```bash
token4ai auth login --host https://dash.token4ai.cloud
```
它会打印**授权 URL** 与**授权码**(如 `XXXX-XXXX`)。
**重要**:agent 无法自行完成授权。请把授权 URL 与授权码交给账户拥有者,由其在浏览器登录 Token4AI
后台并确认该授权码。确认后 CLI 自动拿到令牌并保存到 `~/.config/token4ai/config.json`(0600)。
- 查看状态:`token4ai auth status`  · 退出并吊销令牌:`token4ai auth logout`
- CI / 无状态环境:改用环境变量注入,免读配置文件 ——
  `export TOKEN4AI_ACCESS_TOKEN=t4c_…`、`export TOKEN4AI_HOST=https://dash.token4ai.cloud`。

## 3. 全局约定
- 任何命令加 `--json`:stdout 输出纯 JSON(错误进 stderr、非零退出),便于 agent 解析。
- `--host <url>` 覆盖目标(默认 `https://dash.token4ai.cloud`);为某 host 保存的令牌不会发往另一 host。
- 破坏性操作(`key delete` / `asset delete`)需要 `--yes` 确认;非交互终端未加 `--yes` 会被拒绝。
- `--dry-run` 只用于本地 `agent setup`:显示将写入的文件与配置计划,不写盘、不创建 key。
- **密钥安全**:`key test` 校验的客户密钥只能经 `stdin` 或 `--env <VAR>` 传入,`agent setup` 使用 `--key-env <VAR>` 或 `--key-stdin`,**绝不写进命令行参数,也不出现在输出里**。
- Agent 项目仅创建者可访问，无需项目密码；`project join` 返回短期 Agent Room 票据。

## 4. 命令速查

### 账户 / 概览
```bash
token4ai whoami [--live]        # 当前账户与角色(--live 触发上游实时校验)
token4ai overview               # 后台首页概览
token4ai balance                # 钱包余额(= wallet)
token4ai public-config          # 公开配置   token4ai health   # 健康检查
token4ai announcements          # 公告
```

### API Key(带计费分组)
```bash
token4ai key list                                   # 列出 API Key
token4ai key groups --provider openai               # 该 provider 的计费分组
token4ai key create --provider openai --group <名称|id> [--billing-group <id>]
                                                      # 创建(rawKey 一次性返回;--group 名称→id 自动解析)
token4ai key rotate <id>                            # 轮换密钥
token4ai key update <id> --billing-group <id>       # 改绑计费分组
token4ai key update <id> --clear-billing-group        # 解绑(回落 ×1 费率)
token4ai key delete <id> --yes                      # 删除
echo "$PROVIDER_KEY" | token4ai key test <id> --model gpt-4o-mini  # 连通性测试(密钥经 stdin)
```

### 用量 / 计费 / 钱包
```bash
token4ai usage [--provider <p>] [--page N] [--page-size N] [--start <ts>] [--end <ts>]
token4ai tracing                 # 请求链路   token4ai latency [--region <r>]  # 时延
token4ai billing rate            # 当前费率
token4ai billing orders [--offset N] [--limit N]     # 充值/账单记录
token4ai billing checkout --package <packageId>      # 生成 Stripe 充值链接(打印 url)
token4ai provider-models --provider <p>              # 某 provider 的可用模型
```

### 资产(租户文件存储)
```bash
token4ai asset list [--prefix <p>]        token4ai asset storage         # 用量
token4ai asset download --name <n> [--out <path>]    # 下载(默认写 stdout)
token4ai asset upload   --name <n> --file <path>     # 上传(raw body)
token4ai asset folder   --prefix <p> --name <n>      # 建文件夹
token4ai asset delete   --name <n> --yes             # 删除
```

### 社群(加密群聊,24h 保留)
```bash
token4ai community rooms [--q <关键词>]               # 房间列表
token4ai community create --name <n> [--type public|private] [--password 12345678]
token4ai community join <id> [--password 12345678]   # 私有房需 8 位数字密码
token4ai community presence --rooms a,b               # 在线状态
token4ai community image --name <n> [--out <path>]    # 拉取群聊图片
```

### Agent 项目(专属 Party Room)
```bash
token4ai project list                                  # 当前租户项目
token4ai project create --name <项目名>
token4ai project join <id> --json
```

### 支持 / 设置
```bash
token4ai support chat [--cursor <c>]      token4ai support send --body <文本>
token4ai support tickets [--page N] [--page-size N]
token4ai support ticket-create --title <标题> --content <内容>
token4ai data-region                      token4ai data-region set --region <r>
```

### 本地编码 Agent(一条命令接入)
```bash
token4ai agent setup --agent codex|claude-code|gemini-cli|opencode
      [--key-env <VAR> | --key-stdin | --key-id <id>]
      [--base-url <url>] [--model <m>] [--profile <path>] [--force] [--dry-run]
token4ai agent status [--agent <name>] [--json]
token4ai agent doctor [--agent <name>] [--live] [--json]
```
- 幂等合并现有配置,写前备份;Codex 写 config.toml + auth.json,Claude 合并 settings.json 的 env,Gemini/OpenCode 写专用 env 文件与 shell 托管块。
- 已登录时可自动复用或创建 API Key;每 provider 最多 5 个。OpenCode 配置含注释时默认拒绝,确认接受注释丢失再加 `--force`。

### 通用兜底
```bash
# 任意已连通端点,令牌自动作为 Bearer 附带
token4ai api /api/balance
token4ai api /api/api-keys POST '{"provider":"openai"}'
```

## 注意
- `key create` 的 `--group` 用**分组名称**时,CLI 会先查 `key groups` 解析出 id;省略则按 ×1 费率结算。
- 令牌 30 天有效、可撤销;只有账户拥有者授权过的设备能用,未授权一切返回 401。
- 机器可读的完整端点映射见 `GET https://dash.token4ai.cloud/api/cli/manifest`。