1 line
16 KiB
JSON
1 line
16 KiB
JSON
{"repo": "0xheap/urlyn-code", "files": {"docs/users/configuration/auth.md": {"5bfa9bbd252b07885ab715548d20d89c9a972854": {"t": 1785674229.8027813, "n": 16004, "h": "97572f8a43341781", "c": "# Authentication\n\nUrlyn Code supports three authentication methods. Pick the one that matches how you want to run the CLI:\n\n- **Qwen OAuth**: sign in with your `qwen.ai` account in a browser. Free with a daily quota.\n- **Alibaba Cloud Coding Plan**: use an API key from Alibaba Cloud. Paid subscription with diverse model options and higher quotas.\n- **API Key**: bring your own API key. Flexible to your own needs — supports OpenAI, Anthropic, Gemini, and other compatible endpoints.\n\n## Option 1: Qwen OAuth (Free)\n\nUse this if you want the simplest setup and you're using Qwen models.\n\n- **How it works**: on first start, Urlyn Code opens a browser login page. After you finish, credentials are cached locally so you usually won't need to log in again.\n- **Requirements**: a `qwen.ai` account + internet access (at least for the first login).\n- **Benefits**: no API key management, automatic credential refresh.\n- **Cost & quota**: free, with a quota of **60 requests/minute** and **1,000 requests/day**.\n\nStart the CLI and follow the browser flow:\n\n```bash\nqwen\n```\n\nOr authenticate directly without starting a session:\n\n```bash\nqwen auth qwen-oauth\n```\n\n> [!note]\n>\n> In non-interactive or headless environments (e.g., CI, SSH, containers), you typically **cannot** complete the OAuth browser login flow. \n> In these cases, please use the Alibaba Cloud Coding Plan or API Key authentication method.\n\n## 💳 Option 2: Alibaba Cloud Coding Plan\n\nUse this if you want predictable costs with diverse model options and higher usage quotas.\n\n- **How it works**: Subscribe to the Coding Plan with a fixed monthly fee, then configure Urlyn Code to use the dedicated endpoint and your subscription API key.\n- **Requirements**: Obtain an active Coding Plan subscription from [Alibaba Cloud ModelStudio(Beijing)](https://bailian.console.aliyun.com/cn-beijing?tab=coding-plan#/efm/coding-plan-index) or [Alibaba Cloud ModelStudio(intl)](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index), depending on the region of your account.\n- **Benefits**: Diverse model options, higher usage quotas, predictable monthly costs, access to a wide range of models (Qwen, GLM, Kimi, Minimax and more).\n- **Cost & quota**: View Aliyun ModelStudio Coding Plan documentation[Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3005961)[intl](https://modelstudio.console.alibabacloud.com/?tab=doc#/doc/?type=model&url=2840914).\n\nAlibaba Cloud Coding Plan is available in two regions:\n\n| Region | Console URL |\n| ---------------------------- | ---------------------------------------------------------------------------- |\n| Aliyun ModelStudio (Beijing) | [bailian.console.aliyun.com](https://bailian.console.aliyun.com) |\n| Alibaba Cloud (intl) | [bailian.console.alibabacloud.com](https://bailian.console.alibabacloud.com) |\n\n### Interactive setup\n\nYou can set up Coding Plan authentication in two ways:\n\n**Option A: From the terminal (recommended for first-time setup)**\n\n```bash\n# Interactive — prompts for region and API key\nqwen auth coding-plan\n\n# Or non-interactive — pass region and key directly\nqwen auth coding-plan --region china --key sk-sp-xxxxxxxxx\n```\n\n**Option B: Inside a Urlyn Code session**\n\nEnter `qwen` in the terminal to launch Urlyn Code, then run the `/auth` command and select **Alibaba Cloud Coding Plan**. Choose your region, then enter your `sk-sp-xxxxxxxxx` key.\n\nAfter authentication, use the `/model` command to switch between all Alibaba Cloud Coding Plan supported models (including qwen3.5-plus, qwen3-coder-plus, qwen3-coder-next, qwen3-max, glm-4.7, and kimi-k2.5).\n\n### Alternative: configure via `settings.json`\n\nIf you prefer to skip the interactive `/auth` flow, add the following to `~/.qwen/settings.json`:\n\n```json\n{\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"qwen3-coder-plus\",\n \"name\": \"qwen3-coder-plus (Coding Plan)\",\n \"baseUrl\": \"https://coding.dashscope.aliyuncs.com/v1\",\n \"description\": \"qwen3-coder-plus from Alibaba Cloud Coding Plan\",\n \"envKey\": \"BAILIAN_CODING_PLAN_API_KEY\"\n }\n ]\n },\n \"env\": {\n \"BAILIAN_CODING_PLAN_API_KEY\": \"sk-sp-xxxxxxxxx\"\n },\n \"security\": {\n \"auth\": {\n \"selectedType\": \"openai\"\n }\n },\n \"model\": {\n \"name\": \"qwen3-coder-plus\"\n }\n}\n```\n\n> [!note]\n>\n> The Coding Plan uses a dedicated endpoint (`https://coding.dashscope.aliyuncs.com/v1`) that is different from the standard Dashscope endpoint. Make sure to use the correct `baseUrl`.\n\n## 🚀 Option 3: API Key (flexible)\n\nUse this if you want to connect to third-party providers such as OpenAI, Anthropic, Google, Azure OpenAI, OpenRouter, ModelScope, or a self-hosted endpoint. Supports multiple protocols and providers.\n\n### Recommended: One-file setup via `settings.json`\n\nThe simplest way to get started with API Key authentication is to put everything in a single `~/.qwen/settings.json` file. Here's a complete, ready-to-use example:\n\n```json\n{\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"qwen3-coder-plus\",\n \"name\": \"qwen3-coder-plus\",\n \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode/v1\",\n \"description\": \"Qwen3-Coder via Dashscope\",\n \"envKey\": \"DASHSCOPE_API_KEY\"\n }\n ]\n },\n \"env\": {\n \"DASHSCOPE_API_KEY\": \"sk-xxxxxxxxxxxxx\"\n },\n \"security\": {\n \"auth\": {\n \"selectedType\": \"openai\"\n }\n },\n \"model\": {\n \"name\": \"qwen3-coder-plus\"\n }\n}\n```\n\nWhat each field does:\n\n| Field | Description |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `modelProviders` | Declares which models are available and how to connect to them. Keys (`openai`, `anthropic`, `gemini`) represent the API protocol. |\n| `env` | Stores API keys directly in `settings.json` as a fallback (lowest priority — shell `export` and `.env` files take precedence). |\n| `security.auth.selectedType` | Tells Urlyn Code which protocol to use on startup (e.g. `openai`, `anthropic`, `gemini`). Without this, you'd need to run `/auth` interactively. |\n| `model.name` | The default model to activate when Urlyn Code starts. Must match one of the `id` values in your `modelProviders`. |\n\nAfter saving the file, just run `qwen` — no interactive `/auth` setup needed.\n\n> [!tip]\n>\n> The sections below explain each part in more detail. If the quick example above works for you, feel free to skip ahead to [Security notes](#security-notes).\n\nThe key concept is **Model Providers** (`modelProviders`): Urlyn Code supports multiple API protocols, not just OpenAI. You configure which providers and models are available by editing `~/.qwen/settings.json`, then switch between them at runtime with the `/model` command.\n\n#### Supported protocols\n\n| Protocol | `modelProviders` key | Environment variables | Providers |\n| ----------------- | -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |\n| OpenAI-compatible | `openai` | `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` | OpenAI, Azure OpenAI, OpenRouter, ModelScope, Alibaba Cloud, any OpenAI-compatible endpoint |\n| Anthropic | `anthropic` | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL` | Anthropic Claude |\n| Google GenAI | `gemini` | `GEMINI_API_KEY`, `GEMINI_MODEL` | Google Gemini |\n\n#### Step 1: Configure models and providers in `~/.qwen/settings.json`\n\nDefine which models are available for each protocol. Each model entry requires at minimum an `id` and an `envKey` (the environment variable name that holds your API key).\n\n> [!important]\n>\n> It is recommended to define `modelProviders` in the user-scope `~/.qwen/settings.json` to avoid merge conflicts between project and user settings.\n\nEdit `~/.qwen/settings.json` (create it if it doesn't exist). You can mix multiple protocols in a single file — here is a multi-provider example showing just the `modelProviders` section:\n\n```json\n{\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"gpt-4o\",\n \"name\": \"GPT-4o\",\n \"envKey\": \"OPENAI_API_KEY\",\n \"baseUrl\": \"https://api.openai.com/v1\"\n }\n ],\n \"anthropic\": [\n {\n \"id\": \"claude-sonnet-4-20250514\",\n \"name\": \"Claude Sonnet 4\",\n \"envKey\": \"ANTHROPIC_API_KEY\"\n }\n ],\n \"gemini\": [\n {\n \"id\": \"gemini-2.5-pro\",\n \"name\": \"Gemini 2.5 Pro\",\n \"envKey\": \"GEMINI_API_KEY\"\n }\n ]\n }\n}\n```\n\n> [!tip]\n>\n> Don't forget to also set `env`, `security.auth.selectedType`, and `model.name` alongside `modelProviders` — see the [complete example above](#recommended-one-file-setup-via-settingsjson) for reference.\n\n**`ModelConfig` fields (each entry inside `modelProviders`):**\n\n| Field | Required | Description |\n| ------------------ | -------- | -------------------------------------------------------------------- |\n| `id` | Yes | Model ID sent to the API (e.g. `gpt-4o`, `claude-sonnet-4-20250514`) |\n| `name` | No | Display name in the `/model` picker (defaults to `id`) |\n| `envKey` | Yes | Environment variable name for the API key (e.g. `OPENAI_API_KEY`) |\n| `baseUrl` | No | API endpoint override (useful for proxies or custom endpoints) |\n| `generationConfig` | No | Fine-tune `timeout`, `maxRetries`, `samplingParams`, etc. |\n\n> [!note]\n>\n> When using the `env` field in `settings.json`, credentials are stored in plain text. For better security, prefer `.env` files or shell `export` — see [Step 2](#step-2-set-environment-variables).\n\nFor the full `modelProviders` schema and advanced options like `generationConfig`, `customHeaders`, and `extra_body`, see [Model Providers Reference](model-providers.md).\n\n#### Step 2: Set environment variables\n\nUrlyn Code reads API keys from environment variables (specified by `envKey` in your model config). There are multiple ways to provide them, listed below from **highest to lowest priority**:\n\n**1. Shell environment / `export` (highest priority)**\n\nSet directly in your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) or inline before launching:\n\n```bash\n\n# Alibaba Dashscope\nexport DASHSCOPE_API_KEY=\"sk-...\"\n\n# OpenAI / OpenAI-compatible\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Anthropic\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# Google GenAI\nexport GEMINI_API_KEY=\"AIza...\"\n```\n\n**2. `.env` files**\n\nUrlyn Code auto-loads the **first** `.env` file it finds (variables are **not merged** across multiple files). Only variables not already present in `process.env` are loaded.\n\nSearch order (from the current directory, walking upward toward `/`):\n\n1. `.qwen/.env` (preferred — keeps Urlyn Code variables isolated from other tools)\n2. `.env`\n\nIf nothing is found, it falls back to your **home directory**:\n\n3. `~/.qwen/.env`\n4. `~/.env`\n\n> [!tip]\n>\n> `.qwen/.env` is recommended over `.env` to avoid conflicts with other tools. Some variables (like `DEBUG` and `DEBUG_MODE`) are excluded from project-level `.env` files to avoid interfering with Urlyn Code behavior.\n\n**3. `settings.json` → `env` field (lowest priority)**\n\nYou can also define API keys directly in `~/.qwen/settings.json` under the `env` key. These are loaded as the **lowest-priority fallback** — only applied when a variable is not already set by the system environment or `.env` files.\n\n```json\n{\n \"env\": {\n \"DASHSCOPE_API_KEY\": \"sk-...\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"ANTHROPIC_API_KEY\": \"sk-ant-...\"\n }\n}\n```\n\nThis is the approach used in the [one-file setup example](#recommended-one-file-setup-via-settingsjson) above. It's convenient for keeping everything in one place, but be mindful that `settings.json` may be shared or synced — prefer `.env` files for sensitive secrets.\n\n**Priority summary:**\n\n| Priority | Source | Override behavior |\n| ----------- | ------------------------------ | -------------------------------------------- |\n| 1 (highest) | CLI flags (`--openai-api-key`) | Always wins |\n| 2 | System env (`export`, inline) | Overrides `.env` and `settings.json` → `env` |\n| 3 | `.env` file | Only sets if not in system env |\n| 4 (lowest) | `settings.json` → `env` | Only sets if not in system env or `.env` |\n\n#### Step 3: Switch models with `/model`\n\nAfter launching Urlyn Code, use the `/model` command to switch between all configured models. Models are grouped by protocol:\n\n```\n/model\n```\n\nThe picker will show all models from your `modelProviders` configuration, grouped by their protocol (e.g. `openai`, `anthropic`, `gemini`). Your selection is persisted across sessions.\n\nYou can also switch models directly with a command-line argument, which is convenient when working across multiple terminals.\n\n```bash\n# In one terminal\n\nqwen --model \"qwen3-coder-plus\"\n\n# In another terminal\n\nqwen --model \"qwen3.5-plus\"\n```\n\n## `qwen auth` CLI command\n\nIn addition to the in-session `/auth` slash command, Urlyn Code provides a standalone `qwen auth` CLI command for managing authentication directly from the terminal — without starting an interactive session first.\n\n### Interactive mode\n\nRun `qwen auth` without arguments to get an interactive menu:\n\n```bash\nqwen auth\n```\n\nYou'll see a selector with arrow-key navigation:\n\n```\nSelect authentication method:\n\n> Qwen OAuth - Free · Up to 1,000 requests/day · Qwen latest models\n Alibaba Cloud Coding Plan - Paid · Up to 6,000 requests/5 hrs · All Alibaba Cloud Coding Plan Models\n\n(Use ↑ ↓ arrows to navigate, Enter to select, Ctrl+C to exit)\n```\n\n### Subcommands\n\n| Command | Description |\n| ---------------------------------------------------- | ------------------------------------------------- |\n| `qwen auth` | Interactive authentication setup |\n| `qwen auth qwen-oauth` | Authenticate with Qwen OAuth |\n| `qwen auth coding-plan` | Authenticate with Alibaba Cloud Coding Plan |\n| `qwen auth coding-plan --region china --key sk-sp-…` | Non-interactive Coding Plan setup (for scripting) |\n| `qwen auth status` | Show current authentication status |\n\n**Examples:**\n\n```bash\n# Authenticate with Qwen OAuth directly\nqwen auth qwen-oauth\n\n# Set up Coding Plan interactively (prompts for region and key)\nqwen auth coding-plan\n\n# Set up Coding Plan non-interactively (useful for CI/scripting)\nqwen auth coding-plan --region china --key sk-sp-xxxxxxxxx\n\n# Check your current auth configuration\nqwen auth status\n```\n\n## Security notes\n\n- Don't commit API keys to version control.\n- Prefer `.qwen/.env` for project-local secrets (and keep it out of git).\n- Treat your terminal output as sensitive if it prints credentials for verification.\n"}}}} |