-
-
[](https://www.npmjs.com/package/@qwen-code/qwen-code)
[](./LICENSE)
[](https://nodejs.org/)
[](https://www.npmjs.com/package/@qwen-code/qwen-code)
-**AI-powered command-line workflow tool for developers**
+**An open-source AI agent that lives in your terminal.**
-[Installation](#installation) • [Quick Start](#quick-start) • [Features](#key-features) • [Documentation](./docs/) • [Contributing](./CONTRIBUTING.md)
+中文 |
+Deutsch |
+français |
+日本語 |
+Русский |
+Português (Brasil)
-
+Qwen Code is an open-source AI agent for the terminal, optimized for [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder). It helps you understand large codebases, automate tedious work, and ship faster.
-Qwen Code is a powerful command-line AI workflow tool adapted from [**Gemini CLI**](https://github.com/google-gemini/gemini-cli), specifically optimized for [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) models. It enhances your development workflow with advanced code understanding, automated tasks, and intelligent assistance.
+
-## 💡 Free Options Available
+## Why Qwen Code?
-Get started with Qwen Code at no cost using any of these free options:
-
-### 🔥 Qwen OAuth (Recommended)
-
-- **2,000 requests per day** with no token limits
-- **60 requests per minute** rate limit
-- Simply run `qwen` and authenticate with your qwen.ai account
-- Automatic credential management and refresh
-- Use `/auth` command to switch to Qwen OAuth if you have initialized with OpenAI compatible mode
-
-### 🌏 Regional Free Tiers
-
-- **Mainland China**: ModelScope offers **2,000 free API calls per day**
-- **International**: OpenRouter provides **up to 1,000 free API calls per day** worldwide
-
-For detailed setup instructions, see [Authorization](#authorization).
-
-> [!WARNING]
-> **Token Usage Notice**: Qwen Code may issue multiple API calls per cycle, resulting in higher token usage (similar to Claude Code). We're actively optimizing API efficiency.
-
-## Key Features
-
-- **Code Understanding & Editing** - Query and edit large codebases beyond traditional context window limits
-- **Workflow Automation** - Automate operational tasks like handling pull requests and complex rebases
-- **Enhanced Parser** - Adapted parser specifically optimized for Qwen-Coder models
-- **Vision Model Support** - Automatically detect images in your input and seamlessly switch to vision-capable models for multimodal analysis
+- **OpenAI-compatible, OAuth free tier**: use an OpenAI-compatible API, or sign in with Qwen OAuth to get 2,000 free requests/day.
+- **Open-source, co-evolving**: both the framework and the Qwen3-Coder model are open-source—and they ship and evolve together.
+- **Agentic workflow, feature-rich**: rich built-in tools (Skills, SubAgents, Plan Mode) for a full agentic workflow and a Claude Code-like experience.
+- **Terminal-first, IDE-friendly**: built for developers who live in the command line, with optional integration for VS Code and Zed.
## Installation
-### Prerequisites
-
-Ensure you have [Node.js version 20](https://nodejs.org/en/download) or higher installed.
+#### Prerequisites
```bash
+# Node.js 20+
curl -qL https://www.npmjs.com/install.sh | sh
```
-### Install from npm
+#### NPM (recommended)
```bash
npm install -g @qwen-code/qwen-code@latest
-qwen --version
```
-### Install from source
-
-```bash
-git clone https://github.com/QwenLM/qwen-code.git
-cd qwen-code
-npm install
-npm install -g .
-```
-
-### Install globally with Homebrew (macOS/Linux)
+#### Homebrew (macOS, Linux)
```bash
brew install qwen-code
@@ -91,286 +51,102 @@ brew install qwen-code
## Quick Start
```bash
-# Start Qwen Code
+# Start Qwen Code (interactive)
qwen
-# Example commands
-> Explain this codebase structure
-> Help me refactor this function
-> Generate unit tests for this module
+# Then, in the session:
+/help
+/auth
```
-### Session Management
+On first use, you'll be prompted to sign in. You can run `/auth` anytime to switch authentication methods.
-Control your token usage with configurable session limits to optimize costs and performance.
+Example prompts:
-#### Configure Session Token Limit
-
-Create or edit `.qwen/settings.json` in your home directory:
-
-```json
-{
- "sessionTokenLimit": 32000
-}
+```text
+What does this project do?
+Explain the codebase structure.
+Help me refactor this function.
+Generate unit tests for this module.
```
-#### Session Commands
-
-- **`/compress`** - Compress conversation history to continue within token limits
-- **`/clear`** - Clear all conversation history and start fresh
-- **`/stats`** - Check current token usage and limits
-
-> 📝 **Note**: Session token limit applies to a single conversation, not cumulative API calls.
-
-### Vision Model Configuration
-
-Qwen Code includes intelligent vision model auto-switching that detects images in your input and can automatically switch to vision-capable models for multimodal analysis. **This feature is enabled by default** - when you include images in your queries, you'll see a dialog asking how you'd like to handle the vision model switch.
-
-#### Skip the Switch Dialog (Optional)
-
-If you don't want to see the interactive dialog each time, configure the default behavior in your `.qwen/settings.json`:
-
-```json
-{
- "experimental": {
- "vlmSwitchMode": "once"
- }
-}
-```
-
-**Available modes:**
-
-- **`"once"`** - Switch to vision model for this query only, then revert
-- **`"session"`** - Switch to vision model for the entire session
-- **`"persist"`** - Continue with current model (no switching)
-- **Not set** - Show interactive dialog each time (default)
-
-#### Command Line Override
-
-You can also set the behavior via command line:
-
-```bash
-# Switch once per query
-qwen --vlm-switch-mode once
-
-# Switch for entire session
-qwen --vlm-switch-mode session
-
-# Never switch automatically
-qwen --vlm-switch-mode persist
-```
-
-#### Disable Vision Models (Optional)
-
-To completely disable vision model support, add to your `.qwen/settings.json`:
-
-```json
-{
- "experimental": {
- "visionModelPreview": false
- }
-}
-```
-
-> 💡 **Tip**: In YOLO mode (`--yolo`), vision switching happens automatically without prompts when images are detected.
-
-### Authorization
-
-Choose your preferred authentication method based on your needs:
-
-#### 1. Qwen OAuth (🚀 Recommended - Start in 30 seconds)
-
-The easiest way to get started - completely free with generous quotas:
-
-```bash
-# Just run this command and follow the browser authentication
-qwen
-```
-
-**What happens:**
-
-1. **Instant Setup**: CLI opens your browser automatically
-2. **One-Click Login**: Authenticate with your qwen.ai account
-3. **Automatic Management**: Credentials cached locally for future use
-4. **No Configuration**: Zero setup required - just start coding!
-
-**Free Tier Benefits:**
-
-- ✅ **2,000 requests/day** (no token counting needed)
-- ✅ **60 requests/minute** rate limit
-- ✅ **Automatic credential refresh**
-- ✅ **Zero cost** for individual users
-- ℹ️ **Note**: Model fallback may occur to maintain service quality
-
-#### 2. OpenAI-Compatible API
-
-Use API keys for OpenAI or other compatible providers:
-
-**Configuration Methods:**
-
-1. **Environment Variables**
-
- ```bash
- export OPENAI_API_KEY="your_api_key_here"
- export OPENAI_BASE_URL="your_api_endpoint"
- export OPENAI_MODEL="your_model_choice"
- ```
-
-2. **Project `.env` File**
- Create a `.env` file in your project root:
- ```env
- OPENAI_API_KEY=your_api_key_here
- OPENAI_BASE_URL=your_api_endpoint
- OPENAI_MODEL=your_model_choice
- ```
-
-**API Provider Options**
-
-> ⚠️ **Regional Notice:**
->
-> - **Mainland China**: Use Alibaba Cloud Bailian or ModelScope
-> - **International**: Use Alibaba Cloud ModelStudio or OpenRouter
-
-
-🇨🇳 For Users in Mainland China
+Click to watch a demo video
-**Option 1: Alibaba Cloud Bailian** ([Apply for API Key](https://bailian.console.aliyun.com/)) - -```bash -export OPENAI_API_KEY="your_api_key_here" -export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" -export OPENAI_MODEL="qwen3-coder-plus" -``` - -**Option 2: ModelScope (Free Tier)** ([Apply for API Key](https://modelscope.cn/docs/model-service/API-Inference/intro)) - -- ✅ **2,000 free API calls per day** -- ⚠️ Connect your Aliyun account to avoid authentication errors - -```bash -export OPENAI_API_KEY="your_api_key_here" -export OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1" -export OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct" -``` +
-
+For details (including `.qwen/.env` loading and security notes), see the [authentication guide](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/auth/).
-## Usage Examples
+## Usage
-### 🔍 Explore Codebases
+As an open-source terminal agent, you can use Qwen Code in four primary ways:
+
+1. Interactive mode (terminal UI)
+2. Headless mode (scripts, CI)
+3. IDE integration (VS Code, Zed)
+4. TypeScript SDK
+
+#### Interactive mode
```bash
cd your-project/
qwen
-
-# Architecture analysis
-> Describe the main pieces of this system's architecture
-> What are the key dependencies and how do they interact?
-> Find all API endpoints and their authentication methods
```
-### 💻 Code Development
+Run `qwen` in your project folder to launch the interactive terminal UI. Use `@` to reference local files (for example `@src/main.ts`).
+
+#### Headless mode
```bash
-# Refactoring
-> Refactor this function to improve readability and performance
-> Convert this class to use dependency injection
-> Split this large module into smaller, focused components
-
-# Code generation
-> Create a REST API endpoint for user management
-> Generate unit tests for the authentication module
-> Add error handling to all database operations
+cd your-project/
+qwen -p "your question"
```
-### 🔄 Automate Workflows
+Use `-p` to run Qwen Code without the interactive UI—ideal for scripts, automation, and CI/CD. Learn more: [Headless mode](https://qwenlm.github.io/qwen-code-docs/en/users/features/headless).
-```bash
-# Git automation
-> Analyze git commits from the last 7 days, grouped by feature
-> Create a changelog from recent commits
-> Find all TODO comments and create GitHub issues
+#### IDE integration
-# File operations
-> Convert all images in this directory to PNG format
-> Rename all test files to follow the *.test.ts pattern
-> Find and remove all console.log statements
-```
+Use Qwen Code inside your editor (VS Code and Zed):
-### 🐛 Debugging & Analysis
+- [Use in VS Code](https://qwenlm.github.io/qwen-code-docs/en/users/integration-vscode/)
+- [Use in Zed](https://qwenlm.github.io/qwen-code-docs/en/users/integration-zed/)
-```bash
-# Performance analysis
-> Identify performance bottlenecks in this React component
-> Find all N+1 query problems in the codebase
+#### TypeScript SDK
-# Security audit
-> Check for potential SQL injection vulnerabilities
-> Find all hardcoded credentials or API keys
-```
+Build on top of Qwen Code with the TypeScript SDK:
-## Popular Tasks
-
-### 📚 Understand New Codebases
-
-```text
-> What are the core business logic components?
-> What security mechanisms are in place?
-> How does the data flow through the system?
-> What are the main design patterns used?
-> Generate a dependency graph for this module
-```
-
-### 🔨 Code Refactoring & Optimization
-
-```text
-> What parts of this module can be optimized?
-> Help me refactor this class to follow SOLID principles
-> Add proper error handling and logging
-> Convert callbacks to async/await pattern
-> Implement caching for expensive operations
-```
-
-### 📝 Documentation & Testing
-
-```text
-> Generate comprehensive JSDoc comments for all public APIs
-> Write unit tests with edge cases for this component
-> Create API documentation in OpenAPI format
-> Add inline comments explaining complex algorithms
-> Generate a README for this module
-```
-
-### 🚀 Development Acceleration
-
-```text
-> Set up a new Express server with authentication
-> Create a React component with TypeScript and tests
-> Implement a rate limiter middleware
-> Add database migrations for new schema
-> Configure CI/CD pipeline for this project
-```
+- [Use the Qwen Code SDK](./packages/sdk-typescript/README.md)
## Commands & Shortcuts
@@ -380,6 +156,7 @@ qwen
- `/clear` - Clear conversation history
- `/compress` - Compress history to save tokens
- `/stats` - Show current session information
+- `/bug` - Submit a bug report
- `/exit` or `/quit` - Exit Qwen Code
### Keyboard Shortcuts
@@ -388,6 +165,19 @@ qwen
- `Ctrl+D` - Exit (on empty line)
- `Up/Down` - Navigate command history
+> Learn more about [Commands](https://qwenlm.github.io/qwen-code-docs/en/users/features/commands/)
+>
+> **Tip**: In YOLO mode (`--yolo`), vision switching happens automatically without prompts when images are detected. Learn more about [Approval Mode](https://qwenlm.github.io/qwen-code-docs/en/users/features/approval-mode/)
+
+## Configuration
+
+Qwen Code can be configured via `settings.json`, environment variables, and CLI flags.
+
+- **User settings**: `~/.qwen/settings.json`
+- **Project settings**: `.qwen/settings.json`
+
+See [settings](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/) for available options and precedence.
+
## Benchmark Results
### Terminal-Bench Performance
@@ -397,24 +187,18 @@ qwen
| Qwen Code | Qwen3-Coder-480A35 | 37.5% |
| Qwen Code | Qwen3-Coder-30BA3B | 31.3% |
-## Development & Contributing
+## Ecosystem
-See [CONTRIBUTING.md](./CONTRIBUTING.md) to learn how to contribute to the project.
+Looking for a graphical interface?
-For detailed authentication setup, see the [authentication guide](./docs/cli/authentication.md).
+- [**Gemini CLI Desktop**](https://github.com/Piebald-AI/gemini-cli-desktop) A cross-platform desktop/web/mobile UI for Qwen Code
## Troubleshooting
-If you encounter issues, check the [troubleshooting guide](docs/troubleshooting.md).
+If you encounter issues, check the [troubleshooting guide](https://qwenlm.github.io/qwen-code-docs/en/users/support/troubleshooting/).
+
+To report a bug from within the CLI, run `/bug` and include a short title and repro steps.
## Acknowledgments
This project is based on [Google Gemini CLI](https://github.com/google-gemini/gemini-cli). We acknowledge and appreciate the excellent work of the Gemini CLI team. Our main contribution focuses on parser-level adaptations to better support Qwen-Coder models.
-
-## License
-
-[LICENSE](./LICENSE)
-
-## Star History
-
-[](https://www.star-history.com/#QwenLM/qwen-code&Date)
diff --git a/docs-site/README.md b/docs-site/README.md
new file mode 100644
index 000000000..ad6272c33
--- /dev/null
+++ b/docs-site/README.md
@@ -0,0 +1,54 @@
+# Qwen Code Docs Site
+
+A documentation website for Qwen Code built with [Next.js](https://nextjs.org/) and [Nextra](https://nextra.site/).
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+### Installation
+
+```bash
+npm install
+```
+
+### Setup Content
+
+Link the documentation content from the parent `docs` directory:
+
+```bash
+npm run link
+```
+
+This creates a symbolic link from `../docs` to `content` in the project.
+
+### Development
+
+Start the development server:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser to see the documentation site.
+
+## Project Structure
+
+```
+docs-site/
+├── src/
+│ └── app/
+│ ├── [[...mdxPath]]/ # Dynamic routing for MDX pages
+│ │ └── page.jsx
+│ └── layout.jsx # Root layout with navbar and footer
+├── mdx-components.js # MDX component configuration
+├── next.config.mjs # Next.js configuration
+└── package.json
+```
+
+## License
+
+MIT © Qwen Team
diff --git a/docs-site/mdx-components.js b/docs-site/mdx-components.js
new file mode 100644
index 000000000..ad856fe44
--- /dev/null
+++ b/docs-site/mdx-components.js
@@ -0,0 +1,12 @@
+import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs'; // nextra-theme-blog or your custom theme
+
+// Get the default MDX components
+const themeComponents = getThemeComponents();
+
+// Merge components
+export function useMDXComponents(components) {
+ return {
+ ...themeComponents,
+ ...components,
+ };
+}
diff --git a/docs-site/next-env.d.ts b/docs-site/next-env.d.ts
new file mode 100644
index 000000000..20e7bcfb0
--- /dev/null
+++ b/docs-site/next-env.d.ts
@@ -0,0 +1,6 @@
+/// 🌍 For International Users
+## Authentication -**Option 1: Alibaba Cloud ModelStudio** ([Apply for API Key](https://modelstudio.console.alibabacloud.com/)) +Qwen Code supports two authentication methods: + +- **Qwen OAuth (recommended & free)**: sign in with your `qwen.ai` account in a browser. +- **OpenAI-compatible API**: use `OPENAI_API_KEY` (and optionally a custom base URL / model). + +#### Qwen OAuth (recommended) + +Start `qwen`, then run: ```bash -export OPENAI_API_KEY="your_api_key_here" -export OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1" -export OPENAI_MODEL="qwen3-coder-plus" +/auth ``` -**Option 2: OpenRouter (Free Tier Available)** ([Apply for API Key](https://openrouter.ai/)) +Choose **Qwen OAuth** and complete the browser flow. Your credentials are cached locally so you usually won't need to log in again. + +#### OpenAI-compatible API (API key) + +Environment variables (recommended for CI / headless environments): ```bash -export OPENAI_API_KEY="your_api_key_here" -export OPENAI_BASE_URL="https://openrouter.ai/api/v1" -export OPENAI_MODEL="qwen/qwen3-coder:free" +export OPENAI_API_KEY="your-api-key-here" +export OPENAI_BASE_URL="https://api.openai.com/v1" # optional +export OPENAI_MODEL="gpt-4o" # optional ``` -packages/cli/src/*.ts"] - B["packages/cli/package.json"] - C["README.md
LICENSE
packages/cli/src/utils/*.sb"] - end - - subgraph "Process" - D(Build) - E(Transform) - F(Assemble) - G(Publish) - end - - subgraph "Artifacts" - H["Bundled JS"] - I["Final package.json"] - J["bundle/"] - end - - subgraph "Destination" - K["NPM Registry"] - end - - A --> D --> H - B --> E --> I - C --> F - H --> F - I --> F - F --> J - J --> G --> K -``` - This process ensures that the final published artifact is a purpose-built, clean, and efficient representation of the project, rather than a direct copy of the development workspace. diff --git a/docs/development/telemetry.md b/docs/developers/development/telemetry.md similarity index 68% rename from docs/development/telemetry.md rename to docs/developers/development/telemetry.md index 5ea185a38..f5faee40e 100644 --- a/docs/development/telemetry.md +++ b/docs/developers/development/telemetry.md @@ -6,13 +6,12 @@ Learn how to enable and setup OpenTelemetry for Qwen Code. - [Key Benefits](#key-benefits) - [OpenTelemetry Integration](#opentelemetry-integration) - [Configuration](#configuration) - - [Google Cloud Telemetry](#google-cloud-telemetry) + - [Aliyun Telemetry](#aliyun-telemetry) - [Prerequisites](#prerequisites) - [Direct Export (Recommended)](#direct-export-recommended) - - [Collector-Based Export (Advanced)](#collector-based-export-advanced) - [Local Telemetry](#local-telemetry) - [File-based Output (Recommended)](#file-based-output-recommended) - - [Collector-Based Export (Advanced)](#collector-based-export-advanced-1) + - [Collector-Based Export (Advanced)](#collector-based-export-advanced) - [Logs and Metrics](#logs-and-metrics) - [Logs](#logs) - [Metrics](#metrics) @@ -35,8 +34,8 @@ Learn how to enable and setup OpenTelemetry for Qwen Code. Built on **[OpenTelemetry]** — the vendor-neutral, industry-standard observability framework — Qwen Code's observability system provides: -- **Universal Compatibility**: Export to any OpenTelemetry backend (Google - Cloud, Jaeger, Prometheus, Datadog, etc.) +- **Universal Compatibility**: Export to any OpenTelemetry backend (Aliyun, + Jaeger, Prometheus, Datadog, etc.) - **Standardized Data**: Use consistent formats and collection methods across your toolchain - **Future-Proof Integration**: Connect with existing and future observability @@ -48,18 +47,22 @@ observability framework — Qwen Code's observability system provides: ## Configuration +> [!note] +> +> **⚠️ Special Note: This feature requires corresponding code changes. This documentation is provided in advance; please refer to future code updates for actual functionality.** + All telemetry behavior is controlled through your `.qwen/settings.json` file. These settings can be overridden by environment variables or CLI flags. -| Setting | Environment Variable | CLI Flag | Description | Values | Default | -| -------------- | -------------------------------- | -------------------------------------------------------- | ------------------------------------------------- | ----------------- | ----------------------- | -| `enabled` | `GEMINI_TELEMETRY_ENABLED` | `--telemetry` / `--no-telemetry` | Enable or disable telemetry | `true`/`false` | `false` | -| `target` | `GEMINI_TELEMETRY_TARGET` | `--telemetry-target
✅ Support OpenAI Protocol
✅ Settings
✅ OAuth
✅ Cache Control
✅ Memory
✅ Compress
✅ Theme | Better UI
OnBoarding
LogView
✅ Session
Permission
🔄 Cross-platform Compatibility | +| Coding Workflow | ✅ Slash Commands
✅ MCP
✅ PlanMode
✅ TodoWrite
✅ SubAgent
✅ Multi Model
✅ Chat Management
✅ Tools (WebFetch, Bash, TextSearch, FileReadFile, EditFile) | 🔄 Hooks
SubAgent (enhanced)
✅ Skill
✅ Headless Mode
✅ Tools (WebSearch) | +| Building Open Capabilities | ✅ Custom Commands | ✅ QwenCode SDK
Extension | +| Integrating Community Ecosystem | | ✅ VSCode Plugin
🔄 ACP/Zed
✅ GHA | +| Administrative Capabilities | ✅ Stats
✅ Feedback | Costs
Dashboard | + +> For more details, please see the list below. + +## Features + +#### Completed Features + +| Feature | Version | Description | Category | +| ----------------------- | --------- | ------------------------------------------------------- | ------------------------------- | +| Skill | `V0.6.0` | Extensible custom AI skills | Coding Workflow | +| Github Actions | `V0.5.0` | qwen-code-action and automation | Integrating Community Ecosystem | +| VSCode Plugin | `V0.5.0` | VSCode extension plugin | Integrating Community Ecosystem | +| QwenCode SDK | `V0.4.0` | Open SDK for third-party integration | Building Open Capabilities | +| Session | `V0.4.0` | Enhanced session management | User Experience | +| i18n | `V0.3.0` | Internationalization and multilingual support | User Experience | +| Headless Mode | `V0.3.0` | Headless mode (non-interactive) | Coding Workflow | +| ACP/Zed | `V0.2.0` | ACP and Zed editor integration | Integrating Community Ecosystem | +| Terminal UI | `V0.1.0+` | Interactive terminal user interface | User Experience | +| Settings | `V0.1.0+` | Configuration management system | User Experience | +| Theme | `V0.1.0+` | Multi-theme support | User Experience | +| Support OpenAI Protocol | `V0.1.0+` | Support for OpenAI API protocol | User Experience | +| Chat Management | `V0.1.0+` | Session management (save, restore, browse) | Coding Workflow | +| MCP | `V0.1.0+` | Model Context Protocol integration | Coding Workflow | +| Multi Model | `V0.1.0+` | Multi-model support and switching | Coding Workflow | +| Slash Commands | `V0.1.0+` | Slash command system | Coding Workflow | +| Tool: Bash | `V0.1.0+` | Shell command execution tool (with is_background param) | Coding Workflow | +| Tool: FileRead/EditFile | `V0.1.0+` | File read/write and edit tools | Coding Workflow | +| Custom Commands | `V0.1.0+` | Custom command loading | Building Open Capabilities | +| Feedback | `V0.1.0+` | Feedback mechanism (/bug command) | Administrative Capabilities | +| Stats | `V0.1.0+` | Usage statistics and quota display | Administrative Capabilities | +| Memory | `V0.0.9+` | Project-level and global memory management | User Experience | +| Cache Control | `V0.0.9+` | DashScope cache control | User Experience | +| PlanMode | `V0.0.14` | Task planning mode | Coding Workflow | +| Compress | `V0.0.11` | Chat compression mechanism | User Experience | +| SubAgent | `V0.0.11` | Dedicated sub-agent system | Coding Workflow | +| TodoWrite | `V0.0.10` | Task management and progress tracking | Coding Workflow | +| Tool: TextSearch | `V0.0.8+` | Text search tool (grep, supports .qwenignore) | Coding Workflow | +| Tool: WebFetch | `V0.0.7+` | Web content fetching tool | Coding Workflow | +| Tool: WebSearch | `V0.0.7+` | Web search tool (using Tavily API) | Coding Workflow | +| OAuth | `V0.0.5+` | OAuth login authentication (Qwen OAuth) | User Experience | + +#### Features to Develop + +| Feature | Priority | Status | Description | Category | +| ---------------------------- | -------- | ----------- | --------------------------------- | --------------------------- | +| Better UI | P1 | Planned | Optimized terminal UI interaction | User Experience | +| OnBoarding | P1 | Planned | New user onboarding flow | User Experience | +| Permission | P1 | Planned | Permission system optimization | User Experience | +| Cross-platform Compatibility | P1 | In Progress | Windows/Linux/macOS compatibility | User Experience | +| LogView | P2 | Planned | Log viewing and debugging feature | User Experience | +| Hooks | P2 | In Progress | Extension hooks system | Coding Workflow | +| Extension | P2 | Planned | Extension system | Building Open Capabilities | +| Costs | P2 | Planned | Cost tracking and analysis | Administrative Capabilities | +| Dashboard | P2 | Planned | Management dashboard | Administrative Capabilities | + +#### Distinctive Features to Discuss + +| Feature | Status | Description | +| ---------------- | -------- | ----------------------------------------------------- | +| Home Spotlight | Research | Project discovery and quick launch | +| Competitive Mode | Research | Competitive mode | +| Pulse | Research | User activity pulse analysis (OpenAI Pulse reference) | +| Code Wiki | Research | Project codebase wiki/documentation system | diff --git a/docs/developers/sdk-typescript.md b/docs/developers/sdk-typescript.md new file mode 100644 index 000000000..46625e840 --- /dev/null +++ b/docs/developers/sdk-typescript.md @@ -0,0 +1,375 @@ +# Typescript SDK + +## @qwen-code/sdk + +A minimum experimental TypeScript SDK for programmatic access to Qwen Code. + +Feel free to submit a feature request/issue/PR. + +## Installation + +```bash +npm install @qwen-code/sdk +``` + +## Requirements + +- Node.js >= 20.0.0 +- [Qwen Code](https://github.com/QwenLM/qwen-code) >= 0.4.0 (stable) installed and accessible in PATH + +> **Note for nvm users**: If you use nvm to manage Node.js versions, the SDK may not be able to auto-detect the Qwen Code executable. You should explicitly set the `pathToQwenExecutable` option to the full path of the `qwen` binary. + +## Quick Start + +```typescript +import { query } from '@qwen-code/sdk'; + +// Single-turn query +const result = query({ + prompt: 'What files are in the current directory?', + options: { + cwd: '/path/to/project', + }, +}); + +// Iterate over messages +for await (const message of result) { + if (message.type === 'assistant') { + console.log('Assistant:', message.message.content); + } else if (message.type === 'result') { + console.log('Result:', message.result); + } +} +``` + +## API Reference + +### `query(config)` + +Creates a new query session with the Qwen Code. + +#### Parameters + +- `prompt`: `string | AsyncIterable
-
-
-🇨🇳 For Users in Mainland China
- -**Option 1: Alibaba Cloud Bailian** ([Apply for API Key](https://bailian.console.aliyun.com/)) - -```bash -export OPENAI_API_KEY="your_api_key_here" -export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" -export OPENAI_MODEL="qwen3-coder-plus" -``` - -**Option 2: ModelScope (Free Tier)** ([Apply for API Key](https://modelscope.cn/docs/model-service/API-Inference/intro)) - -- ✅ **2,000 free API calls per day** -- ⚠️ Connect your Aliyun account to avoid authentication errors - -```bash -export OPENAI_API_KEY="your_api_key_here" -export OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1" -export OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct" -``` - -
-
-
-## Usage Examples
-
-### 🔍 Explore Codebases
-
-```bash
-cd your-project/
-qwen
-
-# Architecture analysis
-> Describe the main pieces of this system's architecture
-> What are the key dependencies and how do they interact?
-> Find all API endpoints and their authentication methods
-```
-
-### 💻 Code Development
-
-```bash
-# Refactoring
-> Refactor this function to improve readability and performance
-> Convert this class to use dependency injection
-> Split this large module into smaller, focused components
-
-# Code generation
-> Create a REST API endpoint for user management
-> Generate unit tests for the authentication module
-> Add error handling to all database operations
-```
-
-### 🔄 Automate Workflows
-
-```bash
-# Git automation
-> Analyze git commits from the last 7 days, grouped by feature
-> Create a changelog from recent commits
-> Find all TODO comments and create GitHub issues
-
-# File operations
-> Convert all images in this directory to PNG format
-> Rename all test files to follow the *.test.ts pattern
-> Find and remove all console.log statements
-```
-
-### 🐛 Debugging & Analysis
-
-```bash
-# Performance analysis
-> Identify performance bottlenecks in this React component
-> Find all N+1 query problems in the codebase
-
-# Security audit
-> Check for potential SQL injection vulnerabilities
-> Find all hardcoded credentials or API keys
-```
-
-## Popular Tasks
-
-### 📚 Understand New Codebases
-
-```text
-> What are the core business logic components?
-> What security mechanisms are in place?
-> How does the data flow through the system?
-> What are the main design patterns used?
-> Generate a dependency graph for this module
-```
-
-### 🔨 Code Refactoring & Optimization
-
-```text
-> What parts of this module can be optimized?
-> Help me refactor this class to follow SOLID principles
-> Add proper error handling and logging
-> Convert callbacks to async/await pattern
-> Implement caching for expensive operations
-```
-
-### 📝 Documentation & Testing
-
-```text
-> Generate comprehensive JSDoc comments for all public APIs
-> Write unit tests with edge cases for this component
-> Create API documentation in OpenAPI format
-> Add inline comments explaining complex algorithms
-> Generate a README for this module
-```
-
-### 🚀 Development Acceleration
-
-```text
-> Set up a new Express server with authentication
-> Create a React component with TypeScript and tests
-> Implement a rate limiter middleware
-> Add database migrations for new schema
-> Configure CI/CD pipeline for this project
-```
-
-## Commands & Shortcuts
-
-### Session Commands
-
-- `/help` - Display available commands
-- `/clear` (aliases: `/reset`, `/new`) - Clear conversation history and start a fresh session
-- `/compress` - Compress history to save tokens
-- `/stats` - Show current session information
-- `/exit` or `/quit` - Exit Qwen Code
-
-### Keyboard Shortcuts
-
-- `Ctrl+C` - Cancel current operation
-- `Ctrl+D` - Exit (on empty line)
-- `Up/Down` - Navigate command history
+- Architecture overview
+- Contributing guidelines
+- Core concepts and implementation details
+- Tools and development workflow
+- Extension and plugin development
diff --git a/docs/mermaid/context.mmd b/docs/mermaid/context.mmd
deleted file mode 100644
index ebe4fbee1..000000000
--- a/docs/mermaid/context.mmd
+++ /dev/null
@@ -1,103 +0,0 @@
-graph LR
- %% --- Style Definitions ---
- classDef new fill:#98fb98,color:#000
- classDef changed fill:#add8e6,color:#000
- classDef unchanged fill:#f0f0f0,color:#000
-
- %% --- Subgraphs ---
- subgraph "Context Providers"
- direction TB
- A["gemini.tsx"]
- B["AppContainer.tsx"]
- end
-
- subgraph "Contexts"
- direction TB
- CtxSession["SessionContext"]
- CtxVim["VimModeContext"]
- CtxSettings["SettingsContext"]
- CtxApp["AppContext"]
- CtxConfig["ConfigContext"]
- CtxUIState["UIStateContext"]
- CtxUIActions["UIActionsContext"]
- end
-
- subgraph "Component Consumers"
- direction TB
- ConsumerApp["App"]
- ConsumerAppContainer["AppContainer"]
- ConsumerAppHeader["AppHeader"]
- ConsumerDialogManager["DialogManager"]
- ConsumerHistoryItem["HistoryItemDisplay"]
- ConsumerComposer["Composer"]
- ConsumerMainContent["MainContent"]
- ConsumerNotifications["Notifications"]
- end
-
- %% --- Provider -> Context Connections ---
- A -.-> CtxSession
- A -.-> CtxVim
- A -.-> CtxSettings
-
- B -.-> CtxApp
- B -.-> CtxConfig
- B -.-> CtxUIState
- B -.-> CtxUIActions
- B -.-> CtxSettings
-
- %% --- Context -> Consumer Connections ---
- CtxSession -.-> ConsumerAppContainer
- CtxSession -.-> ConsumerApp
-
- CtxVim -.-> ConsumerAppContainer
- CtxVim -.-> ConsumerComposer
- CtxVim -.-> ConsumerApp
-
- CtxSettings -.-> ConsumerAppContainer
- CtxSettings -.-> ConsumerAppHeader
- CtxSettings -.-> ConsumerDialogManager
- CtxSettings -.-> ConsumerApp
-
- CtxApp -.-> ConsumerAppHeader
- CtxApp -.-> ConsumerNotifications
-
- CtxConfig -.-> ConsumerAppHeader
- CtxConfig -.-> ConsumerHistoryItem
- CtxConfig -.-> ConsumerComposer
- CtxConfig -.-> ConsumerDialogManager
-
-
-
- CtxUIState -.-> ConsumerApp
- CtxUIState -.-> ConsumerMainContent
- CtxUIState -.-> ConsumerComposer
- CtxUIState -.-> ConsumerDialogManager
-
- CtxUIActions -.-> ConsumerComposer
- CtxUIActions -.-> ConsumerDialogManager
-
- %% --- Apply Styles ---
- %% New Elements (Green)
- class B,CtxApp,CtxConfig,CtxUIState,CtxUIActions,ConsumerAppHeader,ConsumerDialogManager,ConsumerComposer,ConsumerMainContent,ConsumerNotifications new
-
- %% Heavily Changed Elements (Blue)
- class A,ConsumerApp,ConsumerAppContainer,ConsumerHistoryItem changed
-
- %% Mostly Unchanged Elements (Gray)
- class CtxSession,CtxVim,CtxSettings unchanged
-
- %% --- Link Styles ---
- %% CtxSession (Red)
- linkStyle 0,8,9 stroke:#e57373,stroke-width:2px
- %% CtxVim (Orange)
- linkStyle 1,10,11,12 stroke:#ffb74d,stroke-width:2px
- %% CtxSettings (Yellow)
- linkStyle 2,7,13,14,15,16 stroke:#fff176,stroke-width:2px
- %% CtxApp (Green)
- linkStyle 3,17,18 stroke:#81c784,stroke-width:2px
- %% CtxConfig (Blue)
- linkStyle 4,19,20,21,22 stroke:#64b5f6,stroke-width:2px
- %% CtxUIState (Indigo)
- linkStyle 5,23,24,25,26 stroke:#7986cb,stroke-width:2px
- %% CtxUIActions (Violet)
- linkStyle 6,27,28 stroke:#ba68c8,stroke-width:2px
diff --git a/docs/mermaid/render-path.mmd b/docs/mermaid/render-path.mmd
deleted file mode 100644
index 5f4c62044..000000000
--- a/docs/mermaid/render-path.mmd
+++ /dev/null
@@ -1,64 +0,0 @@
-graph TD
- %% --- Style Definitions ---
- classDef new fill:#98fb98,color:#000
- classDef changed fill:#add8e6,color:#000
- classDef unchanged fill:#f0f0f0,color:#000
- classDef dispatcher fill:#f9e79f,color:#000,stroke:#333,stroke-width:1px
- classDef container fill:#f5f5f5,color:#000,stroke:#ccc
-
- %% --- Component Tree ---
- subgraph "Entry Point"
- A["gemini.tsx"]
- end
-
- subgraph "State & Logic Wrapper"
- B["AppContainer.tsx"]
- end
-
- subgraph "Primary Layout"
- C["App.tsx"]
- end
-
- A -.-> B
- B -.-> C
-
- subgraph "UI Containers"
- direction LR
- C -.-> D["MainContent"]
- C -.-> G["Composer"]
- C -.-> F["DialogManager"]
- C -.-> E["Notifications"]
- end
-
- subgraph "MainContent"
- direction TB
- D -.-> H["AppHeader"]
- D -.-> I["HistoryItemDisplay"]:::dispatcher
- D -.-> L["ShowMoreLines"]
- end
-
- subgraph "Composer"
- direction TB
- G -.-> K_Prompt["InputPrompt"]
- G -.-> K_Footer["Footer"]
- end
-
- subgraph "DialogManager"
- F -.-> J["Various Dialogs🌍 For International Users
- -**Option 1: Alibaba Cloud ModelStudio** ([Apply for API Key](https://modelstudio.console.alibabacloud.com/)) - -```bash -export OPENAI_API_KEY="your_api_key_here" -export OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1" -export OPENAI_MODEL="qwen3-coder-plus" -``` - -**Option 2: OpenRouter (Free Tier Available)** ([Apply for API Key](https://openrouter.ai/)) - -```bash -export OPENAI_API_KEY="your_api_key_here" -export OPENAI_BASE_URL="https://openrouter.ai/api/v1" -export OPENAI_MODEL="qwen/qwen3-coder:free" -``` - -(Auth, Theme, Settings, etc.)"] - end - - %% --- Apply Styles --- - class B,D,E,F,G,H,J,K_Prompt,L new - class A,C,I changed - class K_Footer unchanged - - %% --- Link Styles --- - %% MainContent Branch (Blue) - linkStyle 2,6,7,8 stroke:#64b5f6,stroke-width:2px - %% Composer Branch (Green) - linkStyle 3,9,10 stroke:#81c784,stroke-width:2px - %% DialogManager Branch (Orange) - linkStyle 4,11 stroke:#ffb74d,stroke-width:2px - %% Notifications Branch (Violet) - linkStyle 5 stroke:#ba68c8,stroke-width:2px - diff --git a/docs/sidebar.json b/docs/sidebar.json deleted file mode 100644 index b4a750529..000000000 --- a/docs/sidebar.json +++ /dev/null @@ -1,68 +0,0 @@ -[ - { - "label": "Overview", - "items": [ - { "label": "Welcome", "slug": "docs" }, - { "label": "Execution and Deployment", "slug": "docs/deployment" }, - { "label": "Architecture Overview", "slug": "docs/architecture" } - ] - }, - { - "label": "CLI", - "items": [ - { "label": "Introduction", "slug": "docs/cli" }, - { "label": "Authentication", "slug": "docs/cli/authentication" }, - { "label": "Commands", "slug": "docs/cli/commands" }, - { "label": "Configuration", "slug": "docs/cli/configuration" }, - { "label": "Checkpointing", "slug": "docs/checkpointing" }, - { "label": "Extensions", "slug": "docs/extension" }, - { "label": "Headless Mode", "slug": "docs/headless" }, - { "label": "IDE Integration", "slug": "docs/ide-integration" }, - { - "label": "IDE Companion Spec", - "slug": "docs/ide-companion-spec" - }, - { "label": "Telemetry", "slug": "docs/telemetry" }, - { "label": "Themes", "slug": "docs/cli/themes" }, - { "label": "Token Caching", "slug": "docs/cli/token-caching" }, - { "label": "Trusted Folders", "slug": "docs/trusted-folders" }, - { "label": "Tutorials", "slug": "docs/cli/tutorials" } - ] - }, - { - "label": "Core", - "items": [ - { "label": "Introduction", "slug": "docs/core" }, - { "label": "Tools API", "slug": "docs/core/tools-api" }, - { "label": "Memory Import Processor", "slug": "docs/core/memport" } - ] - }, - { - "label": "Tools", - "items": [ - { "label": "Overview", "slug": "docs/tools" }, - { "label": "File System", "slug": "docs/tools/file-system" }, - { "label": "Multi-File Read", "slug": "docs/tools/multi-file" }, - { "label": "Shell", "slug": "docs/tools/shell" }, - { "label": "Web Fetch", "slug": "docs/tools/web-fetch" }, - { "label": "Web Search", "slug": "docs/tools/web-search" }, - { "label": "Memory", "slug": "docs/tools/memory" }, - { "label": "MCP Servers", "slug": "docs/tools/mcp-server" }, - { "label": "Sandboxing", "slug": "docs/sandbox" } - ] - }, - { - "label": "Development", - "items": [ - { "label": "NPM", "slug": "docs/npm" }, - { "label": "Releases", "slug": "docs/releases" } - ] - }, - { - "label": "Support", - "items": [ - { "label": "Troubleshooting", "slug": "docs/troubleshooting" }, - { "label": "Terms of Service", "slug": "docs/tos-privacy" } - ] - } -] diff --git a/docs/users/_meta.ts b/docs/users/_meta.ts new file mode 100644 index 000000000..a44167cff --- /dev/null +++ b/docs/users/_meta.ts @@ -0,0 +1,28 @@ +export default { + 'Getting started': { + type: 'separator', + title: 'Getting started', // Title is optional + }, + overview: 'Overview', + quickstart: 'QuickStart', + 'common-workflow': 'Command Workflows', + 'Outside of the terminal': { + type: 'separator', + title: 'Outside of the terminal', // Title is optional + }, + 'integration-vscode': 'Visual Studio Code', + 'integration-zed': 'Zed IDE', + 'integration-github-action': 'Github Actions', + 'Code with Qwen Code': { + type: 'separator', + title: 'Code with Qwen Code', // Title is optional + }, + features: 'Features', + configuration: 'Configuration', + reference: 'Reference', + support: 'Support', + // need refine + 'ide-integration': { + display: 'hidden', + }, +}; diff --git a/docs/users/common-workflow.md b/docs/users/common-workflow.md new file mode 100644 index 000000000..078447cf1 --- /dev/null +++ b/docs/users/common-workflow.md @@ -0,0 +1,571 @@ +# Common workflows + +> Learn about common workflows with Qwen Code. + +Each task in this document includes clear instructions, example commands, and best practices to help you get the most from Qwen Code. + +## Understand new codebases + +### Get a quick codebase overview + +Suppose you've just joined a new project and need to understand its structure quickly. + +**1. Navigate to the project root directory** + +```bash +cd /path/to/project +``` + +**2. Start Qwen Code** + +```bash +qwen +``` + +**3. Ask for a high-level overview** + +``` +give me an overview of this codebase +``` + +**4. Dive deeper into specific components** + +``` +explain the main architecture patterns used here +``` + +``` +what are the key data models? +``` + +``` +how is authentication handled? +``` + +> [!tip] +> +> - Start with broad questions, then narrow down to specific areas +> - Ask about coding conventions and patterns used in the project +> - Request a glossary of project-specific terms + +### Find relevant code + +Suppose you need to locate code related to a specific feature or functionality. + +**1. Ask Qwen Code to find relevant files** + +``` +find the files that handle user authentication +``` + +**2. Get context on how components interact** + +``` +how do these authentication files work together? +``` + +**3. Understand the execution flow** + +``` +trace the login process from front-end to database +``` + +> [!tip] +> +> - Be specific about what you're looking for +> - Use domain language from the project + +## Fix bugs efficiently + +Suppose you've encountered an error message and need to find and fix its source. + +**1. Share the error with Qwen Code** + +``` +I'm seeing an error when I run npm test +``` + +**2. Ask for fix recommendations** + +``` +suggest a few ways to fix the @ts-ignore in user.ts +``` + +**3. Apply the fix** + +``` +update user.tsto add the null check you suggested +``` + +> [!tip] +> +> - Tell Qwen Code the command to reproduce the issue and get a stack trace +> - Mention any steps to reproduce the error +> - Let Qwen Code know if the error is intermittent or consistent + +## Refactor code + +Suppose you need to update old code to use modern patterns and practices. + +**1. Identify legacy code for refactoring** + +``` +find deprecated API usage in our codebase +``` + +**2. Get refactoring recommendations** + +``` +suggest how to refactor utils.js to use modern JavaScript features +``` + +**3. Apply the changes safely** + +``` +refactor utils.js to use ES 2024 features while maintaining the same behavior +``` + +**4. Verify the refactoring** + +``` +run tests for the refactored code +``` + +> [!tip] +> +> - Ask Qwen Code to explain the benefits of the modern approach +> - Request that changes maintain backward compatibility when needed +> - Do refactoring in small, testable increments + +## Use specialized subagents + +Suppose you want to use specialized AI subagents to handle specific tasks more effectively. + +**1. View available subagents** + +``` +/agents +``` + +This shows all available subagents and lets you create new ones. + +**2. Use subagents automatically** + +Qwen Code automatically delegates appropriate tasks to specialized subagents: + +``` +review my recent code changes for security issues +``` + +``` +run all tests and fix any failures +``` + +**3. Explicitly request specific subagents** + +``` +use the code-reviewer subagent to check the auth module +``` + +``` +have the debugger subagent investigate why users can't log in +``` + +**4. Create custom subagents for your workflow** + +``` +/agents +``` + +Then select "create" and follow the prompts to define: + +- A unique identifier that describes the subagent's purpose (for example, `code-reviewer`, `api-designer`). +- When Qwen Code should use this agent +- Which tools it can access +- A system prompt describing the agent's role and behavior + +> [!tip] +> +> - Create project-specific subagents in `.qwen/agents/` for team sharing +> - Use descriptive `description` fields to enable automatic delegation +> - Limit tool access to what each subagent actually needs +> - Know more about [Sub Agents](./features/sub-agents) +> - Know more about [Approval Mode](./features/approval-mode) + +## Work with tests + +Suppose you need to add tests for uncovered code. + +**1. Identify untested code** + +``` +find functions in NotificationsService.swift that are not covered by tests +``` + +**2. Generate test scaffolding** + +``` +add tests for the notification service +``` + +**3. Add meaningful test cases** + +``` +add test cases for edge conditions in the notification service +``` + +**4. Run and verify tests** + +``` +run the new tests and fix any failures +``` + +Qwen Code can generate tests that follow your project's existing patterns and conventions. When asking for tests, be specific about what behavior you want to verify. Qwen Code examines your existing test files to match the style, frameworks, and assertion patterns already in use. + +For comprehensive coverage, ask Qwen Code to identify edge cases you might have missed. Qwen Code can analyze your code paths and suggest tests for error conditions, boundary values, and unexpected inputs that are easy to overlook. + +## Create pull requests + +Suppose you need to create a well-documented pull request for your changes. + +**1. Summarize your changes** + +``` +summarize the changes I've made to the authentication module +``` + +**2. Generate a pull request with Qwen Code** + +``` +create a pr +``` + +**3. Review and refine** + +``` +enhance the PR description with more context about the security improvements +``` + +**4. Add testing details** + +``` +add information about how these changes were tested +``` + +> [!tip] +> +> - Ask Qwen Code directly to make a PR for you +> - Review Qwen Code's generated PR before submitting +> - Ask Qwen Code to highlight potential risks or considerations + +## Handle documentation + +Suppose you need to add or update documentation for your code. + +**1. Identify undocumented code** + +``` +find functions without proper JSDoc comments in the auth module +``` + +**2. Generate documentation** + +``` +add JSDoc comments to the undocumented functions in auth.js +``` + +**3. Review and enhance** + +``` +improve the generated documentation with more context and examples +``` + +**4. Verify documentation** + +``` +check if the documentation follows our project standards +``` + +> [!tip] +> +> - Specify the documentation style you want (JSDoc, docstrings, etc.) +> - Ask for examples in the documentation +> - Request documentation for public APIs, interfaces, and complex logic + +## Reference files and directories + +Use `@` to quickly include files or directories without waiting for Qwen Code to read them. + +**1. Reference a single file** + +``` +Explain the logic in @src/utils/auth.js +``` + +This includes the full content of the file in the conversation. + +**2. Reference a directory** + +``` +What's the structure of @src/components? +``` + +This provides a directory listing with file information. + +**3. Reference MCP resources** + +``` +Show me the data from @github: repos/owner/repo/issues +``` + +This fetches data from connected MCP servers using the format @server: resource. See [MCP](./features/mcp) for details. + +> [!tip] +> +> - File paths can be relative or absolute +> - @ file references add `QWEN.md` in the file's directory and parent directories to context +> - Directory references show file listings, not contents +> - You can reference multiple files in a single message (for example, "`@file 1.js` and `@file 2.js`") + +## Resume previous conversations + +Suppose you've been working on a task with Qwen Code and need to continue where you left off in a later session. + +Qwen Code provides two options for resuming previous conversations: + +- `--continue` to automatically continue the most recent conversation +- `--resume` to display a conversation picker + +**1. Continue the most recent conversation** + +```bash +qwen --continue +``` + +This immediately resumes your most recent conversation without any prompts. + +**2. Continue in non-interactive mode** + +```bash +qwen --continue --p "Continue with my task" +``` + +Use `--print` with `--continue` to resume the most recent conversation in non-interactive mode, perfect for scripts or automation. + +**3. Show conversation picker** + +```bash +qwen --resume +``` + +This displays an interactive conversation selector with a clean list view showing: + +- Session summary (or initial prompt) +- Metadata: time elapsed, message count, and git branch + +Use arrow keys to navigate and press Enter to select a conversation. Press Esc to exit. + +> [!tip] +> +> - Conversation history is stored locally on your machine +> - Use `--continue` for quick access to your most recent conversation +> - Use `--resume` when you need to select a specific past conversation +> - When resuming, you'll see the entire conversation history before continuing +> - The resumed conversation starts with the same model and configuration as the original +> +> **How it works**: +> +> 1. **Conversation Storage**: All conversations are automatically saved locally with their full message history +> 2. **Message Deserialization**: When resuming, the entire message history is restored to maintain context +> 3. **Tool State**: Tool usage and results from the previous conversation are preserved +> 4. **Context Restoration**: The conversation resumes with all previous context intact +> +> **Examples**: +> +> ```bash +> # Continue most recent conversation +> qwen --continue +> +> # Continue most recent conversation with a specific prompt +> qwen --continue --p "Show me our progress" +> +> # Show conversation picker +> qwen --resume +> +> # Continue most recent conversation in non-interactive mode +> qwen --continue --p "Run the tests again" +> ``` + +## Run parallel Qwen Code sessions with Git worktrees + +Suppose you need to work on multiple tasks simultaneously with complete code isolation between Qwen Code instances. + +**1. Understand Git worktrees** + +Git worktrees allow you to check out multiple branches from the same repository into separate directories. Each worktree has its own working directory with isolated files, while sharing the same Git history. Learn more in the [official Git worktree documentation](https://git-scm.com/docs/git-worktree). + +**2. Create a new worktree** + +```bash +# Create a new worktree with a new branch +git worktree add ../project-feature-a -b feature-a + +# Or create a worktree with an existing branch +git worktree add ../project-bugfix bugfix-123 +``` + +This creates a new directory with a separate working copy of your repository. + +**3. Run Qwen Code in each worktree** + +```bash +# Navigate to your worktree +cd ../project-feature-a + +# Run Qwen Code in this isolated environment +qwen +``` + +**4. Run Qwen Code in another worktree** + +```bash +cd ../project-bugfix +qwen +``` + +**5. Manage your worktrees** + +```bash +# List all worktrees +git worktree list + +# Remove a worktree when done +git worktree remove ../project-feature-a +``` + +> [!tip] +> +> - Each worktree has its own independent file state, making it perfect for parallel Qwen Code sessions +> - Changes made in one worktree won't affect others, preventing Qwen Code instances from interfering with each other +> - All worktrees share the same Git history and remote connections +> - For long-running tasks, you can have Qwen Code working in one worktree while you continue development in another +> - Use descriptive directory names to easily identify which task each worktree is for +> - Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include: +> - JavaScript projects: Running dependency installation (`npm install`, `yarn`) +> - Python projects: Setting up virtual environments or installing with package managers +> - Other languages: Following your project's standard setup process + +## Use Qwen Code as a unix-style utility + +### Add Qwen Code to your verification process + +Suppose you want to use Qwen Code as a linter or code reviewer. + +**Add Qwen Code to your build script:** + +```json +// package.json +{ + ... + "scripts": { + ... + "lint:Qwen Code": "qwen -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'" + } +} +``` + +> [!tip] +> +> - Use Qwen Code for automated code review in your CI/CD pipeline +> - Customize the prompt to check for specific issues relevant to your project +> - Consider creating multiple scripts for different types of verification + +### Pipe in, pipe out + +Suppose you want to pipe data into Qwen Code, and get back data in a structured format. + +**Pipe data through Qwen Code:** + +```bash +cat build-error.txt | qwen -p 'concisely explain the root cause of this build error' > output.txt +``` + +> [!tip] +> +> - Use pipes to integrate Qwen-Code into existing shell scripts +> - Combine with other Unix tools for powerful workflows +> - Consider using --output-format for structured output + +### Control output format + +Suppose you need Qwen Code's output in a specific format, especially when integrating Qwen Code into scripts or other tools. + +**1. Use text format (default)** + +```bash +cat data.txt | qwen -p 'summarize this data' --output-format text > summary.txt +``` + +This outputs just Qwen Code's plain text response (default behavior). + +**2. Use JSON format** + +```bash +cat code.py | qwen -p 'analyze this code for bugs' --output-format json > analysis.json +``` + +This outputs a JSON array of messages with metadata including cost and duration. + +**3. Use streaming JSON format** + +```bash +cat log.txt | qwen -p 'parse this log file for errors' --output-format stream-json +``` + +This outputs a series of JSON objects in real-time as Qwen Code processes the request. Each message is a valid JSON object, but the entire output is not valid JSON if concatenated. + +> [!tip] +> +> - Use `--output-format text` for simple integrations where you just need Qwen Code's response +> - Use `--output-format json` when you need the full conversation log +> - Use `--output-format stream-json` for real-time output of each conversation turn + +## Ask Qwen Code about its capabilities + +Qwen Code has built-in access to its documentation and can answer questions about its own features and limitations. + +### Example questions + +``` +can Qwen Code create pull requests? +``` + +``` +how does Qwen Code handle permissions? +``` + +``` +what slash commands are available? +``` + +``` +how do I use MCP with Qwen Code? +``` + +``` +how do I configure Qwen Code for Amazon Bedrock? +``` + +``` +what are the limitations of Qwen Code? +``` + +> [!note] +> +> Qwen Code provides documentation-based answers to these questions. For executable examples and hands-on demonstrations, refer to the specific workflow sections above. + +> [!tip] +> +> - Qwen Code always has access to the latest Qwen Code documentation, regardless of the version you're using +> - Ask specific questions to get detailed answers +> - Qwen Code can explain complex features like MCP integration, enterprise configurations, and advanced workflows diff --git a/docs/users/configuration/_meta.ts b/docs/users/configuration/_meta.ts new file mode 100644 index 000000000..8899eb91f --- /dev/null +++ b/docs/users/configuration/_meta.ts @@ -0,0 +1,10 @@ +export default { + settings: 'Settings', + auth: 'Authentication', + memory: { + display: 'hidden', + }, + 'qwen-ignore': 'Ignoring Files', + 'trusted-folders': 'Trusted Folders', + themes: 'Themes', +}; diff --git a/docs/users/configuration/auth.md b/docs/users/configuration/auth.md new file mode 100644 index 000000000..82bc66b26 --- /dev/null +++ b/docs/users/configuration/auth.md @@ -0,0 +1,119 @@ +# Authentication + +Qwen Code supports two authentication methods. Pick the one that matches how you want to run the CLI: + +- **Qwen OAuth (recommended)**: sign in with your `qwen.ai` account in a browser. +- **OpenAI-compatible API**: use an API key (OpenAI or any OpenAI-compatible provider / endpoint). + +## Option 1: Qwen OAuth (recommended & free) 👍 + +Use this if you want the simplest setup and you’re using Qwen models. + +- **How it works**: on first start, Qwen Code opens a browser login page. After you finish, credentials are cached locally so you usually won’t need to log in again. +- **Requirements**: a `qwen.ai` account + internet access (at least for the first login). +- **Benefits**: no API key management, automatic credential refresh. +- **Cost & quota**: free, with a quota of **60 requests/minute** and **2,000 requests/day**. + +Start the CLI and follow the browser flow: + +```bash +qwen +``` + +## Option 2: OpenAI-compatible API (API key) + +Use this if you want to use OpenAI models or any provider that exposes an OpenAI-compatible API (e.g. OpenAI, Azure OpenAI, OpenRouter, ModelScope, Alibaba Cloud Bailian, or a self-hosted compatible endpoint). + +### Quick start (interactive, recommended for local use) + +When you choose the OpenAI-compatible option in the CLI, it will prompt you for: + +- **API key** +- **Base URL** (default: `https://api.openai.com/v1`) +- **Model** (default: `gpt-4o`) + +> **Note:** the CLI may display the key in plain text for verification. Make sure your terminal is not being recorded or shared. + +### Configure via command-line arguments + +```bash +# API key only +qwen-code --openai-api-key "your-api-key-here" + +# Custom base URL (OpenAI-compatible endpoint) +qwen-code --openai-api-key "your-api-key-here" --openai-base-url "https://your-endpoint.com/v1" + +# Custom model +qwen-code --openai-api-key "your-api-key-here" --model "gpt-4o-mini" +``` + +### Configure via environment variables + +You can set these in your shell profile, CI, or an `.env` file: + +```bash +export OPENAI_API_KEY="your-api-key-here" +export OPENAI_BASE_URL="https://api.openai.com/v1" # optional +export OPENAI_MODEL="gpt-4o" # optional +``` + +#### Persisting env vars with `.env` / `.qwen/.env` + +Qwen Code will auto-load environment variables from the **first** `.env` file it finds (variables are **not merged** across multiple files). + +Search order: + +1. From the **current directory**, walking upward toward `/`: + 1. `.qwen/.env` + 2. `.env` +2. If nothing is found, it falls back to your **home directory**: + - `~/.qwen/.env` + - `~/.env` + +`.qwen/.env` is recommended to keep Qwen Code variables isolated from other tools. Some variables (like `DEBUG` and `DEBUG_MODE`) are excluded from project `.env` files to avoid interfering with qwen-code behavior. + +Examples: + +```bash +# Project-specific settings (recommended) +mkdir -p .qwen +cat >> .qwen/.env <<'EOF' +OPENAI_API_KEY="your-api-key" +OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1" +OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct" +EOF +``` + +```bash +# User-wide settings (available everywhere) +mkdir -p ~/.qwen +cat >> ~/.qwen/.env <<'EOF' +OPENAI_API_KEY="your-api-key" +OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" +OPENAI_MODEL="qwen3-coder-plus" +EOF +``` + +## Switch authentication method (without restarting) + +In the Qwen Code UI, run: + +```bash +/auth +``` + +## Non-interactive / headless environments (CI, SSH, containers) + +In a non-interactive terminal you typically **cannot** complete the OAuth browser login flow. +Use the OpenAI-compatible API method via environment variables: + +- Set at least `OPENAI_API_KEY`. +- Optionally set `OPENAI_BASE_URL` and `OPENAI_MODEL`. + +If none of these are set in a non-interactive session, Qwen Code will exit with an error. + +## Security notes + +- Don’t commit API keys to version control. +- Prefer `.qwen/.env` for project-local secrets (and keep it out of git). +- Treat your terminal output as sensitive if it prints credentials for verification. diff --git a/docs/users/configuration/memory.md b/docs/users/configuration/memory.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/cli/qwen-ignore.md b/docs/users/configuration/qwen-ignore.md similarity index 73% rename from docs/cli/qwen-ignore.md rename to docs/users/configuration/qwen-ignore.md index 1b8709108..9b992bda2 100644 --- a/docs/cli/qwen-ignore.md +++ b/docs/users/configuration/qwen-ignore.md @@ -6,7 +6,7 @@ Qwen Code includes the ability to automatically ignore files, similar to `.gitig ## How it works -When you add a path to your `.qwenignore` file, tools that respect this file will exclude matching files and directories from their operations. For example, when you use the [`read_many_files`](./tools/multi-file.md) command, any paths in your `.qwenignore` file will be automatically excluded. +When you add a path to your `.qwenignore` file, tools that respect this file will exclude matching files and directories from their operations. For example, when you use the [`read_many_files`](../../developers/tools/multi-file) command, any paths in your `.qwenignore` file will be automatically excluded. For the most part, `.qwenignore` follows the conventions of `.gitignore` files: @@ -20,14 +20,10 @@ You can update your `.qwenignore` file at any time. To apply the changes, you mu ## How to use `.qwenignore` -To enable `.qwenignore`: - -1. Create a file named `.qwenignore` in the root of your project directory. - -To add a file or directory to `.qwenignore`: - -1. Open your `.qwenignore` file. -2. Add the path or file you want to ignore, for example: `/archive/` or `apikeys.txt`. +| Step | Description | +| ---------------------- | -------------------------------------------------------------------------------------- | +| **Enable .qwenignore** | Create a file named `.qwenignore` in your project root directory | +| **Add ignore rules** | Open `.qwenignore` file and add paths to ignore, example: `/archive/` or `apikeys.txt` | ### `.qwenignore` examples diff --git a/docs/users/configuration/settings.md b/docs/users/configuration/settings.md new file mode 100644 index 000000000..3e87985b8 --- /dev/null +++ b/docs/users/configuration/settings.md @@ -0,0 +1,510 @@ +# Qwen Code Configuration + +> [!tip] +> +> **Authentication / API keys:** Authentication (Qwen OAuth vs OpenAI-compatible API) and auth-related environment variables (like `OPENAI_API_KEY`) are documented in **[Authentication](../configuration/auth)**. + +> [!note] +> +> **Note on New Configuration Format**: The format of the `settings.json` file has been updated to a new, more organized structure. The old format will be migrated automatically. +> Qwen Code offers several ways to configure its behavior, including environment variables, command-line arguments, and settings files. This document outlines the different configuration methods and available settings. + +## Configuration layers + +Configuration is applied in the following order of precedence (lower numbers are overridden by higher numbers): + +| Level | Configuration Source | Description | +| ----- | ---------------------- | ------------------------------------------------------------------------------- | +| 1 | Default values | Hardcoded defaults within the application | +| 2 | System defaults file | System-wide default settings that can be overridden by other settings files | +| 3 | User settings file | Global settings for the current user | +| 4 | Project settings file | Project-specific settings | +| 5 | System settings file | System-wide settings that override all other settings files | +| 6 | Environment variables | System-wide or session-specific variables, potentially loaded from `.env` files | +| 7 | Command-line arguments | Values passed when launching the CLI | + +## Settings files + +Qwen Code uses JSON settings files for persistent configuration. There are four locations for these files: + +| File Type | Location | Scope | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| System defaults file | Linux: `/etc/qwen-code/system-defaults.json`
Windows: `C:\ProgramData\qwen-code\system-defaults.json`
macOS: `/Library/Application Support/QwenCode/system-defaults.json`
The path can be overridden using the `QWEN_CODE_SYSTEM_DEFAULTS_PATH` environment variable. | Provides a base layer of system-wide default settings. These settings have the lowest precedence and are intended to be overridden by user, project, or system override settings. | +| User settings file | `~/.qwen/settings.json` (where `~` is your home directory). | Applies to all Qwen Code sessions for the current user. | +| Project settings file | `.qwen/settings.json` within your project's root directory. | Applies only when running Qwen Code from that specific project. Project settings override user settings. | +| System settings file | Linux： `/etc/qwen-code/settings.json`
Windows: `C:\ProgramData\qwen-code\settings.json`
macOS: `/Library/Application Support/QwenCode/settings.json`
The path can be overridden using the `QWEN_CODE_SYSTEM_SETTINGS_PATH` environment variable. | Applies to all Qwen Code sessions on the system, for all users. System settings override user and project settings. May be useful for system administrators at enterprises to have controls over users' Qwen Code setups. | + +> [!note] +> +> **Note on environment variables in settings:** String values within your `settings.json` files can reference environment variables using either `$VAR_NAME` or `${VAR_NAME}` syntax. These variables will be automatically resolved when the settings are loaded. For example, if you have an environment variable `MY_API_TOKEN`, you could use it in `settings.json` like this: `"apiKey": "$MY_API_TOKEN"`. + +### The `.qwen` directory in your project + +In addition to a project settings file, a project's `.qwen` directory can contain other project-specific files related to Qwen Code's operation, such as: + +- [Custom sandbox profiles](../features/sandbox) (e.g. `.qwen/sandbox-macos-custom.sb`, `.qwen/sandbox.Dockerfile`). +- [Agent Skills](../features/skills) (experimental) under `.qwen/skills/` (each Skill is a directory containing a `SKILL.md`). + +### Available settings in `settings.json` + +Settings are organized into categories. All settings should be placed within their corresponding top-level category object in your `settings.json` file. + +#### general + +| Setting | Type | Description | Default | +| ------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- | ----------- | +| `general.preferredEditor` | string | The preferred editor to open files in. | `undefined` | +| `general.vimMode` | boolean | Enable Vim keybindings. | `false` | +| `general.disableAutoUpdate` | boolean | Disable automatic updates. | `false` | +| `general.disableUpdateNag` | boolean | Disable update notification prompts. | `false` | +| `general.gitCoAuthor` | boolean | Automatically add a Co-authored-by trailer to git commit messages when commits are made through Qwen Code. | `true` | +| `general.checkpointing.enabled` | boolean | Enable session checkpointing for recovery. | `false` | + +#### output + +| Setting | Type | Description | Default | Possible Values | +| --------------- | ------ | ----------------------------- | -------- | ------------------ | +| `output.format` | string | The format of the CLI output. | `"text"` | `"text"`, `"json"` | + +#### ui + +| Setting | Type | Description | Default | +| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `ui.theme` | string | The color theme for the UI. See [Themes](../configuration/themes) for available options. | `undefined` | +| `ui.customThemes` | object | Custom theme definitions. | `{}` | +| `ui.hideWindowTitle` | boolean | Hide the window title bar. | `false` | +| `ui.hideTips` | boolean | Hide helpful tips in the UI. | `false` | +| `ui.hideBanner` | boolean | Hide the application banner. | `false` | +| `ui.hideFooter` | boolean | Hide the footer from the UI. | `false` | +| `ui.showMemoryUsage` | boolean | Display memory usage information in the UI. | `false` | +| `ui.showLineNumbers` | boolean | Show line numbers in code blocks in the CLI output. | `true` | +| `ui.showCitations` | boolean | Show citations for generated text in the chat. | `true` | +| `enableWelcomeBack` | boolean | Show welcome back dialog when returning to a project with conversation history. When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. This feature integrates with the `/summary` command and quit confirmation dialog. | `true` | +| `ui.accessibility.disableLoadingPhrases` | boolean | Disable loading phrases for accessibility. | `false` | +| `ui.accessibility.screenReader` | boolean | Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers. | `false` | +| `ui.customWittyPhrases` | array of strings | A list of custom phrases to display during loading states. When provided, the CLI will cycle through these phrases instead of the default ones. | `[]` | + +#### ide + +| Setting | Type | Description | Default | +| ------------------ | ------- | ---------------------------------------------------- | ------- | +| `ide.enabled` | boolean | Enable IDE integration mode. | `false` | +| `ide.hasSeenNudge` | boolean | Whether the user has seen the IDE integration nudge. | `false` | + +#### privacy + +| Setting | Type | Description | Default | +| -------------------------------- | ------- | -------------------------------------- | ------- | +| `privacy.usageStatisticsEnabled` | boolean | Enable collection of usage statistics. | `true` | + +#### model + +| Setting | Type | Description | Default | +| -------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `model.name` | string | The Qwen model to use for conversations. | `undefined` | +| `model.maxSessionTurns` | number | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited. | `-1` | +| `model.summarizeToolOutput` | object | Enables or disables the summarization of tool output. You can specify the token budget for the summarization using the `tokenBudget` setting. Note: Currently only the `run_shell_command` tool is supported. For example `{"run_shell_command": {"tokenBudget": 2000}}` | `undefined` | +| `model.generationConfig` | object | Advanced overrides passed to the underlying content generator. Supports request controls such as `timeout`, `maxRetries`, and `disableCacheControl`, along with fine-tuning knobs under `samplingParams` (for example `temperature`, `top_p`, `max_tokens`). Leave unset to rely on provider defaults. | `undefined` | +| `model.chatCompression.contextPercentageThreshold` | number | Sets the threshold for chat history compression as a percentage of the model's total token limit. This is a value between 0 and 1 that applies to both automatic compression and the manual `/compress` command. For example, a value of `0.6` will trigger compression when the chat history exceeds 60% of the token limit. Use `0` to disable compression entirely. | `0.7` | +| `model.skipNextSpeakerCheck` | boolean | Skip the next speaker check. | `false` | +| `model.skipLoopDetection` | boolean | Disables loop detection checks. Loop detection prevents infinite loops in AI responses but can generate false positives that interrupt legitimate workflows. Enable this option if you experience frequent false positive loop detection interruptions. | `false` | +| `model.skipStartupContext` | boolean | Skips sending the startup workspace context (environment summary and acknowledgement) at the beginning of each session. Enable this if you prefer to provide context manually or want to save tokens on startup. | `false` | +| `model.enableOpenAILogging` | boolean | Enables logging of OpenAI API calls for debugging and analysis. When enabled, API requests and responses are logged to JSON files. | `false` | +| `model.openAILoggingDir` | string | Custom directory path for OpenAI API logs. If not specified, defaults to `logs/openai` in the current working directory. Supports absolute paths, relative paths (resolved from current working directory), and `~` expansion (home directory). | `undefined` | + +**Example model.generationConfig:** + +``` +{ + "model": { + "generationConfig": { + "timeout": 60000, + "disableCacheControl": false, + "samplingParams": { + "temperature": 0.2, + "top_p": 0.8, + "max_tokens": 1024 + } + } + } +} +``` + +**model.openAILoggingDir examples:** + +- `"~/qwen-logs"` - Logs to `~/qwen-logs` directory +- `"./custom-logs"` - Logs to `./custom-logs` relative to current directory +- `"/tmp/openai-logs"` - Logs to absolute path `/tmp/openai-logs` + +#### context + +| Setting | Type | Description | Default | +| ------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `context.fileName` | string or array of strings | The name of the context file(s). | `undefined` | +| `context.importFormat` | string | The format to use when importing memory. | `undefined` | +| `context.discoveryMaxDirs` | number | Maximum number of directories to search for memory. | `200` | +| `context.includeDirectories` | array | Additional directories to include in the workspace context. Specifies an array of additional absolute or relative paths to include in the workspace context. Missing directories will be skipped with a warning by default. Paths can use `~` to refer to the user's home directory. This setting can be combined with the `--include-directories` command-line flag. | `[]` | +| `context.loadFromIncludeDirectories` | boolean | Controls the behavior of the `/memory refresh` command. If set to `true`, `QWEN.md` files should be loaded from all directories that are added. If set to `false`, `QWEN.md` should only be loaded from the current directory. | `false` | +| `context.fileFiltering.respectGitIgnore` | boolean | Respect .gitignore files when searching. | `true` | +| `context.fileFiltering.respectQwenIgnore` | boolean | Respect .qwenignore files when searching. | `true` | +| `context.fileFiltering.enableRecursiveFileSearch` | boolean | Whether to enable searching recursively for filenames under the current tree when completing `@` prefixes in the prompt. | `true` | +| `context.fileFiltering.disableFuzzySearch` | boolean | When `true`, disables the fuzzy search capabilities when searching for files, which can improve performance on projects with a large number of files. | `false` | + +#### Troubleshooting File Search Performance + +If you are experiencing performance issues with file searching (e.g., with `@` completions), especially in projects with a very large number of files, here are a few things you can try in order of recommendation: + +1. **Use `.qwenignore`:** Create a `.qwenignore` file in your project root to exclude directories that contain a large number of files that you don't need to reference (e.g., build artifacts, logs, `node_modules`). Reducing the total number of files crawled is the most effective way to improve performance. +2. **Disable Fuzzy Search:** If ignoring files is not enough, you can disable fuzzy search by setting `disableFuzzySearch` to `true` in your `settings.json` file. This will use a simpler, non-fuzzy matching algorithm, which can be faster. +3. **Disable Recursive File Search:** As a last resort, you can disable recursive file search entirely by setting `enableRecursiveFileSearch` to `false`. This will be the fastest option as it avoids a recursive crawl of your project. However, it means you will need to type the full path to files when using `@` completions. + +#### tools + +| Setting | Type | Description | Default | Notes | +| ------------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tools.sandbox` | boolean or string | Sandbox execution environment (can be a boolean or a path string). | `undefined` | | +| `tools.shell.enableInteractiveShell` | boolean | Use `node-pty` for an interactive shell experience. Fallback to `child_process` still applies. | `false` | | +| `tools.core` | array of strings | This can be used to restrict the set of built-in tools with an allowlist. You can also specify command-specific restrictions for tools that support it, like the `run_shell_command` tool. For example, `"tools.core": ["run_shell_command(ls -l)"]` will only allow the `ls -l` command to be executed. | `undefined` | | +| `tools.exclude` | array of strings | Tool names to exclude from discovery. You can also specify command-specific restrictions for tools that support it, like the `run_shell_command` tool. For example, `"tools.exclude": ["run_shell_command(rm -rf)"]` will block the `rm -rf` command. **Security Note:** Command-specific restrictions in `tools.exclude` for `run_shell_command` are based on simple string matching and can be easily bypassed. This feature is **not a security mechanism** and should not be relied upon to safely execute untrusted code. It is recommended to use `tools.core` to explicitly select commands that can be executed. | `undefined` | | +| `tools.allowed` | array of strings | A list of tool names that will bypass the confirmation dialog. This is useful for tools that you trust and use frequently. For example, `["run_shell_command(git)", "run_shell_command(npm test)"]` will skip the confirmation dialog to run any `git` and `npm test` commands. | `undefined` | | +| `tools.approvalMode` | string | Sets the default approval mode for tool usage. | `default` | Possible values: `plan` (analyze only, do not modify files or execute commands), `default` (require approval before file edits or shell commands run), `auto-edit` (automatically approve file edits), `yolo` (automatically approve all tool calls) | +| `tools.discoveryCommand` | string | Command to run for tool discovery. | `undefined` | | +| `tools.callCommand` | string | Defines a custom shell command for calling a specific tool that was discovered using `tools.discoveryCommand`. The shell command must meet the following criteria: It must take function `name` (exactly as in [function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) as first command line argument. It must read function arguments as JSON on `stdin`, analogous to [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). It must return function output as JSON on `stdout`, analogous to [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). | `undefined` | | +| `tools.useRipgrep` | boolean | Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance. | `true` | | +| `tools.useBuiltinRipgrep` | boolean | Use the bundled ripgrep binary. When set to `false`, the system-level `rg` command will be used instead. This setting is only effective when `tools.useRipgrep` is `true`. | `true` | | +| `tools.enableToolOutputTruncation` | boolean | Enable truncation of large tool outputs. | `true` | Requires restart: Yes | +| `tools.truncateToolOutputThreshold` | number | Truncate tool output if it is larger than this many characters. Applies to Shell, Grep, Glob, ReadFile and ReadManyFiles tools. | `25000` | Requires restart: Yes | +| `tools.truncateToolOutputLines` | number | Maximum lines or entries kept when truncating tool output. Applies to Shell, Grep, Glob, ReadFile and ReadManyFiles tools. | `1000` | Requires restart: Yes | +| `tools.autoAccept` | boolean | Controls whether the CLI automatically accepts and executes tool calls that are considered safe (e.g., read-only operations) without explicit user confirmation. If set to `true`, the CLI will bypass the confirmation prompt for tools deemed safe. | `false` | | + +#### mcp + +| Setting | Type | Description | Default | +| ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `mcp.serverCommand` | string | Command to start an MCP server. | `undefined` | +| `mcp.allowed` | array of strings | An allowlist of MCP servers to allow. Allows you to specify a list of MCP server names that should be made available to the model. This can be used to restrict the set of MCP servers to connect to. Note that this will be ignored if `--allowed-mcp-server-names` is set. | `undefined` | +| `mcp.excluded` | array of strings | A denylist of MCP servers to exclude. A server listed in both `mcp.excluded` and `mcp.allowed` is excluded. Note that this will be ignored if `--allowed-mcp-server-names` is set. | `undefined` | + +> [!note] +> +> **Security Note for MCP servers:** These settings use simple string matching on MCP server names, which can be modified. If you're a system administrator looking to prevent users from bypassing this, consider configuring the `mcpServers` at the system settings level such that the user will not be able to configure any MCP servers of their own. This should not be used as an airtight security mechanism. + +#### security + +| Setting | Type | Description | Default | +| ------------------------------ | ------- | ------------------------------------------------- | ----------- | +| `security.folderTrust.enabled` | boolean | Setting to track whether Folder trust is enabled. | `false` | +| `security.auth.selectedType` | string | The currently selected authentication type. | `undefined` | +| `security.auth.enforcedType` | string | The required auth type (useful for enterprises). | `undefined` | +| `security.auth.useExternal` | boolean | Whether to use an external authentication flow. | `undefined` | + +#### advanced + +| Setting | Type | Description | Default | +| ------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | +| `advanced.autoConfigureMemory` | boolean | Automatically configure Node.js memory limits. | `false` | +| `advanced.dnsResolutionOrder` | string | The DNS resolution order. | `undefined` | +| `advanced.excludedEnvVars` | array of strings | Environment variables to exclude from project context. Specifies environment variables that should be excluded from being loaded from project `.env` files. This prevents project-specific environment variables (like `DEBUG=true`) from interfering with the CLI behavior. Variables from `.qwen/.env` files are never excluded. | `["DEBUG","DEBUG_MODE"]` | +| `advanced.bugCommand` | object | Configuration for the bug report command. Overrides the default URL for the `/bug` command. Properties: `urlTemplate` (string): A URL that can contain `{title}` and `{info}` placeholders. Example: `"bugCommand": { "urlTemplate": "https://bug.example.com/new?title={title}&info={info}" }` | `undefined` | +| `advanced.tavilyApiKey` | string | API key for Tavily web search service. Used to enable the `web_search` tool functionality. | `undefined` | + +> [!note] +> +> **Note about advanced.tavilyApiKey:** This is a legacy configuration format. For Qwen OAuth users, DashScope provider is automatically available without any configuration. For other authentication types, configure Tavily or Google providers using the new `webSearch` configuration format. + +#### mcpServers + +Configures connections to one or more Model-Context Protocol (MCP) servers for discovering and using custom tools. Qwen Code attempts to connect to each configured MCP server to discover available tools. If multiple MCP servers expose a tool with the same name, the tool names will be prefixed with the server alias you defined in the configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts. Note that the system might strip certain schema properties from MCP tool definitions for compatibility. At least one of `command`, `url`, or `httpUrl` must be provided. If multiple are specified, the order of precedence is `httpUrl`, then `url`, then `command`. + +| Property | Type | Description | Optional | +| --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| `mcpServers.
See more about [Approval Mode](../features/approval-mode). | +| `--allowed-tools` | | A comma-separated list of tool names that will bypass the confirmation dialog. | Tool names | Example: `qwen --allowed-tools "Shell(git status)"` | +| `--telemetry` | | Enables [telemetry](/developers/development/telemetry). | | | +| `--telemetry-target` | | Sets the telemetry target. | | See [telemetry](/developers/development/telemetry) for more information. | +| `--telemetry-otlp-endpoint` | | Sets the OTLP endpoint for telemetry. | | See [telemetry](../../developers/development/telemetry) for more information. | +| `--telemetry-otlp-protocol` | | Sets the OTLP protocol for telemetry (`grpc` or `http`). | | Defaults to `grpc`. See [telemetry](../../developers/development/telemetry) for more information. | +| `--telemetry-log-prompts` | | Enables logging of prompts for telemetry. | | See [telemetry](../../developers/development/telemetry) for more information. | +| `--checkpointing` | | Enables [checkpointing](../features/checkpointing). | | | +| `--experimental-acp` | | Enables ACP mode (Agent Control Protocol). Useful for IDE/editor integrations like [Zed](../integration-zed). | | Experimental. | +| `--experimental-skills` | | Enables experimental [Agent Skills](../features/skills) (registers the `skill` tool and loads Skills from `.qwen/skills/` and `~/.qwen/skills/`). | | Experimental. | +| `--extensions` | `-e` | Specifies a list of extensions to use for the session. | Extension names | If not provided, all available extensions are used. Use the special term `qwen -e none` to disable all extensions. Example: `qwen -e my-extension -e my-other-extension` | +| `--list-extensions` | `-l` | Lists all available extensions and exits. | | | +| `--proxy` | | Sets the proxy for the CLI. | Proxy URL | Example: `--proxy http://localhost:7890`. | +| `--include-directories` | | Includes additional directories in the workspace for multi-directory support. | Directory paths | Can be specified multiple times or as comma-separated values. 5 directories can be added at maximum. Example: `--include-directories /path/to/project1,/path/to/project2` or `--include-directories /path/to/project1 --include-directories /path/to/project2` | +| `--screen-reader` | | Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers. | | | +| `--version` | | Displays the version of the CLI. | | | +| `--openai-logging` | | Enables logging of OpenAI API calls for debugging and analysis. | | This flag overrides the `enableOpenAILogging` setting in `settings.json`. | +| `--openai-logging-dir` | | Sets a custom directory path for OpenAI API logs. | Directory path | This flag overrides the `openAILoggingDir` setting in `settings.json`. Supports absolute paths, relative paths, and `~` expansion. Example: `qwen --openai-logging-dir "~/qwen-logs" --openai-logging` | +| `--tavily-api-key` | | Sets the Tavily API key for web search functionality for this session. | API key | Example: `qwen --tavily-api-key tvly-your-api-key-here` | + +## Context Files (Hierarchical Instructional Context) + +While not strictly configuration for the CLI's _behavior_, context files (defaulting to `QWEN.md` but configurable via the `context.fileName` setting) are crucial for configuring the _instructional context_ (also referred to as "memory"). This powerful feature allows you to give project-specific instructions, coding style guides, or any relevant background information to the AI, making its responses more tailored and accurate to your needs. The CLI includes UI elements, such as an indicator in the footer showing the number of loaded context files, to keep you informed about the active context. + +- **Purpose:** These Markdown files contain instructions, guidelines, or context that you want the Qwen model to be aware of during your interactions. The system is designed to manage this instructional context hierarchically. + +### Example Context File Content (e.g. `QWEN.md`) + +Here's a conceptual example of what a context file at the root of a TypeScript project might contain: + +``` +# Project: My Awesome TypeScript Library + +## General Instructions: +- When generating new TypeScript code, please follow the existing coding style. +- Ensure all new functions and classes have JSDoc comments. +- Prefer functional programming paradigms where appropriate. +- All code should be compatible with TypeScript 5.0 and Node.js 20+. + +## Coding Style: +- Use 2 spaces for indentation. +- Interface names should be prefixed with `I` (e.g., `IUserService`). +- Private class members should be prefixed with an underscore (`_`). +- Always use strict equality (`===` and `!==`). + +## Specific Component: `src/api/client.ts` +- This file handles all outbound API requests. +- When adding new API call functions, ensure they include robust error handling and logging. +- Use the existing `fetchWithRetry` utility for all GET requests. + +## Regarding Dependencies: +- Avoid introducing new external dependencies unless absolutely necessary. +- If a new dependency is required, please state the reason. +``` + +This example demonstrates how you can provide general project context, specific coding conventions, and even notes about particular files or components. The more relevant and precise your context files are, the better the AI can assist you. Project-specific context files are highly encouraged to establish conventions and context. + +- **Hierarchical Loading and Precedence:** The CLI implements a sophisticated hierarchical memory system by loading context files (e.g., `QWEN.md`) from several locations. Content from files lower in this list (more specific) typically overrides or supplements content from files higher up (more general). The exact concatenation order and final context can be inspected using the `/memory show` command. The typical loading order is: + 1. **Global Context File:** + - Location: `~/.qwen/
+
### Using Your Custom Theme
- Select your custom theme using the `/theme` command in Qwen Code. Your custom theme will appear in the theme selection dialog.
- Or, set it as the default by adding `"theme": "MyCustomTheme"` to the `ui` object in your `settings.json`.
-- Custom themes can be set at the user, project, or system level, and follow the same [configuration precedence](./configuration.md) as other settings.
+- Custom themes can be set at the user, project, or system level, and follow the same [configuration precedence](../configuration/settings) as other settings.
----
+## Themes Preview
-## Dark Themes
-
-### ANSI
-
-
-
-### Atom OneDark
-
-
-
-### Ayu
-
-
-
-### Default
-
-
-
-### Dracula
-
-
-
-### GitHub
-
-
-
-## Light Themes
-
-### ANSI Light
-
-
-
-### Ayu Light
-
-
-
-### Default Light
-
-
-
-### GitHub Light
-
-
-
-### Google Code
-
-
-
-### Xcode
-
-
+| Dark Theme | Preview | Light Theme | Preview |
+| :----------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| ANSI | 
| ANSI Light | 
|
+| Atom OneDark | 
| Ayu Light | 
|
+| Ayu | 
| Default Light | 
|
+| Default | 
| GitHub Light | 
|
+| Dracula | 
| Google Code | 
|
+| GitHub | 
| Xcode | 
|
diff --git a/docs/cli/trusted-folders.md b/docs/users/configuration/trusted-folders.md
similarity index 90%
rename from docs/cli/trusted-folders.md
rename to docs/users/configuration/trusted-folders.md
index 6fe3486b6..7aa16d842 100644
--- a/docs/cli/trusted-folders.md
+++ b/docs/users/configuration/trusted-folders.md
@@ -22,8 +22,8 @@ Add the following to your user `settings.json` file:
Once the feature is enabled, the first time you run the Qwen Code from a folder, a dialog will automatically appear, prompting you to make a choice:
-- **Trust folder**: Grants full trust to the current folder (e.g., `my-project`).
-- **Trust parent folder**: Grants trust to the parent directory (e.g., `safe-projects`), which automatically trusts all of its subdirectories as well. This is useful if you keep all your safe projects in one place.
+- **Trust folder**: Grants full trust to the current folder (e.g. `my-project`).
+- **Trust parent folder**: Grants trust to the parent directory (e.g. `safe-projects`), which automatically trusts all of its subdirectories as well. This is useful if you keep all your safe projects in one place.
- **Don't trust**: Marks the folder as untrusted. The CLI will operate in a restricted "safe mode."
Your choice is saved in a central file (`~/.qwen/trustedFolders.json`), so you will only be asked once per folder.
@@ -56,6 +56,6 @@ If you need to change a decision or see all your settings, you have a couple of
For advanced users, it's helpful to know the exact order of operations for how trust is determined:
-1. **IDE Trust Signal**: If you are using the [IDE Integration](./ide-integration.md), the CLI first asks the IDE if the workspace is trusted. The IDE's response takes highest priority.
+1. **IDE Trust Signal**: If you are using the [IDE Integration](../ide-integration/ide-integration), the CLI first asks the IDE if the workspace is trusted. The IDE's response takes highest priority.
2. **Local Trust File**: If the IDE is not connected, the CLI checks the central `~/.qwen/trustedFolders.json` file.
diff --git a/docs/users/features/_meta.ts b/docs/users/features/_meta.ts
new file mode 100644
index 000000000..bf182b6b7
--- /dev/null
+++ b/docs/users/features/_meta.ts
@@ -0,0 +1,13 @@
+export default {
+ commands: 'Commands',
+ 'sub-agents': 'SubAgents',
+ skills: 'Skills (Experimental)',
+ headless: 'Headless Mode',
+ checkpointing: {
+ display: 'hidden',
+ },
+ 'approval-mode': 'Approval Mode',
+ mcp: 'MCP',
+ 'token-caching': 'Token Caching',
+ sandbox: 'Sandboxing',
+};
diff --git a/docs/users/features/approval-mode.md b/docs/users/features/approval-mode.md
new file mode 100644
index 000000000..e072f237c
--- /dev/null
+++ b/docs/users/features/approval-mode.md
@@ -0,0 +1,263 @@
+# Approval Mode
+
+Qwen Code offers three distinct permission modes that allow you to flexibly control how AI interacts with your code and system based on task complexity and risk level.
+
+## Permission Modes Comparison
+
+| Mode | File Editing | Shell Commands | Best For | Risk Level |
+| -------------- | --------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ | ---------- |
+| **Plan** | ❌ Read-only analysis only | ❌ Not executed | • Code exploration • Planning complex changes
• Safe code review | Lowest | +| **Default** | ✅ Manual approval required | ✅ Manual approval required | • New/unfamiliar codebases
• Critical systems
• Team collaboration
• Learning and teaching | Low | +| **Auto-Edit** | ✅ Auto-approved | ❌ Manual approval required | • Daily development tasks
• Refactoring and code improvements
• Safe automation | Medium | +| **YOLO** | ✅ Auto-approved | ✅ Auto-approved | • Trusted personal projects
• Automated scripts/CI/CD
• Batch processing tasks | Highest | + +### Quick Reference Guide + +- **Start in Plan Mode**: Great for understanding before making changes +- **Work in Default Mode**: The balanced choice for most development work +- **Switch to Auto-Edit**: When you're making lots of safe code changes +- **Use YOLO sparingly**: Only for trusted automation in controlled environments + +> [!tip] +> +> You can quickly cycle through modes during a session using **Shift+Tab**. The terminal status bar shows your current mode, so you always know what permissions Qwen Code has. + +## 1. Use Plan Mode for safe code analysis + +Plan Mode instructs Qwen Code to create a plan by analyzing the codebase with **read-only** operations, perfect for exploring codebases, planning complex changes, or reviewing code safely. + +### When to use Plan Mode + +- **Multi-step implementation**: When your feature requires making edits to many files +- **Code exploration**: When you want to research the codebase thoroughly before changing anything +- **Interactive development**: When you want to iterate on the direction with Qwen Code + +### How to use Plan Mode + +**Turn on Plan Mode during a session** + +You can switch into Plan Mode during a session using **Shift+Tab** to cycle through permission modes. + +If you are in Normal Mode, **Shift+Tab** first switches into `auto-edits` Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** will switch into Plan Mode, indicated by `⏸ plan mode`. + +**Start a new session in Plan Mode** + +To start a new session in Plan Mode, use the `/approval-mode` then select `plan` + +```bash +/approval-mode +``` + +**Run "headless" queries in Plan Mode** + +You can also run a query in Plan Mode directly with `-p` or `prompt`: + +```bash +qwen --prompt "What is machine learning?" +``` + +### Example: Planning a complex refactor + +```bash +/approval-mode plan +``` + +``` +I need to refactor our authentication system to use OAuth2. Create a detailed migration plan. +``` + +Qwen Code analyzes the current implementation and create a comprehensive plan. Refine with follow-ups: + +``` +What about backward compatibility? +How should we handle database migration? +``` + +### Configure Plan Mode as default + +```json +// .qwen/settings.json +{ + "permissions": { + "defaultMode": "plan" + } +} +``` + +## 2. Use Default Mode for Controlled Interaction + +Default Mode is the standard way to work with Qwen Code. In this mode, you maintain full control over all potentially risky operations - Qwen Code will ask for your approval before making any file changes or executing shell commands. + +### When to use Default Mode + +- **New to a codebase**: When you're exploring an unfamiliar project and want to be extra cautious +- **Critical systems**: When working on production code, infrastructure, or sensitive data +- **Learning and teaching**: When you want to understand each step Qwen Code is taking +- **Team collaboration**: When multiple people are working on the same codebase +- **Complex operations**: When the changes involve multiple files or complex logic + +### How to use Default Mode + +**Turn on Default Mode during a session** + +You can switch into Default Mode during a session using **Shift+Tab** to cycle through permission modes. If you're in any other mode, pressing **Shift+Tab** will eventually cycle back to Default Mode, indicated by the absence of any mode indicator at the bottom of the terminal. + +**Start a new session in Default Mode** + +Default Mode is the initial mode when you start Qwen Code. If you've changed modes and want to return to Default Mode, use: + +``` +/approval-mode default +``` + +**Run "headless" queries in Default Mode** + +When running headless commands, Default Mode is the default behavior. You can explicitly specify it with: + +``` +qwen --prompt "Analyze this code for potential bugs" +``` + +### Example: Safely implementing a feature + +``` +/approval-mode default +``` + +``` +I need to add user profile pictures to our application. The pictures should be stored in an S3 bucket and the URLs saved in the database. +``` + +Qwen Code will analyze your codebase and propose a plan. It will then ask for approval before: + +1. Creating new files (controllers, models, migrations) +2. Modifying existing files (adding new columns, updating APIs) +3. Running any shell commands (database migrations, dependency installation) + +You can review each proposed change and approve or reject it individually. + +### Configure Default Mode as default + +```bash +// .qwen/settings.json +{ + "permissions": { +"defaultMode": "default" + } +} +``` + +## 3. Auto Edits Mode + +Auto-Edit Mode instructs Qwen Code to automatically approve file edits while requiring manual approval for shell commands, ideal for accelerating development workflows while maintaining system safety. + +### When to use Auto-Accept Edits Mode + +- **Daily development**: Ideal for most coding tasks +- **Safe automation**: Allows AI to modify code while preventing accidental execution of dangerous commands +- **Team collaboration**: Use in shared projects to avoid unintended impacts on others + +### How to switch to this mode + +``` +# Switch via command +/approval-mode auto-edit + +# Or use keyboard shortcut +Shift+Tab # Switch from other modes +``` + +### Workflow Example + +1. You ask Qwen Code to refactor a function +2. AI analyzes the code and proposes changes +3. **Automatically** applies all file changes without confirmation +4. If tests need to be run, it will **request approval** to execute `npm test` + +## 4. YOLO Mode - Full Automation + +YOLO Mode grants Qwen Code the highest permissions, automatically approving all tool calls including file editing and shell commands. + +### When to use YOLO Mode + +- **Automated scripts**: Running predefined automated tasks +- **CI/CD pipelines**: Automated execution in controlled environments +- **Personal projects**: Rapid iteration in fully trusted environments +- **Batch processing**: Tasks requiring multi-step command chains + +> [!warning] +> +> **Use YOLO Mode with caution**: AI can execute any command with your terminal permissions. Ensure: +> +> 1. You trust the current codebase +> 2. You understand all actions AI will perform +> 3. Important files are backed up or committed to version control + +### How to enable YOLO Mode + +``` +# Temporarily enable (current session only) +/approval-mode yolo + +# Set as project default +/approval-mode yolo --project + +# Set as user global default +/approval-mode yolo --user +``` + +### Configuration Example + +```bash +// .qwen/settings.json +{ + "permissions": { +"defaultMode": "yolo", +"confirmShellCommands": false, +"confirmFileEdits": false + } +} +``` + +### Automated Workflow Example + +```bash +# Fully automated refactoring task +qwen --prompt "Run the test suite, fix all failing tests, then commit changes" + +# Without human intervention, AI will: +# 1. Run test commands (auto-approved) +# 2. Fix failed test cases (auto-edit files) +# 3. Execute git commit (auto-approved) +``` + +## Mode Switching & Configuration + +### Keyboard Shortcut Switching + +During a Qwen Code session, use **Shift+Tab** to quickly cycle through the three modes: + +``` +Default Mode → Auto-Edit Mode → YOLO Mode → Plan Mode → Default Mode +``` + +### Persistent Configuration + +``` +// Project-level: ./.qwen/settings.json +// User-level: ~/.qwen/settings.json +{ + "permissions": { +"defaultMode": "auto-edit", // or "plan" or "yolo" +"confirmShellCommands": true, +"confirmFileEdits": true + } +} +``` + +### Mode Usage Recommendations + +1. **New to codebase**: Start with **Plan Mode** for safe exploration +2. **Daily development tasks**: Use **Auto-Accept Edits** (default mode), efficient and safe +3. **Automated scripts**: Use **YOLO Mode** in controlled environments for full automation +4. **Complex refactoring**: Use **Plan Mode** first for detailed planning, then switch to appropriate mode for execution diff --git a/docs/features/checkpointing.md b/docs/users/features/checkpointing.md similarity index 100% rename from docs/features/checkpointing.md rename to docs/users/features/checkpointing.md diff --git a/docs/users/features/commands.md b/docs/users/features/commands.md new file mode 100644 index 000000000..716fc3926 --- /dev/null +++ b/docs/users/features/commands.md @@ -0,0 +1,265 @@ +# Commands + +This document details all commands supported by Qwen Code, helping you efficiently manage sessions, customize the interface, and control its behavior. + +Qwen Code commands are triggered through specific prefixes and fall into three categories: + +| Prefix Type | Function Description | Typical Use Case | +| -------------------------- | --------------------------------------------------- | ---------------------------------------------------------------- | +| Slash Commands (`/`) | Meta-level control of Qwen Code itself | Managing sessions, modifying settings, getting help | +| At Commands (`@`) | Quickly inject local file content into conversation | Allowing AI to analyze specified files or code under directories | +| Exclamation Commands (`!`) | Direct interaction with system Shell | Executing system commands like `git status`, `ls`, etc. | + +## 1. Slash Commands (`/`) + +Slash commands are used to manage Qwen Code sessions, interface, and basic behavior. + +### 1.1 Session and Project Management + +These commands help you save, restore, and summarize work progress. + +| Command | Description | Usage Examples | +| ----------- | --------------------------------------------------------- | ------------------------------------ | +| `/init` | Analyze current directory and create initial context file | `/init` | +| `/summary` | Generate project summary based on conversation history | `/summary` | +| `/compress` | Replace chat history with summary to save Tokens | `/compress` | +| `/resume` | Resume a previous conversation session | `/resume` | +| `/restore` | Restore files to state before tool execution | `/restore` (list) or `/restore
(default: 600,000) | Request timeout in milliseconds (default: 600,000ms = 10 minutes) | +| `trust` | boolean
(default: false) | When `true`, bypasses all tool call confirmations for this server (default: `false`) | +| `includeTools` | array | List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (allowlist behavior). If not specified, all tools from the server are enabled by default. | +| `excludeTools` | array | List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server.
Note: `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded. | +| `targetAudience` | string | The OAuth Client ID allowlisted on the IAP-protected application you are trying to access. Used with `authProviderType: 'service_account_impersonation'`. | +| `targetServiceAccount` | string | The email address of the Google Cloud Service Account to impersonate. Used with `authProviderType: 'service_account_impersonation'`. | + + + +### Manage MCP servers with `qwen mcp` + +You can always configure MCP servers by manually editing `settings.json`, but the CLI is usually faster. + +#### Adding a server (`qwen mcp add`) + +```bash +qwen mcp add [options]
qwen*api_key: *(Optional)\_ The API key for the Qwen API.
+
+- qwen*cli_version: *(Optional, default: `latest`)\_ The version of the Qwen Code CLI to install. Can be "latest", "preview", "nightly", a specific version number, or a git branch, tag, or commit. For more information, see [Qwen Code CLI releases](https://github.com/QwenLM/qwen-code-action/blob/main/docs/releases.md).
+
+- qwen*debug: *(Optional)\_ Enable debug logging and output streaming.
+
+- qwen*model: *(Optional)\_ The model to use with Qwen Code.
+
+- prompt: _(Optional, default: `You are a helpful assistant.`)_ A string passed to the Qwen Code CLI's [`--prompt` argument](https://github.com/QwenLM/qwen-code-action/blob/main/docs/cli/configuration.md#command-line-arguments).
+
+- settings: _(Optional)_ A JSON string written to `.qwen/settings.json` to configure the CLI's _project_ settings.
+ For more details, see the documentation on [settings files](https://github.com/QwenLM/qwen-code-action/blob/main/docs/cli/configuration.md#settings-files).
+
+- use*qwen_code_assist: *(Optional, default: `false`)\_ Whether to use Code Assist for Qwen Code model access instead of the default Qwen Code API key.
+ For more information, see the [Qwen Code CLI documentation](https://github.com/QwenLM/qwen-code-action/blob/main/docs/cli/authentication.md).
+
+- use*vertex_ai: *(Optional, default: `false`)\_ Whether to use Vertex AI for Qwen Code model access instead of the default Qwen Code API key.
+ For more information, see the [Qwen Code CLI documentation](https://github.com/QwenLM/qwen-code-action/blob/main/docs/cli/authentication.md).
+
+- extensions: _(Optional)_ A list of Qwen Code CLI extensions to install.
+
+- upload*artifacts: *(Optional, default: `false`)\_ Whether to upload artifacts to the github action.
+
+- use*pnpm: *(Optional, default: `false`)\_ Whether or not to use pnpm instead of npm to install qwen-code-cli
+
+- workflow*name: *(Optional, default: `${{ github.workflow }}`)\_ The GitHub workflow name, used for telemetry purposes.
+
+
+
+### Outputs
+
+
+
+- summary: The summarized output from the Qwen Code CLI execution.
+
+- error: The error output from the Qwen Code CLI execution, if any.
+
+
+
+### Repository Variables
+
+We recommend setting the following values as repository variables so they can be reused across all workflows. Alternatively, you can set them inline as action inputs in individual workflows or to override repository-level values.
+
+| Name | Description | Type | Required | When Required |
+| ------------------ | --------------------------------------------------------- | -------- | -------- | ------------------------- |
+| `DEBUG` | Enables debug logging for the Qwen Code CLI. | Variable | No | Never |
+| `QWEN_CLI_VERSION` | Controls which version of the Qwen Code CLI is installed. | Variable | No | Pinning the CLI version |
+| `APP_ID` | GitHub App ID for custom authentication. | Variable | No | Using a custom GitHub App |
+
+To add a repository variable:
+
+1. Go to your repository's **Settings > Secrets and variables > Actions > New variable**.
+2. Enter the variable name and value.
+3. Save.
+
+For details about repository variables, refer to the [GitHub documentation on variables][variables].
+
+### Secrets
+
+You can set the following secrets in your repository:
+
+| Name | Description | Required | When Required |
+| ----------------- | --------------------------------------------- | -------- | ------------------------------------------ |
+| `QWEN_API_KEY` | Your Qwen API key from DashScope. | Yes | Required for all workflows that call Qwen. |
+| `APP_PRIVATE_KEY` | Private key for your GitHub App (PEM format). | No | Using a custom GitHub App. |
+
+To add a secret:
+
+1. Go to your repository's **Settings > Secrets and variables >Actions > New repository secret**.
+2. Enter the secret name and value.
+3. Save.
+
+For more information, refer to the [official GitHub documentation on creating and using encrypted secrets][secrets].
+
+## Authentication
+
+This action requires authentication to the GitHub API and optionally to Qwen Code services.
+
+### GitHub Authentication
+
+You can authenticate with GitHub in two ways:
+
+1. **Default `GITHUB_TOKEN`:** For simpler use cases, the action can use the
+ default `GITHUB_TOKEN` provided by the workflow.
+2. **Custom GitHub App (Recommended):** For the most secure and flexible
+ authentication, we recommend creating a custom GitHub App.
+
+For detailed setup instructions for both Qwen and GitHub authentication, go to the
+[**Authentication documentation**](./configuration/auth).
+
+## Extensions
+
+The Qwen Code CLI can be extended with additional functionality through extensions.
+These extensions are installed from source from their GitHub repositories.
+
+For detailed instructions on how to set up and configure extensions, go to the
+[Extensions documentation](../developers/extensions/extension).
+
+## Best Practices
+
+To ensure the security, reliability, and efficiency of your automated workflows, we strongly recommend following our best practices. These guidelines cover key areas such as repository security, workflow configuration, and monitoring.
+
+Key recommendations include:
+
+- **Securing Your Repository:** Implementing branch and tag protection, and restricting pull request approvers.
+- **Monitoring and Auditing:** Regularly reviewing action logs and enabling OpenTelemetry for deeper insights into performance and behavior.
+
+For a comprehensive guide on securing your repository and workflows, please refer to our [**Best Practices documentation**](./common-workflow).
+
+## Customization
+
+Create a QWEN.md file in the root of your repository to provide
+project-specific context and instructions to [Qwen Code CLI](./common-workflow). This is useful for defining
+coding conventions, architectural patterns, or other guidelines the model should
+follow for a given repository.
+
+## Contributing
+
+Contributions are welcome! Check out the Qwen Code CLI **Contributing Guide** for more details on how to get started.
+
+[secrets]: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
+[Qwen Code]: https://github.com/QwenLM/qwen-code
+[DashScope]: https://dashscope.console.aliyun.com/apiKey
+[Qwen Code CLI]: https://github.com/QwenLM/qwen-code-action/
+[variables]: https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables#creating-configuration-variables-for-a-repository
+[GitHub CLI]: https://docs.github.com/en/github-cli/github-cli
+[QWEN.md]: https://github.com/QwenLM/qwen-code-action/blob/main/docs/cli/configuration.md#context-files-hierarchical-instructional-context
diff --git a/docs/users/integration-vscode.md b/docs/users/integration-vscode.md
new file mode 100644
index 000000000..b12de7858
--- /dev/null
+++ b/docs/users/integration-vscode.md
@@ -0,0 +1,45 @@
+# Visual Studio Code
+
+> The VS Code extension (Beta) lets you see Qwen's changes in real-time through a native graphical interface integrated directly into your IDE, making it easier to access and interact with Qwen Code.
+
++ + + +### Features + +- **Native IDE experience**: Dedicated Qwen Code sidebar panel accessed via the Qwen icon +- **Auto-accept edits mode**: Automatically apply Qwen's changes as they're made +- **File management**: @-mention files or attach files and images using the system file picker +- **Conversation history**: Access to past conversations +- **Multiple sessions**: Run multiple Qwen Code sessions simultaneously + +### Requirements + +- VS Code 1.98.0 or higher + +### Installation + +1. Install Qwen Code CLI: + + ```bash + npm install -g qwen-code + ``` + +2. Download and install the extension from the [Visual Studio Code Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion). + +## Troubleshooting + +### Extension not installing + +- Ensure you have VS Code 1.98.0 or higher +- Check that VS Code has permission to install extensions +- Try installing directly from the Marketplace website + +### Qwen Code not responding + +- Check your internet connection +- Start a new conversation to see if the issue persists +- [File an issue on GitHub](https://github.com/qwenlm/qwen-code/issues) if the problem continues diff --git a/docs/users/integration-zed.md b/docs/users/integration-zed.md new file mode 100644 index 000000000..cd4cb2ae4 --- /dev/null +++ b/docs/users/integration-zed.md @@ -0,0 +1,54 @@ +# Zed Editor + +> Zed Editor provides native support for AI coding assistants through the Agent Control Protocol (ACP). This integration allows you to use Qwen Code directly within Zed's interface with real-time code suggestions. + + + +### Features + +- **Native agent experience**: Integrated AI assistant panel within Zed's interface +- **Agent Client Protocol**: Full support for ACP enabling advanced IDE interactions +- **File management**: @-mention files to add them to the conversation context +- **Conversation history**: Access to past conversations within Zed + +### Requirements + +- Zed Editor (latest version recommended) +- Qwen Code CLI installed + +### Installation + +1. Install Qwen Code CLI: + + ```bash + npm install -g qwen-code + ``` + +2. Download and install [Zed Editor](https://zed.dev/) + +3. In Zed, click the **settings button** in the top right corner, select **"Add agent"**, choose **"Create a custom agent"**, and add the following configuration: + +```json +"Qwen Code": { + "type": "custom", + "command": "qwen", + "args": ["--experimental-acp"], + "env": {} +} +``` + + + +## Troubleshooting + +### Agent not appearing + +- Run `qwen --version` in terminal to verify installation +- Check that the JSON configuration is valid +- Restart Zed Editor + +### Qwen Code not responding + +- Check your internet connection +- Verify CLI works by running `qwen` in terminal +- [File an issue on GitHub](https://github.com/qwenlm/qwen-code/issues) if the problem persists diff --git a/docs/users/overview.md b/docs/users/overview.md new file mode 100644 index 000000000..31a16040c --- /dev/null +++ b/docs/users/overview.md @@ -0,0 +1,62 @@ +# Qwen Code overview + +> Learn about Qwen Code, Qwen's agentic coding tool that lives in your terminal and helps you turn ideas into code faster than ever before. + +## Get started in 30 seconds + +Prerequisites: + +- A [Qwen Code](https://chat.qwen.ai/auth?mode=register) account +- Requires [Node.js 20+](https://nodejs.org/zh-cn/download), you can use `node -v` to check the version. If it's not installed, use the following command to install it. + +### Install Qwen Code: + +**NPM**(recommended) + +```bash +npm install -g @qwen-code/qwen-code@latest +``` + +**Homebrew**(macOS, Linux) + +```bash +brew install qwen-code +``` + +### Start using Qwen Code: + +```bash +cd your-project +qwen +``` + +Select **Qwen OAuth (Free)** authentication and follow the prompts to log in. Then let's start with understanding your codebase. Try one of these commands: + +``` +what does this project do? +``` + + + +You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 mins) →](./quickstart) + +> [!tip] +> +> See [troubleshooting](./support/troubleshooting) if you hit issues. + +> [!note] +> +> **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new **VS Code extension** provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Qwen Code directly in your sidebar. You can search for **Qwen Code** in the VS Code Marketplace and download it. + +## What Qwen Code does for you + +- **Build features from descriptions**: Tell Qwen Code what you want to build in plain language. It will make a plan, write the code, and ensure it works. +- **Debug and fix issues**: Describe a bug or paste an error message. Qwen Code will analyze your codebase, identify the problem, and implement a fix. +- **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Qwen Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](./features/mcp) can pull from external datasources like Google Drive, Figma, and Slack. +- **Automate tedious tasks**: Fix fiddly lint issues, resolve merge conflicts, and write release notes. Do all this in a single command from your developer machines, or automatically in CI. + +## Why developers love Qwen Code + +- **Works in your terminal**: Not another chat window. Not another IDE. Qwen Code meets you where you already work, with the tools you already love. +- **Takes action**: Qwen Code can directly edit files, run commands, and create commits. Need more? [MCP](./features/mcp) lets Qwen Code read your design docs in Google Drive, update your tickets in Jira, or use _your_ custom developer tooling. +- **Unix philosophy**: Qwen Code is composable and scriptable. `tail -f app.log | qwen -p "Slack me if you see any anomalies appear in this log stream"` _works_. Your CI can run `qwen -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`. diff --git a/docs/users/quickstart.md b/docs/users/quickstart.md new file mode 100644 index 000000000..1fa249abc --- /dev/null +++ b/docs/users/quickstart.md @@ -0,0 +1,251 @@ +# Quickstart + +> 👏 Welcome to Qwen Code! + +This quickstart guide will have you using AI-powered coding assistance in just a few minutes. By the end, you'll understand how to use Qwen Code for common development tasks. + +## Before you begin + +Make sure you have: + +- A **terminal** or command prompt open +- A code project to work with +- A [Qwen Code](https://chat.qwen.ai/auth?mode=register) account + +## Step 1: Install Qwen Code + +To install Qwen Code, use one of the following methods: + +### NPM (recommended) + +Requires [Node.js 20+](https://nodejs.org/download), you can use `node -v` check the version. If it's not installed, use the following command to install it. + +If you have [Node.js or newer installed](https://nodejs.org/en/download/): + +```sh +npm install -g @qwen-code/qwen-code@latest +``` + +### Homebrew (macOS, Linux) + +```sh +brew install qwen-code +``` + +## Step 2: Log in to your account + +Qwen Code requires an account to use. When you start an interactive session with the `qwen` command, you'll need to log in: + +```bash +# You'll be prompted to log in on first use +qwen +``` + +```bash +# Follow the prompts to log in with your account +/auth +``` + +Select `Qwen OAuth`, log in to your account and follow the prompts to confirm. Once logged in, your credentials are stored and you won't need to log in again. + +> [!note] +> +> When you first authenticate Qwen Code with your Qwen account, a workspace called ".qwen" is automatically created for you. This workspace provides centralized cost tracking and management for all Qwen Code usage in your organization. + +> [!tip] +> +> If you need to log in again or switch accounts, use the `/auth` command within Qwen Code. + +## Step 3: Start your first session + +Open your terminal in any project directory and start Qwen Code: + +```bash +# optiona +cd /path/to/your/project +# start qwen +qwen +``` + +You'll see the Qwen Code welcome screen with your session information, recent conversations, and latest updates. Type `/help` for available commands. + +## Chat with Qwen Code + +### Ask your first question + +Qwen Code will analyze your files and provide a summary. You can also ask more specific questions: + +``` +explain the folder structure +``` + +You can also ask Qwen Code about its own capabilities: + +``` +what can Qwen Code do? +``` + +> [!note] +> +> Qwen Code reads your files as needed - you don't have to manually add context. Qwen Code also has access to its own documentation and can answer questions about its features and capabilities. + +### Make your first code change + +Now let's make Qwen Code do some actual coding. Try a simple task: + +``` +add a hello world function to the main file +``` + +Qwen Code will: + +1. Find the appropriate file +2. Show you the proposed changes +3. Ask for your approval +4. Make the edit + +> [!note] +> +> Qwen Code always asks for permission before modifying files. You can approve individual changes or enable "Accept all" mode for a session. + +### Use Git with Qwen Code + +Qwen Code makes Git operations conversational: + +``` +what files have I changed? +``` + +``` +commit my changes with a descriptive message +``` + +You can also prompt for more complex Git operations: + +``` +create a new branch called feature/quickstart +``` + +``` +show me the last 5 commits +``` + +``` +help me resolve merge conflicts +``` + +### Fix a bug or add a feature + +Qwen Code is proficient at debugging and feature implementation. + +Describe what you want in natural language: + +``` +add input validation to the user registration form +``` + +Or fix existing issues: + +``` +there's a bug where users can submit empty forms - fix it +``` + +Qwen Code will: + +- Locate the relevant code +- Understand the context +- Implement a solution +- Run tests if available + +### Test out other common workflows + +There are a number of ways to work with Claude: + +**Refactor code** + +``` +refactor the authentication module to use async/await instead of callbacks +``` + +**Write tests** + +``` +write unit tests for the calculator functions +``` + +**Update documentation** + +``` +update the README with installation instructions +``` + +**Code review** + +``` +review my changes and suggest improvements +``` + +> [!tip] +> +> **Remember**: Qwen Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there. + +## Essential commands + +Here are the most important commands for daily use: + +| Command | What it does | Example | +| --------------------- | ------------------------------------------------ | ----------------------------- | +| `qwen` | start Qwen Code | `qwen` | +| `/auth` | Change authentication method | `/auth` | +| `/help` | Display help information for available commands | `/help` or `/?` | +| `/compress` | Replace chat history with summary to save Tokens | `/compress` | +| `/clear` | Clear terminal screen content | `/clear` (shortcut: `Ctrl+L`) | +| `/theme` | Change Qwen Code visual theme | `/theme` | +| `/language` | View or change language settings | `/language` | +| → `ui [language]` | Set UI interface language | `/language ui zh-CN` | +| → `output [language]` | Set LLM output language | `/language output Chinese` | +| `/quit` | Exit Qwen Code immediately | `/quit` or `/exit` | + +See the [CLI reference](./features/commands) for a complete list of commands. + +## Pro tips for beginners + +**Be specific with your requests** + +- Instead of: "fix the bug" +- Try: "fix the login bug where users see a blank screen after entering wrong credentials" + +**Use step-by-step instructions** + +- Break complex tasks into steps: + +``` +1. create a new database table for user profiles +2. create an API endpoint to get and update user profiles +3. build a webpage that allows users to see and edit their information +``` + +**Let Qwen Code explore first** + +- Before making changes, let Qwen Code understand your code: + +``` +analyze the database schema +``` + +``` +build a dashboard showing products that are most frequently returned by our UK customers +``` + +**Save time with shortcuts** + +- Press `?` to see all available keyboard shortcuts +- Use Tab for command completion +- Press ↑ for command history +- Type `/` to see all slash commands + +## Getting help + +- **In Qwen Code**: Type `/help` or ask "how do I..." +- **Documentation**: You're here! Browse other guides +- **Community**: Join our [GitHub Discussion](https://github.com/QwenLM/qwen-code/discussions) for tips and support diff --git a/docs/users/reference/_meta.ts b/docs/users/reference/_meta.ts new file mode 100644 index 000000000..a4c232e86 --- /dev/null +++ b/docs/users/reference/_meta.ts @@ -0,0 +1,3 @@ +export default { + 'keyboard-shortcuts': 'Keyboard Shortcuts', +}; diff --git a/docs/cli/keyboard-shortcuts.md b/docs/users/reference/keyboard-shortcuts.md similarity index 100% rename from docs/cli/keyboard-shortcuts.md rename to docs/users/reference/keyboard-shortcuts.md diff --git a/docs/cli/Uninstall.md b/docs/users/support/Uninstall.md similarity index 86% rename from docs/cli/Uninstall.md rename to docs/users/support/Uninstall.md index bdc7ae653..f8970c883 100644 --- a/docs/cli/Uninstall.md +++ b/docs/users/support/Uninstall.md @@ -1,4 +1,4 @@ -# Uninstalling the CLI +# Uninstall Your uninstall method depends on how you ran the CLI. Follow the instructions for either npx or a global npm installation. @@ -33,7 +33,7 @@ Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force ## Method 2: Using npm (Global Install) -If you installed the CLI globally (e.g., `npm install -g @qwen-code/qwen-code`), use the `npm uninstall` command with the `-g` flag to remove it. +If you installed the CLI globally (e.g. `npm install -g @qwen-code/qwen-code`), use the `npm uninstall` command with the `-g` flag to remove it. ```bash npm uninstall -g @qwen-code/qwen-code diff --git a/docs/support/_meta.ts b/docs/users/support/_meta.ts similarity index 77% rename from docs/support/_meta.ts rename to docs/users/support/_meta.ts index 9140d4fe7..1407565ae 100644 --- a/docs/support/_meta.ts +++ b/docs/users/support/_meta.ts @@ -1,4 +1,6 @@ export default { troubleshooting: 'Troubleshooting', 'tos-privacy': 'Terms of Service', + + Uninstall: 'Uninstall', }; diff --git a/docs/support/tos-privacy.md b/docs/users/support/tos-privacy.md similarity index 82% rename from docs/support/tos-privacy.md rename to docs/users/support/tos-privacy.md index 046b1d086..aa0d5c471 100644 --- a/docs/support/tos-privacy.md +++ b/docs/users/support/tos-privacy.md @@ -23,19 +23,21 @@ When you authenticate using your qwen.ai account, these Terms of Service and Pri - **Terms of Service:** Your use is governed by the [Qwen Terms of Service](https://qwen.ai/termsservice). - **Privacy Notice:** The collection and use of your data is described in the [Qwen Privacy Policy](https://qwen.ai/privacypolicy). -For details about authentication setup, quotas, and supported features, see [Authentication Setup](./cli/authentication.md). +For details about authentication setup, quotas, and supported features, see [Authentication Setup](../configuration/settings). ## 2. If you are using OpenAI-Compatible API Authentication When you authenticate using API keys from OpenAI-compatible providers, the applicable Terms of Service and Privacy Notice depend on your chosen provider. -**Important:** When using OpenAI-compatible API authentication, you are subject to the terms and privacy policies of your chosen API provider, not Qwen Code's terms. Please review your provider's documentation for specific details about data usage, retention, and privacy practices. +> [!important] +> +> When using OpenAI-compatible API authentication, you are subject to the terms and privacy policies of your chosen API provider, not Qwen Code's terms. Please review your provider's documentation for specific details about data usage, retention, and privacy practices. Qwen Code supports various OpenAI-compatible providers. Please refer to your specific provider's terms of service and privacy policy for detailed information. ## Usage Statistics and Telemetry -Qwen Code may collect anonymous usage statistics and telemetry data to improve the user experience and product quality. This data collection is optional and can be controlled through configuration settings. +Qwen Code may collect anonymous usage statistics and [telemetry](../../developers/development/telemetry) data to improve the user experience and product quality. This data collection is optional and can be controlled through configuration settings. ### What Data is Collected @@ -50,10 +52,6 @@ When enabled, Qwen Code may collect: - **Qwen OAuth:** Usage statistics are governed by Qwen's privacy policy. You can opt-out through Qwen Code's configuration settings. - **OpenAI-Compatible API:** No additional data is collected by Qwen Code beyond what your chosen API provider collects. -### Opt-Out Instructions - -You can disable usage statistics collection by following the instructions in the [Usage Statistics Configuration](./cli/configuration.md#usage-statistics) documentation. - ## Frequently Asked Questions (FAQ) ### 1. Is my code, including prompts and answers, used to train AI models? @@ -85,8 +83,6 @@ When enabled, Qwen Code may collect: The Usage Statistics setting only controls data collection by Qwen Code itself. It does not affect what data your chosen AI service provider (Qwen, OpenAI, etc.) may collect according to their own privacy policies. -You can disable Usage Statistics collection by following the instructions in the [Usage Statistics Configuration](./cli/configuration.md#usage-statistics) documentation. - ### 3. How do I switch between authentication methods? You can switch between Qwen OAuth and OpenAI-compatible API authentication at any time: @@ -95,4 +91,4 @@ You can switch between Qwen OAuth and OpenAI-compatible API authentication at an 2. **Within the CLI**: Use the `/auth` command to reconfigure your authentication method 3. **Environment variables**: Set up `.env` files for automatic OpenAI-compatible API authentication -For detailed instructions, see the [Authentication Setup](./cli/authentication.md) documentation. +For detailed instructions, see the [Authentication Setup](../configuration/settings#environment-variables-for-api-access) documentation. diff --git a/docs/support/troubleshooting.md b/docs/users/support/troubleshooting.md similarity index 90% rename from docs/support/troubleshooting.md rename to docs/users/support/troubleshooting.md index f654c1f64..5ea16b3cb 100644 --- a/docs/support/troubleshooting.md +++ b/docs/users/support/troubleshooting.md @@ -1,4 +1,4 @@ -# Troubleshooting guide +# Troubleshooting This guide provides solutions to common issues and debugging tips, including topics on: @@ -31,7 +31,7 @@ This guide provides solutions to common issues and debugging tips, including top 1. In your home directory: `~/.qwen/settings.json`. 2. In your project's root directory: `./.qwen/settings.json`. - Refer to [Qwen Code Configuration](./cli/configuration.md) for more details. + Refer to [Qwen Code Configuration](../configuration/settings) for more details. - **Q: Why don't I see cached token counts in my stats output?** - A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Qwen API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Qwen Code Assist API does not support cached content creation. You can still view your total token usage using the `/stats` command. @@ -48,7 +48,7 @@ This guide provides solutions to common issues and debugging tips, including top - **Solution:** The update depends on how you installed Qwen Code: - If you installed `qwen` globally, check that your `npm` global binary directory is in your `PATH`. You can update using the command `npm install -g @qwen-code/qwen-code@latest`. - - If you are running `qwen` from source, ensure you are using the correct command to invoke it (e.g., `node packages/cli/dist/index.js ...`). To update, pull the latest changes from the repository, and then rebuild using the command `npm run build`. + - If you are running `qwen` from source, ensure you are using the correct command to invoke it (e.g. `node packages/cli/dist/index.js ...`). To update, pull the latest changes from the repository, and then rebuild using the command `npm run build`. - **Error: `MODULE_NOT_FOUND` or import errors.** - **Cause:** Dependencies are not installed correctly, or the project hasn't been built. @@ -59,12 +59,12 @@ This guide provides solutions to common issues and debugging tips, including top - **Error: "Operation not permitted", "Permission denied", or similar.** - **Cause:** When sandboxing is enabled, Qwen Code may attempt operations that are restricted by your sandbox configuration, such as writing outside the project directory or system temp directory. - - **Solution:** Refer to the [Configuration: Sandboxing](./cli/configuration.md#sandboxing) documentation for more information, including how to customize your sandbox configuration. + - **Solution:** Refer to the [Configuration: Sandboxing](../features/sandbox) documentation for more information, including how to customize your sandbox configuration. - **Qwen Code is not running in interactive mode in "CI" environments** - - **Issue:** Qwen Code does not enter interactive mode (no prompt appears) if an environment variable starting with `CI_` (e.g., `CI_TOKEN`) is set. This is because the `is-in-ci` package, used by the underlying UI framework, detects these variables and assumes a non-interactive CI environment. + - **Issue:** Qwen Code does not enter interactive mode (no prompt appears) if an environment variable starting with `CI_` (e.g. `CI_TOKEN`) is set. This is because the `is-in-ci` package, used by the underlying UI framework, detects these variables and assumes a non-interactive CI environment. - **Cause:** The `is-in-ci` package checks for the presence of `CI`, `CONTINUOUS_INTEGRATION`, or any environment variable with a `CI_` prefix. When any of these are found, it signals that the environment is non-interactive, which prevents the CLI from starting in its interactive mode. - - **Solution:** If the `CI_` prefixed variable is not needed for the CLI to function, you can temporarily unset it for the command. e.g., `env -u CI_TOKEN qwen` + - **Solution:** If the `CI_` prefixed variable is not needed for the CLI to function, you can temporarily unset it for the command. e.g. `env -u CI_TOKEN qwen` - **DEBUG mode not working from project .env file** - **Issue:** Setting `DEBUG=true` in a project's `.env` file doesn't enable debug mode for the CLI. @@ -88,7 +88,7 @@ The Qwen Code uses specific exit codes to indicate the reason for termination. T | --------- | -------------------------- | --------------------------------------------------------------------------------------------------- | | 41 | `FatalAuthenticationError` | An error occurred during the authentication process. | | 42 | `FatalInputError` | Invalid or missing input was provided to the CLI. (non-interactive mode only) | -| 44 | `FatalSandboxError` | An error occurred with the sandboxing environment (e.g., Docker, Podman, or Seatbelt). | +| 44 | `FatalSandboxError` | An error occurred with the sandboxing environment (e.g. Docker, Podman, or Seatbelt). | | 52 | `FatalConfigError` | A configuration file (`settings.json`) is invalid or contains errors. | | 53 | `FatalTurnLimitedError` | The maximum number of conversational turns for the session was reached. (non-interactive mode only) | @@ -101,7 +101,7 @@ The Qwen Code uses specific exit codes to indicate the reason for termination. T - **Core debugging:** - Check the server console output for error messages or stack traces. - Increase log verbosity if configurable. - - Use Node.js debugging tools (e.g., `node --inspect`) if you need to step through server-side code. + - Use Node.js debugging tools (e.g. `node --inspect`) if you need to step through server-side code. - **Tool issues:** - If a specific tool is failing, try to isolate the issue by running the simplest possible version of the command or operation the tool performs. diff --git a/eslint.config.js b/eslint.config.js index 5b3b7f3d0..26ec8edf8 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -75,6 +75,8 @@ export default tseslint.config( }, }, rules: { + // We use TypeScript for React components; prop-types are unnecessary + 'react/prop-types': 'off', // General Best Practice Rules (subset adapted for flat config) '@typescript-eslint/array-type': ['error', { default: 'array-simple' }], 'arrow-body-style': ['error', 'as-needed'], @@ -111,10 +113,14 @@ export default tseslint.config( { allow: [ 'react-dom/test-utils', + 'react-dom/client', 'memfs/lib/volume.js', 'yargs/**', 'msw/node', - '**/generated/**' + '**/generated/**', + './styles/tailwind.css', + './styles/App.css', + './styles/style.css' ], }, ], @@ -257,4 +263,25 @@ export default tseslint.config( ], }, }, + // Settings for docs-site directory + { + files: ['docs-site/**/*.{js,jsx}'], + languageOptions: { + globals: { + ...globals.browser, + ...globals.node, + }, + parserOptions: { + ecmaFeatures: { + jsx: true, + }, + }, + }, + rules: { + // Allow relaxed rules for documentation site + '@typescript-eslint/no-unused-vars': 'off', + 'react/prop-types': 'off', + 'react/react-in-jsx-scope': 'off', + }, + }, ); diff --git a/integration-tests/acp-integration.test.ts b/integration-tests/acp-integration.test.ts index b098e0251..31e32da76 100644 --- a/integration-tests/acp-integration.test.ts +++ b/integration-tests/acp-integration.test.ts @@ -13,8 +13,6 @@ import { TestRig } from './test-helper.js'; const REQUEST_TIMEOUT_MS = 60_000; const INITIAL_PROMPT = 'Create a quick note (smoke test).'; -const RESUME_PROMPT = 'Continue the note after reload.'; -const LIST_SIZE = 5; const IS_SANDBOX = process.env['GEMINI_SANDBOX'] && process.env['GEMINI_SANDBOX']!.toLowerCase() !== 'false'; @@ -25,6 +23,14 @@ type PendingRequest = { timeout: NodeJS.Timeout; }; +type UsageMetadata = { + promptTokens?: number | null; + completionTokens?: number | null; + thoughtsTokens?: number | null; + totalTokens?: number | null; + cachedTokens?: number | null; +}; + type SessionUpdateNotification = { sessionId?: string; update?: { @@ -39,6 +45,9 @@ type SessionUpdateNotification = { text?: string; }; modeId?: string; + _meta?: { + usage?: UsageMetadata; + }; }; }; @@ -86,10 +95,14 @@ function setupAcpTest( const permissionHandler = options?.permissionHandler ?? (() => ({ optionId: 'proceed_once' })); - const agent = spawn('node', [rig.bundlePath, '--experimental-acp'], { - cwd: rig.testDir!, - stdio: ['pipe', 'pipe', 'pipe'], - }); + const agent = spawn( + 'node', + [rig.bundlePath, '--experimental-acp', '--no-chat-recording'], + { + cwd: rig.testDir!, + stdio: ['pipe', 'pipe', 'pipe'], + }, + ); agent.stderr?.on('data', (chunk) => { stderr.push(chunk.toString()); @@ -253,11 +266,11 @@ function setupAcpTest( } (IS_SANDBOX ? describe.skip : describe)('acp integration', () => { - it('creates, lists, loads, and resumes a session', async () => { + it('basic smoke test', async () => { const rig = new TestRig(); rig.setup('acp load session'); - const { sendRequest, cleanup, stderr, sessionUpdates } = setupAcpTest(rig); + const { sendRequest, cleanup, stderr } = setupAcpTest(rig); try { const initResult = await sendRequest('initialize', { @@ -283,34 +296,6 @@ function setupAcpTest( prompt: [{ type: 'text', text: INITIAL_PROMPT }], }); expect(promptResult).toBeDefined(); - - await delay(500); - - const listResult = (await sendRequest('session/list', { - cwd: rig.testDir!, - size: LIST_SIZE, - })) as { items?: Array<{ sessionId: string }> }; - - expect(Array.isArray(listResult.items)).toBe(true); - expect(listResult.items?.length ?? 0).toBeGreaterThan(0); - - const sessionToLoad = listResult.items![0].sessionId; - await sendRequest('session/load', { - cwd: rig.testDir!, - sessionId: sessionToLoad, - mcpServers: [], - }); - - const resumeResult = await sendRequest('session/prompt', { - sessionId: sessionToLoad, - prompt: [{ type: 'text', text: RESUME_PROMPT }], - }); - expect(resumeResult).toBeDefined(); - - const sessionsWithUpdates = sessionUpdates - .map((update) => update.sessionId) - .filter(Boolean); - expect(sessionsWithUpdates).toContain(sessionToLoad); } catch (e) { if (stderr.length) { console.error('Agent stderr:', stderr.join('')); @@ -587,4 +572,52 @@ function setupAcpTest( await cleanup(); } }); + + it('receives usage metadata in agent_message_chunk updates', async () => { + const rig = new TestRig(); + rig.setup('acp usage metadata'); + + const { sendRequest, cleanup, stderr, sessionUpdates } = setupAcpTest(rig); + + try { + await sendRequest('initialize', { + protocolVersion: 1, + clientCapabilities: { fs: { readTextFile: true, writeTextFile: true } }, + }); + await sendRequest('authenticate', { methodId: 'openai' }); + + const newSession = (await sendRequest('session/new', { + cwd: rig.testDir!, + mcpServers: [], + })) as { sessionId: string }; + + await sendRequest('session/prompt', { + sessionId: newSession.sessionId, + prompt: [{ type: 'text', text: 'Say "hello".' }], + }); + + await delay(500); + + // Find updates with usage metadata + const updatesWithUsage = sessionUpdates.filter( + (u) => + u.update?.sessionUpdate === 'agent_message_chunk' && + u.update?._meta?.usage, + ); + + expect(updatesWithUsage.length).toBeGreaterThan(0); + + const usage = updatesWithUsage[0].update?._meta?.usage; + expect(usage).toBeDefined(); + expect( + typeof usage?.promptTokens === 'number' || + typeof usage?.totalTokens === 'number', + ).toBe(true); + } catch (e) { + if (stderr.length) console.error('Agent stderr:', stderr.join('')); + throw e; + } finally { + await cleanup(); + } + }); }); diff --git a/integration-tests/file-system.test.ts b/integration-tests/file-system.test.ts index bd15c76eb..9e8176290 100644 --- a/integration-tests/file-system.test.ts +++ b/integration-tests/file-system.test.ts @@ -202,8 +202,8 @@ describe('file-system', () => { const readAttempt = toolLogs.find( (log) => log.toolRequest.name === 'read_file', ); - const writeAttempt = toolLogs.find( - (log) => log.toolRequest.name === 'write_file', + const editAttempt = toolLogs.find( + (log) => log.toolRequest.name === 'edit_file', ); const successfulReplace = toolLogs.find( (log) => log.toolRequest.name === 'replace' && log.toolRequest.success, @@ -226,15 +226,15 @@ describe('file-system', () => { // CRITICAL: Verify that no matter what the model did, it never successfully // wrote or replaced anything. - if (writeAttempt) { + if (editAttempt) { console.error( - 'A write_file attempt was made when no file should be written.', + 'A edit_file attempt was made when no file should be written.', ); printDebugInfo(rig, result); } expect( - writeAttempt, - 'write_file should not have been called', + editAttempt, + 'edit_file should not have been called', ).toBeUndefined(); if (successfulReplace) { diff --git a/integration-tests/sdk-typescript/configuration-options.test.ts b/integration-tests/sdk-typescript/configuration-options.test.ts index bc59cd791..ca218248c 100644 --- a/integration-tests/sdk-typescript/configuration-options.test.ts +++ b/integration-tests/sdk-typescript/configuration-options.test.ts @@ -438,12 +438,8 @@ describe('Configuration Options (E2E)', () => { } }); - // Skip in containerized sandbox environments - qwen-oauth requires user interaction - // which is not possible in Docker/Podman CI environments - it.skipIf( - process.env['SANDBOX'] === 'sandbox:docker' || - process.env['SANDBOX'] === 'sandbox:podman', - )('should accept authType: qwen-oauth', async () => { + // Skip - qwen-oauth requires user interaction which is not possible in CI environments + it.skip('should accept authType: qwen-oauth', async () => { // Note: qwen-oauth requires credentials in ~/.qwen and user interaction // Without credentials, the auth process will timeout waiting for user // This test verifies the option is accepted and passed correctly to CLI diff --git a/integration-tests/sdk-typescript/permission-control.test.ts b/integration-tests/sdk-typescript/permission-control.test.ts index e8d201e6e..974f72b37 100644 --- a/integration-tests/sdk-typescript/permission-control.test.ts +++ b/integration-tests/sdk-typescript/permission-control.test.ts @@ -952,7 +952,8 @@ describe('Permission Control (E2E)', () => { TEST_TIMEOUT, ); - it( + // FIXME: This test is flaky and sometimes fails with no tool calls. + it.skip( 'should allow read-only tools without restrictions', async () => { // Create test files for the model to read diff --git a/integration-tests/sdk-typescript/test-helper.ts b/integration-tests/sdk-typescript/test-helper.ts index f3005655e..d7efc026c 100644 --- a/integration-tests/sdk-typescript/test-helper.ts +++ b/integration-tests/sdk-typescript/test-helper.ts @@ -73,15 +73,26 @@ export class SDKTestHelper { await mkdir(this.testDir, { recursive: true }); // Optionally create .qwen/settings.json for CLI configuration - if (options.createQwenConfig) { + if (options.createQwenConfig !== false) { const qwenDir = join(this.testDir, '.qwen'); await mkdir(qwenDir, { recursive: true }); + const optionsSettings = options.settings ?? {}; + const generalSettings = + typeof optionsSettings['general'] === 'object' && + optionsSettings['general'] !== null + ? (optionsSettings['general'] as Record