### Skills/Aiclient Cli Usage --- name: aiclient-cli-usage description: Use when an agent needs to understand, configure, or call the AIClient2API service via its CLI tools or REST APIs. --- # AIClient2API CLI & API Usage Skill ## Overview This skill provides instructions for AI agents to interact with the AIClient2API service. It covers how to discover available commands and navigate the exhaustive API surface using both local CLI and remote REST interfaces. ## Self-Discovery Modes **CRITICAL**: Regardless of how you access the service, using REST APIs (for management or AI tasks) requires the `Server Address` and appropriate credentials. **Always ask the user for the `Server Address` (use `http://localhost:3000` as default for local) and `Admin Password` before attempting API-based tasks.** ### 1. Local Mode (CLI & REST API) Use these when you have shell access to the server environment. In this mode, you can use both local CLI tools and REST APIs: - **CLI Help**: `npm run help` (Add `--json` for structured data) - **CLI API Guide**: `npm run example:api` (Add `--json` for structured data) - **REST API**: You can access all endpoints via `http://localhost:` (Default: 3000). ### 2. Remote Mode (REST API Only) Use these when interacting with a running instance over the network without shell access: - **Help JSON**: `GET /api/help` (Public, No Auth) - **API Guide JSON**: `GET /api/example` (Public, No Auth) - **REST API**: Use the user-provided `Server Address`. ## When to Use - When you need to understand, configure, or call the AIClient2API service. - To programmatically manage model providers or account pools. - To monitor system health, logs, or usage. ## Core API Categories (AI vs. Management) ### 0. Public Endpoints (No Auth Required) Use these for self-discovery or system monitoring: - `GET /api/help`: Get full API help documentation (JSON). - `GET /api/example`: Get API calling examples (JSON). - `GET /provider_health`: Detailed health status of all model providers. - `POST /api/login`: Exchange `Admin Password` for a dynamic `Token`. ### 1. AI Business Path (`/v1/*`, `/v1beta/*`, `/count_tokens`) - **Purpose**: AI model inference (chat, image, token counting). - **Auth**: Static `API Key`. **Ask the user for this if not provided.** - **Header**: `Authorization: Bearer ` ### 2. Management Path (`/api/*`, `/health`, `/provider_health`) - **Purpose**: Server config, node pool management, logs, stats. - **Auth**: Dynamic `Token` via `/api/login`. **Ask the user for the `Server Address` and `Admin Password`.** - **Header**: `Authorization: Bearer ` (Except for `/api/login` and public health checks). ## Advanced Patterns ### Path Routing Force a specific provider by prefixing the AI business path: - `/gemini-cli-oauth/v1/chat/completions` - `/claude-custom/v1/messages` ### Real-time Logs (SSE) Subscribe to `GET /api/events` via `EventSource` for live system output. ## Quick Reference | Mode | Method | Command/Endpoint | Format | |------|--------|------------------|--------| | Local | CLI | `npm run help -- --json` | JSON | | Local | CLI | `npm run example:api` | Text | | Local | REST | `GET http://localhost:3000/api/help` | JSON | | Remote | REST | `GET /api/help` | JSON | | Remote | REST | `GET /api/example?format=text` | Text | ## Common Mistakes - **Wrong Key**: Using the static AI Key for management APIs (causes 401). - **No Login**: Attempting to fetch `/api/config` without first calling `/api/login`. - **Format Mismatch**: Expecting JSON from a CLI command without the `--json` flag. ## Code Example: Management API Flow ```javascript // 1. Login to get token const login = await fetch('/api/login', { method: 'POST', body: JSON.stringify({ password: 'admin' }) }); const { token } = await login.json(); // 2. Use token for management const nodes = await fetch('/api/providers', { headers: { 'Authorization': `Bearer ${token}` } }); ``` --- ### OPENCLAW CONFIG GUIDE # OpenClaw Configuration Guide Quick configuration guide for using AIClient2API with OpenClaw. --- ## Prerequisites 1. Start AIClient2API service 2. Configure at least one provider in Web UI (`http://localhost:3000`) 3. Note the API Key from configuration file 4. Install OpenClaw - Docker version: [justlikemaki/openclaw-docker-cn-im](https://hub.docker.com/r/justlikemaki/openclaw-docker-cn-im) - Or use other installation methods --- ## Configuration Methods ### Method 1: OpenAI Protocol (Recommended) **Use Case**: For Gemini models ```json5 { env: { AICLIENT2API_KEY: "your-api-key" }, agents: { defaults: { model: { primary: "aiclient2api/gemini-3-flash-preview" }, models: { "aiclient2api/gemini-3-flash-preview": { alias: "Gemini 3 Flash" } } } }, models: { mode: "merge", providers: { aiclient2api: { baseUrl: "http://localhost:3000/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [ { id: "gemini-3-flash-preview", name: "Gemini 3 Flash Preview", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1000000, maxTokens: 8192 } ] } } } } ``` ### Method 2: Claude Protocol **Use Case**: For Claude models with features like Prompt Caching ```json5 { env: { AICLIENT2API_KEY: "your-api-key" }, agents: { defaults: { model: { primary: "aiclient2api/claude-sonnet-4-5" }, models: { "aiclient2api/claude-sonnet-4-5": { alias: "Claude Sonnet 4.5" } } } }, models: { mode: "merge", providers: { aiclient2api: { baseUrl: "http://localhost:3000", apiKey: "${AICLIENT2API_KEY}", api: "anthropic-messages", models: [ { id: "claude-sonnet-4-5", name: "Claude Sonnet 4.5", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 200000, maxTokens: 8192 } ] } } } } ``` --- ## Specify Provider (Optional) Specify a specific provider via routing parameters: ```json5 { models: { providers: { // Kiro Claude (OpenAI Protocol) "aiclient2api-kiro": { baseUrl: "http://localhost:3000/claude-kiro-oauth/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [...] }, // Kiro Claude (Claude Protocol) "aiclient2api-kiro-claude": { baseUrl: "http://localhost:3000/claude-kiro-oauth", apiKey: "${AICLIENT2API_KEY}", api: "anthropic-messages", models: [...] }, // Gemini CLI (OpenAI Protocol) "aiclient2api-gemini": { baseUrl: "http://localhost:3000/gemini-cli-oauth/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [...] }, // Antigravity (OpenAI Protocol) "aiclient2api-antigravity": { baseUrl: "http://localhost:3000/gemini-antigravity/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [...] } } } } ``` --- ## Configure Fallback ```json5 { agents: { defaults: { model: { primary: "aiclient2api/claude-sonnet-4-5", fallbacks: [ "aiclient2api/gemini-3-flash-preview" ] } } } } ``` --- ## Common Commands ```bash # List all models openclaw models list # Switch model openclaw models set aiclient2api/claude-sonnet-4-5 # Chat with specific model openclaw chat --model aiclient2api/gemini-3-flash-preview "your question" ``` --- ## Protocol Comparison | Feature | OpenAI Protocol | Claude Protocol | |---------|----------------|-----------------| | Base URL | `http://localhost:3000/v1` | `http://localhost:3000` | | API Type | `openai-completions` | `anthropic-messages` | | Supported Models | All models | Claude only | | Special Features | - | Prompt Caching, Extended Thinking | --- ## FAQ **Q: Connection failed?** - Confirm AIClient2API service is running - Check if Base URL is correct (OpenAI protocol needs `/v1` suffix) - Try using `127.0.0.1` instead of `localhost` **Q: 401 error?** - Check if API Key is correctly configured - Confirm environment variable `AICLIENT2API_KEY` is set **Q: Model unavailable?** - Confirm provider is configured in AIClient2API Web UI - Run `openclaw gateway restart` to restart gateway - Run `openclaw models list` to verify model list --- For more information, see [AIClient2API Documentation](../README.md) --- ### OPENCLAW CONFIG GUIDE JA # OpenClaw 設定ガイド OpenClaw で AIClient2API を使用するためのクイック設定ガイド。 --- ## 前提条件 1. AIClient2API サービスを起動 2. Web UI (`http://localhost:3000`) で少なくとも1つのプロバイダーを設定 3. 設定ファイルから API Key を記録 4. OpenClaw をインストール - Docker バージョン：[justlikemaki/openclaw-docker-cn-im](https://hub.docker.com/r/justlikemaki/openclaw-docker-cn-im) - または他のインストール方法を使用 --- ## 設定方法 ### 方法1：OpenAI プロトコル（推奨） **使用例**：Gemini モデルを使用する場合 ```json5 { env: { AICLIENT2API_KEY: "your-api-key" }, agents: { defaults: { model: { primary: "aiclient2api/gemini-3-flash-preview" }, models: { "aiclient2api/gemini-3-flash-preview": { alias: "Gemini 3 Flash" } } } }, models: { mode: "merge", providers: { aiclient2api: { baseUrl: "http://localhost:3000/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [ { id: "gemini-3-flash-preview", name: "Gemini 3 Flash Preview", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1000000, maxTokens: 8192 } ] } } } } ``` ### 方法2：Claude プロトコル **使用例**：Prompt Caching などの機能を持つ Claude モデルを使用する場合 ```json5 { env: { AICLIENT2API_KEY: "your-api-key" }, agents: { defaults: { model: { primary: "aiclient2api/claude-sonnet-4-5" }, models: { "aiclient2api/claude-sonnet-4-5": { alias: "Claude Sonnet 4.5" } } } }, models: { mode: "merge", providers: { aiclient2api: { baseUrl: "http://localhost:3000", apiKey: "${AICLIENT2API_KEY}", api: "anthropic-messages", models: [ { id: "claude-sonnet-4-5", name: "Claude Sonnet 4.5", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 200000, maxTokens: 8192 } ] } } } } ``` --- ## プロバイダーの指定（オプション） ルーティングパラメータで特定のプロバイダーを指定： ```json5 { models: { providers: { // Kiro Claude（OpenAI プロトコル） "aiclient2api-kiro": { baseUrl: "http://localhost:3000/claude-kiro-oauth/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [...] }, // Kiro Claude（Claude プロトコル） "aiclient2api-kiro-claude": { baseUrl: "http://localhost:3000/claude-kiro-oauth", apiKey: "${AICLIENT2API_KEY}", api: "anthropic-messages", models: [...] }, // Gemini CLI（OpenAI プロトコル） "aiclient2api-gemini": { baseUrl: "http://localhost:3000/gemini-cli-oauth/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [...] }, // Antigravity（OpenAI プロトコル） "aiclient2api-antigravity": { baseUrl: "http://localhost:3000/gemini-antigravity/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [...] } } } } ``` --- ## フォールバックの設定 ```json5 { agents: { defaults: { model: { primary: "aiclient2api/claude-sonnet-4-5", fallbacks: [ "aiclient2api/gemini-3-flash-preview" ] } } } } ``` --- ## よく使うコマンド ```bash # すべてのモデルをリスト表示 openclaw models list # モデルを切り替え openclaw models set aiclient2api/claude-sonnet-4-5 # 特定のモデルでチャット openclaw chat --model aiclient2api/gemini-3-flash-preview "あなたの質問" ``` --- ## プロトコル比較 | 機能 | OpenAI プロトコル | Claude プロトコル | |------|------------------|------------------| | Base URL | `http://localhost:3000/v1` | `http://localhost:3000` | | API タイプ | `openai-completions` | `anthropic-messages` | | サポートモデル | すべてのモデル | Claude のみ | | 特殊機能 | - | Prompt Caching、Extended Thinking | --- ## よくある質問 **Q: 接続に失敗しますか？** - AIClient2API サービスが実行中であることを確認 - Base URL が正しいか確認（OpenAI プロトコルには `/v1` サフィックスが必要） - `localhost` の代わりに `127.0.0.1` を使用してみる **Q: 401 エラー？** - API Key が正しく設定されているか確認 - 環境変数 `AICLIENT2API_KEY` が設定されているか確認 **Q: モデルが利用できない？** - AIClient2API Web UI でプロバイダーが設定されているか確認 - `openclaw gateway restart` を実行してゲートウェイを再起動 - `openclaw models list` を実行してモデルリストを確認 --- 詳細については、[AIClient2API ドキュメント](../README-JA.md) を参照してください --- ### OPENCLAW CONFIG GUIDE ZH # OpenClaw 配置指南 在 OpenClaw 中使用 AIClient2API 的快速配置指南。 --- ## 前置准备 1. 启动 AIClient2API 服务 2. 在 Web UI (`http://localhost:3000`) 配置至少一个提供商 3. 记录配置文件中的 API Key 4. 安装 OpenClaw - Docker 版本：[justlikemaki/openclaw-docker-cn-im](https://hub.docker.com/r/justlikemaki/openclaw-docker-cn-im) - 或使用其他安装方式 --- ## 配置方式 ### 方式一：OpenAI 协议（推荐） **适用场景**：使用 Gemini 模型 ```json5 { env: { AICLIENT2API_KEY: "your-api-key" }, agents: { defaults: { model: { primary: "aiclient2api/gemini-3-flash-preview" }, models: { "aiclient2api/gemini-3-flash-preview": { alias: "Gemini 3 Flash" } } } }, models: { mode: "merge", providers: { aiclient2api: { baseUrl: "http://localhost:3000/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [ { id: "gemini-3-flash-preview", name: "Gemini 3 Flash Preview", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1000000, maxTokens: 8192 } ] } } } } ``` ### 方式二：Claude 协议 **适用场景**：使用 Claude 模型，需要 Prompt Caching 等特性 ```json5 { env: { AICLIENT2API_KEY: "your-api-key" }, agents: { defaults: { model: { primary: "aiclient2api/claude-sonnet-4-5" }, models: { "aiclient2api/claude-sonnet-4-5": { alias: "Claude Sonnet 4.5" } } } }, models: { mode: "merge", providers: { aiclient2api: { baseUrl: "http://localhost:3000", apiKey: "${AICLIENT2API_KEY}", api: "anthropic-messages", models: [ { id: "claude-sonnet-4-5", name: "Claude Sonnet 4.5", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 200000, maxTokens: 8192 } ] } } } } ``` --- ## 指定提供商（可选） 通过路由参数指定特定提供商： ```json5 { models: { providers: { // Kiro 提供的 Claude (OpenAI 协议) "aiclient2api-kiro": { baseUrl: "http://localhost:3000/claude-kiro-oauth/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [...] }, // Kiro 提供的 Claude (Claude 协议) "aiclient2api-kiro-claude": { baseUrl: "http://localhost:3000/claude-kiro-oauth", apiKey: "${AICLIENT2API_KEY}", api: "anthropic-messages", models: [...] }, // Gemini CLI (OpenAI 协议) "aiclient2api-gemini": { baseUrl: "http://localhost:3000/gemini-cli-oauth/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [...] }, // Antigravity (OpenAI 协议) "aiclient2api-antigravity": { baseUrl: "http://localhost:3000/gemini-antigravity/v1", apiKey: "${AICLIENT2API_KEY}", api: "openai-completions", models: [...] } } } } ``` --- ## 配置 Fallback ```json5 { agents: { defaults: { model: { primary: "aiclient2api/claude-sonnet-4-5", fallbacks: [ "aiclient2api/gemini-3-flash-preview" ] } } } } ``` --- ## 常用命令 ```bash # 列出所有模型 openclaw models list # 切换模型 openclaw models set aiclient2api/claude-sonnet-4-5 # 使用指定模型对话 openclaw chat --model aiclient2api/gemini-3-flash-preview "你的问题" ``` --- ## 协议对比 | 特性 | OpenAI 协议 | Claude 协议 | |------|------------|------------| | Base URL | `http://localhost:3000/v1` | `http://localhost:3000` | | API 类型 | `openai-completions` | `anthropic-messages` | | 支持模型 | 所有模型 | 仅 Claude | | 特殊特性 | - | Prompt Caching、Extended Thinking | --- ## 常见问题 **Q: 连接失败？** - 确认 AIClient2API 服务运行中 - 检查 Base URL 是否正确（OpenAI 协议需要 `/v1` 后缀） - 尝试使用 `127.0.0.1` 替代 `localhost` **Q: 401 错误？** - 检查 API Key 是否正确配置 - 确认环境变量 `AICLIENT2API_KEY` 已设置 **Q: 模型不可用？** - 在 AIClient2API Web UI 确认已配置对应提供商 - 运行 `openclaw gateway restart` 重启网关 - 运行 `openclaw models list` 验证模型列表 --- 更多信息请参考 [AIClient2API 文档](../README-ZH.md) --- ### OPENCODE CONFIG EXAMPLE # OpenCode 配置示例及重点解释 本文档提供了一个典型的 `opencode` 配置文件示例，并对其中的关键配置项进行了详细解释，帮助您快速理解如何配置不同的 AI 服务提供商。 ## 配置示例 (`config.json`) ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 配置重点解释 ### 1. `provider` (服务提供商配置) 这是配置的核心部分，每个键（如 `kiro`, `gemini-cli`）代表一个独立的服务提供商实例。 * **`npm` (SDK 适配器)**: * 指定底层使用的 AI SDK。例如： * `@ai-sdk/anthropic`: 用于 Anthropic (Claude) 系列模型。 * `@ai-sdk/openai-compatible`: 用于兼容 OpenAI 接口标准的模型。 * `@ai-sdk/google`: 用于 Google Gemini 系列模型。 * **重点**: 必须确保 `npm` 字段与您要使用的模型协议匹配，否则会导致连接失败。 * **`options` (连接参数)**: * **`baseURL`**: API 的访问地址。在示例中，许多是内网或中转地址（如 `http://localhost:3000/...`）。 * **`apiKey`**: 访问 API 所需的身份验证密钥。 * **`models` (模型映射)**: * 定义该提供商下可用的模型列表。 * **键名 (ID)**: 实际调用时使用的模型 ID（例如 `claude-opus-4-5`）。 * **`name`**: 在 UI 界面上显示的友好名称。 * **重点**: 这里的键名必须与服务端实际支持的模型标识符一致。 ### 2. 区分同类型的不同实例 在示例中，有两个 `gemini` 相关的配置：`gemini-antigravity` 和 `gemini-cli`。 * 它们虽然都使用 `@ai-sdk/google`，但通过不同的 `baseURL` 区分。 * 这允许您在同一配置中接入来自不同网关或环境的同类模型，并通过自定义的 `name`（如 `gemini-2.5-flash-antigravity` vs `gemini-2.5-flash-geminicli`）在前端进行区分。 ### 3. `$schema` * 用于提供 JSON 模式验证。在支持的编辑器（如 VS Code）中，它可以为您提供自动补全和实时错误检查。 --- ### PROVIDER ADAPTER GUIDE # AIClient2API Provider 接入指南 本文档详细说明了如何向 AIClient2API 项目接入全新的模型提供商（Provider），涵盖从后端核心逻辑到前端 UI 管理的全流程调整。 ## 1. 接入流程概览 1. **后端常量定义**：在 `src/utils/common.js` 中添加标识。 2. **核心 Service 开发**：在 `src/providers/` 实现 API 请求逻辑。 3. **适配器注册**：在 `src/providers/adapter.js` 注册并实现适配器类。 4. **模型与号池配置**：在 `src/providers/provider-models.js` 和 `src/providers/provider-pool-manager.js` 配置。 5. **前端 UI 全方位调整**： * `static/app/provider-manager.js`：号池显示与顺序。 * `static/app/file-upload.js`：上传路径映射。 * `static/app/modal.js`：配置字段显示顺序。 * `static/app/utils.js`：定义配置字段元数据。 * `static/components/section-config.html`：配置按钮。 * `static/components/section-guide.html`：使用指南。 * `static/app/routing-examples.js`：路由调用示例。 6. **系统级映射（必做）**：在 OAuth 处理器、凭据关联工具、用量统计等模块中建立映射。 --- ## 2. 后端核心实现 ### 2.1 定义常量 修改 [`src/utils/common.js`](src/utils/common.js)，在 `MODEL_PROVIDER` 中添加新 key（格式建议：`协议-名称-类型`）。 ### 2.2 核心 Service (Core) 在 `src/providers/` 下创建新目录并实现 `NewProviderApiService` 类。 **必选方法**：`constructor(config)`, `initialize()`, `listModels()`, `generateContent()`, `generateContentStream()`。 **可选功能**：若支持用量查询，需实现 `getUsageLimits()`；若支持 Token 统计，需实现 `countTokens()`。 ### 2.3 注册适配器 在 [`src/providers/adapter.js`](src/providers/adapter.js) 中： 1. 继承 `ApiServiceAdapter` 实现特定提供商的适配器类。 2. 适配器类需按需重写 `generateContent`, `generateContentStream`, `listModels`, `getUsageLimits`, `countTokens`, `refreshToken` 等方法，并转发给核心 Service。 3. 在 `getServiceAdapter` 工厂方法中添加对应的 `switch` 分支，根据 `MODEL_PROVIDER` 返回实例。 ### 2.4 模型与号池默认配置 * **模型列表**：在 [`src/providers/provider-models.js`](src/providers/provider-models.js) 的 `PROVIDER_MODELS` 对象中添加默认支持的模型 ID。 * **健康检查默认值**：在 [`src/providers/provider-pool-manager.js`](src/providers/provider-pool-manager.js) 的以下位置配置： * `DEFAULT_HEALTH_CHECK_MODELS`：指定用于健康检查的默认模型。 * `checkAndRefreshExpiringNodes`：指定凭据文件路径键名。 * `_buildHealthCheckRequests`：若有特殊请求格式需求，需在此添加逻辑。 --- ## 3. 前端界面调整 ### 3.1 字段定义与元数据 ([`static/app/utils.js`](static/app/utils.js)) 在 `getProviderTypeFields` 函数中定义该提供商所需的配置字段（如 API Key, Base URL, 凭据路径等），指定字段类型和占位符。 ### 3.2 字段显示顺序 ([`static/app/modal.js`](static/app/modal.js)) 在 `getFieldOrder` 函数的 `fieldOrderMap` 中添加新提供商的字段显示顺序。 ### 3.3 号池显示逻辑 ([`static/app/provider-manager.js`](static/app/provider-manager.js)) * **显示顺序**：将新标识和显示名称添加到 `providerConfigs` 数组。 * **授权按钮**：若支持 OAuth，在 `generateAuthButton` 的 `oauthProviders` 数组中添加标识。 * **认证逻辑**：若支持 OAuth 或批量导入，需在 `handleGenerateAuthUrl` 中实现相应的触发逻辑（如弹出认证方式选择器）。 ### 3.4 凭据上传路由 ([`static/app/file-upload.js`](static/app/file-upload.js)) * 修改 `getProviderKey`，建立提供商标识与 `configs/` 子目录名的映射（例如：`new-provider-api` -> `new-provider`）。 ### 3.5 凭据文件管理筛选器 需要在以下三个位置添加新提供商的筛选支持： #### 3.5.1 HTML 筛选器选项 ([`static/components/section-upload-config.html`](static/components/section-upload-config.html)) 在 `id="configProviderFilter"` 的 `