Skip to main content
Get up and running with Qwen Code quickly. This guide will walk you through your first session and show you the essential features.
Before you begin: Make sure you’ve installed Qwen Code.

​
Start Your First Session

1

Launch Qwen Code

Open your terminal and navigate to your project directory:
cd your-project
qwen
On first launch, you’ll be prompted to authenticate. You can choose between:
  • Qwen OAuth (recommended): Free tier with 1,000 requests/day
  • API Key: Use OpenAI, Anthropic, Gemini, or other compatible providers
If you’re in a CI/CD environment or SSH session where browser OAuth isn’t available, use the API key method instead.
2

Authenticate

Run the auth command to set up your authentication:
/auth
For Qwen OAuth:
  1. Select “Qwen OAuth” from the menu
  2. A browser window will open
  3. Sign in with your qwen.ai account
  4. Return to the terminal - you’re ready to go!
For API Key:
  1. Select “API Key” from the menu
  2. Choose your provider (OpenAI, Anthropic, Gemini, etc.)
  3. Enter your API key when prompted
See the Authentication guide for detailed configuration options.
3

Try Your First Prompt

Now you’re ready to interact with Qwen Code! Try some of these prompts:
What does this project do?

Explain the codebase structure

Help me refactor this function

Generate unit tests for this module
You can reference specific files using @filename syntax, like: “Explain @src/main.ts”

​
Essential Commands

Learn the key commands to navigate your Qwen Code session.
Display a list of all available commands and their descriptions.
/help
Start a fresh conversation while keeping your configuration.
/clear
Change to a different model mid-session.
/model
Select from your configured models or add a new one.
See token usage, costs, and other session metrics.
/stats
Save your session and exit the CLI.
/exit

​
Keyboard Shortcuts

Make your workflow faster with these keyboard shortcuts:
ShortcutAction
Ctrl+CCancel current operation
Ctrl+DExit (on empty line)
Up/DownNavigate command history

​
Headless Mode

Run Qwen Code in non-interactive mode for scripts and automation: 
qwen -p "your question or task"
Example uses: 
qwen -p "Review the code in src/ and suggest improvements"
See Headless Mode for more details.

​
Reference Files

You can reference specific files in your prompts using the @ syntax: 
Explain @src/main.ts

Refactor @components/UserList.tsx to use hooks

Compare @old/api.ts with @new/api.ts

​
Common Use Cases

​
Code Explanation

What does the calculateTotal function in @src/utils/cart.ts do?

​
Code Generation

Create a user authentication system with JWT tokens

​
Debugging

Why is this error occurring in @src/api/products.ts?

​
Refactoring

Refactor @src/legacy/utils.js to use ES6+ features

​
Advanced Features

Once you’re comfortable with the basics, explore these powerful features:

Approval Modes

Control how Qwen Code executes commands with different permission levels

Subagents

Delegate complex tasks to specialized AI agents

Skills

Extend Qwen Code with reusable skill modules

MCP Integration

Connect to Model Context Protocol servers

​
Session Management

​
Save and Resume Sessions

Your session history is automatically saved. To resume a previous session: 
qwen --resume <session-id>
List your recent sessions: 
/stats

​
Clear History

If you want to start fresh while keeping your configuration: 
/clear

​
Configuration

Customize Qwen Code to fit your workflow:

​
Model Selection

Set your preferred model in ~/.qwen/settings.json: 
{
  "model": {
    "name": "qwen3-coder-plus"
  }
}
Or switch models on the fly: 
/model

​
Approval Mode

Choose how Qwen Code handles command execution:
  • Plan: Review plan before execution
  • Default: Approve each command
  • Auto-edit: Auto-approve file edits
  • YOLO: Auto-approve everything
Set via command line: 
qwen --yolo    # Auto-approve everything
qwen --plan    # Plan mode
Or change mid-session: 
/approval-mode
Learn more in Approval Modes.

​
Troubleshooting

If OAuth fails:
  1. Make sure you have a browser available
  2. Try clearing your credentials: rm -rf ~/.qwen/credentials
  3. Use API key authentication instead in headless environments
For API key issues:
  1. Verify your API key is correct
  2. Check that the provider is properly configured
  3. Ensure you have network access to the API endpoint
If you get “qwen: command not found”:
  1. Make sure you’ve installed Qwen Code globally
  2. Restart your terminal after installation
  3. Check that npm global bin is in your PATH
npm install -g @qwen-code/qwen-code
If responses are slow:
  1. Check your internet connection
  2. Try a different model (some are faster)
  3. Use /compress to reduce context size
  4. Check API service status for your provider
If Qwen Code behaves unexpectedly:
  1. Run /clear to reset context
  2. Check approval mode settings
  3. Verify your configuration in ~/.qwen/settings.json
  4. Use /bug to report issues with system info

​
Next Steps

Explore Interactive Mode

Learn all the features of the interactive terminal UI

Configure Providers

Set up multiple AI providers and models

Integrate with Your IDE

Use Qwen Code inside VS Code, Zed, or JetBrains

Advanced Features

Explore subagents, skills, and more