Skip to content

Qwen Code CLI Agent

Complete guide to using the Qwen Code CLI agent.

Overview

The Qwen Code CLI agent is the most powerful option, using the official qwen-code CLI tool for advanced AI processing.

Features

  • ✅ Full integration with Qwen3-Coder models
  • ✅ Automatic TODO planning
  • ✅ Built-in tools: web search, git, github, shell
  • ✅ MCP integration: Automatic access to Docling document processing (PDF, DOCX, images, OCR)
  • ✅ Free tier: 2000 requests/day
  • ✅ Vision model support
  • ✅ DEBUG трейсинг выполнения CLI - Подробнее →

Installation

1. Install Node.js 20+

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# macOS
brew install node@20

# Windows
# Download from nodejs.org

2. Install Qwen Code CLI

npm install -g @qwen-code/qwen-code@latest

Docker: The bot image already includes Node.js 20 and the Qwen CLI. You only need to authenticate inside the running container once (persisted via ~/.qwen bind mount):

docker exec -it tg-note-bot bash -lc "qwen"

3. Verify Installation

qwen --version

4. Authenticate

qwen

Follow the prompts to authenticate via qwen.ai.

5. Configure Approval Mode (IMPORTANT!)

⚠️ КРИТИЧЕСКИ ВАЖНО: Для корректной работы CLI с ботом необходимо настроить режим одобрения инструментов:

qwen
/approval-mode yolo --project

Docker one-liners for non-interactive application:

docker exec -it tg-note-bot bash -lc "qwen <<<'/approval-mode yolo --project'"

Зачем это нужно?

  • CLI по умолчанию требует ручного подтверждения для каждого действия
  • Бот работает в автономном режиме и не может взаимодействовать с CLI интерактивно
  • Режим yolo автоматически одобряет все операции агента

⚠️ Внимание! Использование режима yolo - на ваш страх и риск. Агент получит полный доступ к файловым операциям и командам.

Доступные режимы одобрения:

  • plan - только анализ, без изменения файлов
  • default - требует подтверждения для редактирования файлов и команд
  • auto-edit - автоматически одобряет редактирование файлов
  • yolo - автоматически одобряет все операции (требуется для бота)

Области применения:

  • --session - только для текущей сессии
  • --project - для текущего проекта (рекомендуется)
  • --user - для всех проектов пользователя

Рекомендуется ознакомиться с официальной документацией qwen-code-cli для полного понимания возможностей и ограничений.

Configuration

Update config.yaml:

AGENT_TYPE: "qwen_code_cli"
AGENT_QWEN_CLI_PATH: "qwen"
AGENT_TIMEOUT: 300
AGENT_ENABLE_WEB_SEARCH: true
AGENT_ENABLE_GIT: true
AGENT_ENABLE_GITHUB: true
AGENT_ENABLE_SHELL: false

Tip: The CLI path is configurable via AGENT_QWEN_CLI_PATH and defaults to qwen. Ensure qwen --version succeeds on your system before enabling this agent.

MCP Integration

The Qwen CLI automatically discovers and connects to MCP servers configured in ~/.qwen/settings.json. This configuration is automatically generated by the MCP Hub on startup.

Available MCP Tools:

  • Docling MCP: Document processing (PDF, DOCX, images, OCR)
  • Automatically configured when Docling is enabled
  • Accessible via convert_document_from_content tool

  • Supports base64 file transfer (no shared filesystem needed)

  • MCP Hub: Built-in memory tools and registry

  • store_memory, retrieve_memory, list_categories
  • Per-user storage isolation

Configuration Location:

The MCP configuration is automatically generated in ~/.qwen/settings.json by the MCP Hub service. In Docker mode, this file is persisted via the ~/.qwen bind mount.

Example MCP Configuration:

{
  "mcpServers": {
    "mcp-hub": {
      "url": "http://mcp-hub:8765/sse",
      "timeout": 99999,
      "trust": true
    },
    "docling": {
      "url": "http://docling-mcp:8077/sse",
      "timeout": 99999,
      "trust": true
    }
  },
  "allowMCPServers": ["mcp-hub", "docling"]
}

How It Works:

  1. MCP Hub starts and generates ~/.qwen/settings.json
  2. Qwen CLI reads the configuration on startup
  3. CLI automatically connects to configured MCP servers
  4. All MCP tools become available in CLI sessions

For more details, see MCP Architecture and File Format Recognition.

How It Works

  1. Message received
  2. Agent prepares prompt
  3. CLI working directory set to user's knowledge base path
  4. Calls qwen CLI in KB directory
  5. Qwen creates TODO plan
  6. Executes plan with tools (files created in correct KB location)
  7. Returns structured markdown
  8. Saved to KB

Important: The CLI automatically runs inside your knowledge base directory (knowledge_bases/your-kb-name/). This ensures that any files created by the agent are saved to the correct location in your knowledge base structure.

Source Citations (Ссылки на источники)

NEW REQUIREMENT (v4+): The Qwen CLI agent now ALWAYS includes source references in created documents:

  • Inline citations - Links directly in text next to specific facts/concepts
  • Format: Согласно [название источника](URL), ... or ... как описано в [источнике](URL)

  • Example: Модель GPT-4 использует архитектуру трансформера ([OpenAI Technical Report](https://openai.com/research/gpt-4))

  • "Источники" section - Mandatory section at the end of EVERY created file

  • Lists all sources with URLs and brief descriptions

  • Format: 

    ## Источники

1. [Название источника](URL) - краткое описание
2. [Другой источник](URL) - краткое описание

  • Additional materials - Optional "См. также" section for supplementary resources

This ensures all knowledge base entries maintain proper attribution and traceability.

Connection Descriptions (Связи)

  • Agent must add links only to EXISTING KB files (not those created in the same run).
  • Each link MUST include a meaningful description (1–2 sentences) explaining the nature of the connection: similarity/difference, dependency, part-whole, alternative, sequence, overlapping concepts.
  • Avoid generic placeholders like “Связанная тема”.

Troubleshooting

Files Created in Wrong Location

Проблема: CLI создаёт файлы в корне проекта, а не в knowledge_bases/your-kb-name/

Решение: Это было исправлено в последней версии. Бот автоматически устанавливает рабочую директорию CLI в путь вашей базы знаний перед каждым запросом. Убедитесь, что вы используете актуальную версию бота.

Как это работает:

  • При обработке сообщения бот определяет путь к вашей базе знаний
  • Перед вызовом qwen CLI устанавливается working_directory в этот путь
  • Все файлы, созданные агентом, попадают в правильную структуру KB

CLI Requires Manual Approval

Проблема: CLI требует подтверждения каждого действия, бот зависает

Решение: Настройте режим yolo как описано в разделе установки:

qwen
/approval-mode yolo --project

Почему это необходимо:

  • CLI по умолчанию работает в интерактивном режиме
  • Бот не может взаимодействовать с CLI в интерактивном режиме
  • Режим yolo отключает все запросы подтверждения

Authentication Issues

Проблема: CLI не может авторизоваться

Решение:

  1. Запустите qwen в терминале
  2. Следуйте инструкциям для OAuth авторизации через qwen.ai
  3. Либо настройте OpenAI-совместимый API:
export OPENAI_API_KEY="your-key"
export OPENAI_BASE_URL="your-url"

CLI Not Found

Проблема: qwen: command not found

Решение:

  1. Проверьте установку: npm list -g @qwen-code/qwen-code
  2. Переустановите: npm install -g @qwen-code/qwen-code@latest
  3. Проверьте PATH: echo $PATH
  4. Если используете nvm: убедитесь, что Node.js активирован

See Also