> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install and configure the Qwen Code TypeScript SDK

## Install the SDK

Install the SDK using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install @qwen-code/sdk
  ```

  ```bash yarn theme={null}
  yarn add @qwen-code/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @qwen-code/sdk
  ```
</CodeGroup>

## 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

```bash theme={null}
node --version
```

If you need to upgrade Node.js, visit [nodejs.org](https://nodejs.org/) or use a version manager like [nvm](https://github.com/nvm-sh/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:

```bash theme={null}
npm install -g qwen-code@^0.4.0
```

The CLI must be accessible in your PATH. Verify the installation:

```bash theme={null}
qwen --version
```

<Warning>
  We recommend upgrading to SDK version **0.1.1** or later to benefit from the bundled CLI and avoid installation complexity.
</Warning>

## 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:

```bash theme={null}
export OPENAI_API_KEY="your-api-key-here"
```

For persistent configuration, add it to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):

```bash theme={null}
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
```

### Qwen OAuth (Alternative)

<Warning>
  Using Qwen OAuth in the SDK is **not recommended** because credentials are stored in `~/.qwen` and may need periodic refresh.
</Warning>

If you still want to use Qwen OAuth:

```typescript theme={null}
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:

```bash theme={null}
npx qwen-code auth
```

## TypeScript Configuration

For TypeScript projects, ensure your `tsconfig.json` includes:

```json tsconfig.json theme={null}
{
  "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:

```typescript test.ts theme={null}
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:

```bash theme={null}
npx tsx test.ts
```

You should see the AI's response printed to the console.

## Dependencies

The SDK has minimal dependencies:

```json package.json theme={null}
{
  "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` |

<Note>
  The `model` option in `QueryOptions` takes precedence over environment variables.
</Note>

## 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

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/sdk/quick-start">
    Run your first query
  </Card>

  <Card title="API Reference" icon="book" href="/sdk/api/query">
    Explore the query() function
  </Card>
</CardGroup>