Installation

Install and configure the Qwen Code TypeScript SDK

Install the SDK

Install the SDK using your preferred package manager:

npm

npm install @qwen-code/sdk

yarn add @qwen-code/sdk

pnpm add @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.

OpenAI-Compatible API (Recommended)

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:

Variable	Description	Example
OPENAI_API_KEY	API key for OpenAI-compatible services	sk-...
OPENAI_MODEL	Default model to use	gpt-4
QWEN_MODEL	Qwen-specific model (fallback)	qwen-max
QWEN_CODE_CLI_PATH	Custom 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