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

# Zed Editor Integration

> Use Qwen Code as an agent server in Zed via the Agent Client Protocol

The Qwen Code extension for Zed integrates Qwen Code as an AI agent server using the [Agent Client Protocol (ACP)](https://agentclientprotocol.com). This provides a native agent experience directly within Zed's interface.

## Features

<CardGroup cols={2}>
  <Card title="Native Agent Experience" icon="robot">
    Integrated AI assistant panel within Zed's interface
  </Card>

  <Card title="Agent Client Protocol" icon="plug">
    Full support for ACP enabling advanced IDE interactions
  </Card>

  <Card title="File Management" icon="at">
    @-mention files to add them to the conversation context
  </Card>

  <Card title="Conversation History" icon="clock-rotate-left">
    Access to past conversations within Zed
  </Card>

  <Card title="Multi-platform" icon="desktop">
    Works on macOS (ARM64 & Intel), Linux, and Windows
  </Card>

  <Card title="Workspace Awareness" icon="folder-tree">
    Read, write, and edit files in your workspace
  </Card>
</CardGroup>

## Requirements

<Note>
  The Zed extension requires the Qwen Code CLI to be installed separately.
</Note>

* **Zed Editor**: Latest version recommended
* **Node.js**: Version 20 or later
* **Qwen Code CLI**: Installed globally via npm
* **Internet connection**: For AI model access

## Installation

<Steps>
  <Step title="Install Qwen Code CLI">
    First, install the Qwen Code CLI globally:

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

    Verify the installation:

    ```bash theme={null}
    qwen --version
    ```
  </Step>

  <Step title="Install Zed Extension">
    Open Zed and install the extension using one of these methods:

    **Via Extensions Panel:**

    1. Open the Extensions panel:
       * macOS: `cmd-shift-x`
       * Linux/Windows: `ctrl-shift-x`
    2. Search for "Qwen Code"
    3. Click "Install"

    **Via Command Line:**

    ```bash theme={null}
    zed --install-extension qwen-code
    ```
  </Step>

  <Step title="Enable Agent Server">
    After installation:

    1. Switch to the **Agent Server** tab in the Extensions panel
    2. Ensure "Qwen Code" is enabled
    3. The agent server will start automatically
  </Step>

  <Step title="Open Agent Panel">
    Launch the Agent Panel:

    * macOS: `cmd-shift-a`
    * Linux/Windows: `ctrl-shift-a`

    Select "Qwen Code" from the agent list and start chatting!
  </Step>
</Steps>

## Usage

### Opening the Agent Panel

Access the Qwen Code agent:

1. Press `cmd-shift-a` (macOS) or `ctrl-shift-a` (Linux/Windows)
2. Select "Qwen Code" from the agent dropdown
3. Start your conversation

### Using @-mentions

Reference files in your workspace:

```
@filename to mention specific files
@directory/ to reference entire directories
```

Example:

```
Explain what @src/main.rs does
Refactor @utils/parser.ts to improve performance
Add tests for @components/Button.tsx
```

### Agent Capabilities

The Qwen Code agent can:

* **Read files**: Access any file in your workspace
* **Write files**: Create new files or modify existing ones
* **Edit code**: Make surgical changes to specific functions or sections
* **Explain code**: Provide detailed explanations of code structure and logic
* **Debug**: Help identify and fix bugs
* **Suggest improvements**: Recommend refactorings and optimizations

### Natural Language Commands

Use natural language to describe what you want:

```
"Explain the codebase structure"
"Find all TODO comments"
"Refactor this function to use async/await"
"Generate unit tests for the parser module"
"Fix the type errors in src/types.ts"
```

## Configuration

### Environment Variables

The Zed extension inherits environment variables from Zed. To set custom variables:

1. Open Zed settings (macOS: `cmd-,`, Linux/Windows: `ctrl-,`)
2. Add agent server environment variables:

```json theme={null}
{
  "agent_servers": {
    "qwen-code": {
      "env": {
        "QWEN_LOG_LEVEL": "info",
        "YOUR_CUSTOM_VAR": "value"
      }
    }
  }
}
```

### Qwen Code Settings

The agent server reads configuration from:

* **User settings**: `~/.qwen/settings.json`
* **Project settings**: `.qwen/settings.json` (workspace root)

Configure authentication, models, and other options:

```json theme={null}
{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "envKey": "DASHSCOPE_API_KEY"
      }
    ]
  },
  "env": {
    "DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3-coder-plus"
  }
}
```

See the [Configuration Guide](/users/configuration/settings) for all options.

### Authentication

The extension uses your existing Qwen Code authentication. Configure it by running the CLI:

```bash theme={null}
qwen
/auth
```

Choose between:

* **Qwen OAuth**: Free tier with 1,000 requests/day
* **API Key**: Use OpenAI, Anthropic, or other compatible providers

## Platform Support

The Zed extension is available for:

| Platform | Architecture          | Status      |
| -------- | --------------------- | ----------- |
| macOS    | ARM64 (Apple Silicon) | ✅ Supported |
| macOS    | x86\_64 (Intel)       | ✅ Supported |
| Linux    | x86\_64               | ✅ Supported |
| Windows  | x86\_64               | ✅ Supported |

<Note>
  The current version requires Node.js to run. A single-file executable version is in development.
</Note>

## Tips & Best Practices

<AccordionGroup>
  <Accordion title="Mention files explicitly">
    Always use @-mentions to specify which files you're asking about. This gives Qwen precise context:

    Good: "Refactor @src/parser.ts to use async/await"

    Not as good: "Refactor the parser file"
  </Accordion>

  <Accordion title="Review changes before accepting">
    When Qwen suggests file changes, review them carefully in Zed's diff view before accepting.
  </Accordion>

  <Accordion title="Use conversation history">
    Build on previous conversations. Qwen remembers the context from your chat history.
  </Accordion>

  <Accordion title="Start broad, then narrow">
    Begin with high-level questions ("What does this project do?") then drill down into specifics.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server shutdown unexpectedly">
    **Issue**: Error message "server shut down unexpectedly"

    **Solutions**:

    1. Collect logs:
       * Press `cmd-shift-p` (macOS) or `ctrl-shift-p` (Windows/Linux)
       * Select **Zed: Open Log**
    2. Check logs for errors related to:
       * Agent server startup
       * Node.js runtime
       * Qwen Code CLI
    3. Verify Qwen Code CLI works:
       ```bash theme={null}
       qwen --version
       qwen --acp
       ```
    4. Check Node.js version:
       ```bash theme={null}
       node --version  # Should be 20 or later
       ```
  </Accordion>

  <Accordion title="Agent server starts but has issues">
    **Issue**: Agent starts but encounters problems during use

    **Solutions**:

    1. Open ACP logs:
       * Press `cmd-shift-p` (macOS) or `ctrl-shift-p` (Windows/Linux)
       * Select **Dev: Open ACP Logs**
    2. Look for error messages in the ACP logs
    3. Check authentication:
       ```bash theme={null}
       qwen
       /auth
       ```
    4. Verify internet connectivity
  </Accordion>

  <Accordion title="Agent not appearing in list">
    **Issue**: Can't find Qwen Code in the agent dropdown

    **Solutions**:

    * Verify the extension is installed (check Extensions panel)
    * Ensure the agent server is enabled in the Agent Server tab
    * Restart Zed
    * Check that Qwen Code CLI is installed:
      ```bash theme={null}
      which qwen  # Unix/macOS
      where qwen  # Windows
      ```
  </Accordion>

  <Accordion title="Authentication errors">
    **Issue**: Agent can't authenticate or make requests

    **Solutions**:

    1. Run authentication setup:
       ```bash theme={null}
       qwen
       /auth
       ```
    2. Check `~/.qwen/settings.json` for correct API keys
    3. Test authentication in the CLI:
       ```bash theme={null}
       qwen -p "Hello"
       ```
    4. Verify API key validity with your provider
  </Accordion>
</AccordionGroup>

### Viewing Logs

Access different log files for debugging:

| Log Type  | How to Access                          | Contains                            |
| --------- | -------------------------------------- | ----------------------------------- |
| Zed Logs  | `cmd/ctrl-shift-p` → "Zed: Open Log"   | General Zed and extension logs      |
| ACP Logs  | `cmd/ctrl-p` → "Dev: Open ACP Logs"    | Agent Client Protocol communication |
| Qwen Logs | Terminal: `tail -f ~/.qwen/logs/*.log` | Qwen Code CLI logs                  |

## Reporting Issues

If you encounter problems:

1. **Collect diagnostic information**:
   * Zed version: Help → About Zed
   * Qwen Code version: `qwen --version`
   * Node.js version: `node --version`
   * Relevant log excerpts

2. **Report the issue** at one of these locations:
   * [Qwen Code Issues](https://github.com/QwenLM/qwen-code/issues)
   * [Qwen Code Zed Extension Issues](https://github.com/QwenLM/qwen-code-zed-extension/issues)

3. **Include in your report**:
   * Clear description of the issue
   * Steps to reproduce
   * Expected vs. actual behavior
   * Relevant log excerpts
   * System information

## Resources

<CardGroup cols={2}>
  <Card title="Zed Agent Panel Guide" icon="book" href="https://zed.dev/docs/ai/agent-panel">
    Learn more about Zed's agent panel
  </Card>

  <Card title="Agent Client Protocol" icon="network-wired" href="https://agentclientprotocol.com">
    Understand the ACP specification
  </Card>

  <Card title="Qwen Code Discussions" icon="comments" href="https://github.com/QwenLM/qwen-code/discussions">
    Join the community discussion
  </Card>

  <Card title="Zed Community" icon="users" href="https://zed.dev/community">
    Connect with other Zed users
  </Card>
</CardGroup>

## Next Steps

* Explore [Qwen Code CLI features](/users/overview)
* Learn about [configuration options](/users/configuration/settings)
* Try the [VS Code extension](/ide-integration/vscode) for a different workflow
* Check out [JetBrains integration](/ide-integration/jetbrains) for IntelliJ IDEs