Skip to main content

​
Install the SDK

Install the SDK using your preferred package manager: 
npm install @qwen-code/sdk

​
Requirements

Ensure your environment meets the following requirements:
  • Node.js: >= 18.0.0
  • TypeScript: >= 5.0.0 (for TypeScript projects)

​
Check Your Node.js Version

node --version
If you need to upgrade Node.js, visit nodejs.org or use a version manager like nvm.

​
CLI Bundling

From SDK version 0.1.1 onwards, the Qwen Code CLI is bundled with the SDK package. You don’t need to install the CLI separately.

​
SDK Version 0.1.0 (Legacy)

If you’re using SDK version 0.1.0, you must install the Qwen Code CLI separately: 
npm install -g qwen-code@^0.4.0
The CLI must be accessible in your PATH. Verify the installation: 
qwen --version
We recommend upgrading to SDK version 0.1.1 or later to benefit from the bundled CLI and avoid installation complexity.

​
Authentication Setup

The SDK requires API credentials to communicate with AI models. You can use either OpenAI-compatible APIs or Qwen’s OAuth service. Set your API key as an environment variable: 
export OPENAI_API_KEY="your-api-key-here"
For persistent configuration, add it to your shell profile (~/.bashrc, ~/.zshrc, etc.): 
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

​
Qwen OAuth (Alternative)

Using Qwen OAuth in the SDK is not recommended because credentials are stored in ~/.qwen and may need periodic refresh.
If you still want to use Qwen OAuth: 
import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'Hello',
  options: {
    authType: 'qwen-oauth',
  },
});
You’ll need to authenticate with the Qwen CLI first: 
npx qwen-code auth

​
TypeScript Configuration

For TypeScript projects, ensure your tsconfig.json includes:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  }
}

​
Verify Installation

Create a simple test file to verify everything works:
test.ts
import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'What is 2 + 2?',
  options: {},
});

for await (const message of result) {
  if (message.type === 'assistant') {
    console.log('Assistant:', message.message.content);
  } else if (message.type === 'result') {
    console.log('Done! Usage:', message.usage);
  }
}
Run the test: 
npx tsx test.ts
You should see the AI’s response printed to the console.

​
Dependencies

The SDK has minimal dependencies:
package.json
{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.25.1",
    "zod": "^3.25.0"
  }
}
  • @modelcontextprotocol/sdk: For MCP server integration
  • zod: For schema validation in custom tools

​
Environment Variables

The SDK respects the following environment variables:
VariableDescriptionExample
OPENAI_API_KEYAPI key for OpenAI-compatible servicessk-...
OPENAI_MODELDefault model to usegpt-4
QWEN_MODELQwen-specific model (fallback)qwen-max
QWEN_CODE_CLI_PATHCustom path to CLI executable/path/to/qwen
The model option in QueryOptions takes precedence over environment variables.

​
Troubleshooting

​
Command Not Found Error

If you see “qwen: command not found” when using SDK version 0.1.0:
  1. Ensure the CLI is installed globally: npm install -g qwen-code@^0.4.0
  2. Check your PATH includes the global npm bin directory
  3. Or upgrade to SDK version 0.1.1+ to use the bundled CLI

​
Module Resolution Errors

If you encounter module resolution errors:
  1. Ensure Node.js version is >= 18.0.0
  2. Check that "type": "module" is in your package.json for ESM projects
  3. Use node --loader tsx or npx tsx for TypeScript files

​
API Authentication Errors

If queries fail with authentication errors:
  1. Verify OPENAI_API_KEY is set correctly
  2. Check that the API key has sufficient permissions
  3. Ensure you’re not hitting rate limits

​
Next Steps

Quick Start

Run your first query

API Reference

Explore the query() function