Publish the OmniaKey AI coding tools configuration guide

README.md

@@ -0,0 +1,257 @@
+---
+language:
+- zh
+- en
+license: mit
+tags:
+- tutorial
+- omniakey
+- ai-coding
+- claude-code
+- codex
+- cursor
+- cline
+- continue
+- aider
+- openai-compatible
+- anthropic
+- llm
+- vscode
+---
+
+# OmniaKey AI Coding Tools
+
+> 在 Claude Code、Codex、Cursor、Cline、Continue、Aider 等 AI 编程工具中使用 Claude、GPT、Gemini、Grok 等模型。
+
+[OmniaKey](https://omniakey.com/) 为 AI 编程工具提供一把统一 API Key，同时支持 Anthropic Messages、OpenAI Chat Completions 和 OpenAI Responses 等协议。按实际用量计费，无需为每个工具分别管理订阅。
+
+> This repository is a configuration guide, not a downloadable model checkpoint. English quick start is included below.
+
+## 快速入口
+
+- [创建 OmniaKey API Key](https://omniakey.com/dashboard/tokens)
+- [查看模型目录](https://omniakey.com/models)
+- [AI 编程工具完整指南](https://docs.omniakey.com/cn/coding)
+- OpenAI-compatible Base URL：`https://api.omniakey.com/v1`
+- Anthropic Base URL：`https://api.omniakey.com`
+
+请勿把真实 API Key 提交到 Git、截图、Issue 或日志中。示例统一使用 `sk-your-omniakey-key`。
+
+## 先检查当前可用模型
+
+模型和权限会持续更新。不要依赖旧教程中的静态价格表，先用自己的 Key 查询：
+
+```bash
+curl https://api.omniakey.com/v1/models \
+  -H "Authorization: Bearer sk-your-omniakey-key"
+```
+
+从返回结果复制准确的 model ID，再填入对应工具。
+
+## Claude Code
+
+Claude Code 使用 Anthropic Messages API，因此 Base URL **不要带 `/v1`**：
+
+```bash
+export ANTHROPIC_BASE_URL="https://api.omniakey.com"
+export ANTHROPIC_AUTH_TOKEN="sk-your-omniakey-key"
+claude
+```
+
+Claude Code 会自行请求 `/v1/messages`。如果把 Base URL 写成 `https://api.omniakey.com/v1`，最终会变成错误的 `/v1/v1/messages`。
+
+进入会话后可以用 `/model` 显式选择当前可用的 Claude 模型。OmniaKey 不会静默把你指定的模型替换成其他模型。
+
+## OpenAI Codex CLI
+
+Codex 自定义 provider 使用 Responses API。编辑 `~/.codex/config.toml`：
+
+```toml
+model = "gpt-5.6-sol"
+model_provider = "omniakey"
+
+[model_providers.omniakey]
+name = "OmniaKey"
+base_url = "https://api.omniakey.com/v1"
+env_key = "OMNIAKEY_API_KEY"
+wire_api = "responses"
+```
+
+然后设置 Key 并启动：
+
+```bash
+export OMNIAKEY_API_KEY="sk-your-omniakey-key"
+codex
+```
+
+示例 model ID 可能随目录更新；排障时先确认它出现在当前 Key 的 `/v1/models` 返回中。
+
+## Cursor
+
+在 Cursor 的模型或自定义 OpenAI 设置中填写：
+
+| 配置项 | 值 |
+| --- | --- |
+| OpenAI API Key | `sk-your-omniakey-key` |
+| Override OpenAI Base URL | `https://api.omniakey.com/v1` |
+| Model | 从 `/v1/models` 复制一个当前可用 ID |
+
+Cursor 不同版本对自定义模型、Agent 模式和 Tab Completion 的支持可能不同。若某功能仍走 Cursor 自有服务，这是客户端能力边界，并不代表 API Key 无效。
+
+## Cline
+
+在 Cline 设置中选择 **OpenAI Compatible**，然后填写：
+
+| 配置项 | 值 |
+| --- | --- |
+| Base URL | `https://api.omniakey.com/v1` |
+| API Key | `sk-your-omniakey-key` |
+| Model ID | 从 `/v1/models` 复制 |
+
+保存后建议先用一个小任务测试 streaming 和工具调用，再开始大型代码修改。
+
+## Continue
+
+在 Continue 中新增一个 OpenAI-compatible 模型：
+
+```yaml
+name: OmniaKey
+version: 1.0.0
+schema: v1
+models:
+  - name: OmniaKey Coding
+    provider: openai
+    model: YOUR_MODEL_ID
+    apiBase: https://api.omniakey.com/v1
+    apiKey: sk-your-omniakey-key
+```
+
+Continue 的配置格式会随版本变化；如果你的版本使用 UI 配置，填入相同的 Base URL、Key 和 Model ID 即可。
+
+## Aider
+
+先设置 OpenAI-compatible 凭证和端点：
+
+```bash
+export OPENAI_API_KEY="sk-your-omniakey-key"
+export OPENAI_API_BASE="https://api.omniakey.com/v1"
+aider --model openai/YOUR_MODEL_ID
+```
+
+Aider 通过 LiteLLM 识别 provider 前缀。若模型需要不同前缀或参数，请以当前 Aider/LiteLLM 文档和 `/v1/models` 返回为准。
+
+## OpenAI SDK
+
+### Python
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.omniakey.com/v1",
+    api_key="sk-your-omniakey-key",
+)
+
+response = client.chat.completions.create(
+    model="YOUR_MODEL_ID",
+    messages=[
+        {"role": "user", "content": "Review this function for correctness."}
+    ],
+)
+
+print(response.choices[0].message.content)
+```
+
+### Node.js
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "https://api.omniakey.com/v1",
+  apiKey: "sk-your-omniakey-key",
+});
+
+const response = await client.chat.completions.create({
+  model: "YOUR_MODEL_ID",
+  messages: [
+    { role: "user", content: "Write tests for this TypeScript module." },
+  ],
+});
+
+console.log(response.choices[0].message.content);
+```
+
+## 常见问题
+
+| 现象 | 检查 |
+| --- | --- |
+| `401 Unauthorized` | Key 是否正确、是否带 `Bearer `、是否复制了多余空格 |
+| `404 Not Found` | OpenAI-compatible 工具是否使用 `/v1`；Claude Code 是否错误地多加了 `/v1` |
+| Model not found | 用当前 Key 请求 `/v1/models`，复制准确 ID |
+| 工具调用失败 | 先确认客户端使用的协议和该模型的工具调用能力 |
+| Streaming 中断 | 检查本地代理、企业网络和客户端超时设置；保留 request ID 便于排查 |
+| `429` | 按响应中的 retry/reset 信息等待后重试，避免无上限自动循环 |
+
+## 为什么选择 OmniaKey
+
+- 一把 Key 连接 Claude、GPT、Gemini、Grok 等模型
+- 同时提供 Anthropic 原生协议与 OpenAI-compatible 接口
+- 支持 Chat Completions、Responses、streaming 和工具调用
+- 模型 ID 显式可见，不静默替换
+- 一个 Dashboard 管理 Key、余额和用量
+
+---
+
+## English quick start
+
+Create a key at [OmniaKey Dashboard](https://omniakey.com/dashboard/tokens), then choose the protocol your coding tool actually uses.
+
+### Claude Code
+
+```bash
+export ANTHROPIC_BASE_URL="https://api.omniakey.com"
+export ANTHROPIC_AUTH_TOKEN="sk-your-omniakey-key"
+claude
+```
+
+Do not append `/v1`; Claude Code appends `/v1/messages` itself.
+
+### OpenAI-compatible tools
+
+Use these values in Cursor, Cline, Continue, Aider, SDKs, and other compatible clients:
+
+```text
+Base URL: https://api.omniakey.com/v1
+API Key:  sk-your-omniakey-key
+Model:    choose an ID returned by GET /v1/models
+```
+
+### Codex
+
+```toml
+model = "gpt-5.6-sol"
+model_provider = "omniakey"
+
+[model_providers.omniakey]
+name = "OmniaKey"
+base_url = "https://api.omniakey.com/v1"
+env_key = "OMNIAKEY_API_KEY"
+wire_api = "responses"
+```
+
+Always verify the current model catalog before relying on an example ID:
+
+```bash
+curl https://api.omniakey.com/v1/models \
+  -H "Authorization: Bearer sk-your-omniakey-key"
+```
+
+## Links
+
+- [OmniaKey](https://omniakey.com/)
+- [Get an API Key](https://omniakey.com/dashboard/tokens)
+- [Model catalog](https://omniakey.com/models)
+- [Coding tools guide](https://docs.omniakey.com/en/coding)
+
+This repository contains documentation only and is not affiliated with Anthropic, OpenAI, Cursor, Cline, Continue, or Aider. Product names belong to their respective owners.