Agent lacks built-in knowledge of its own config system — confuses Qwen/Claude/Gemini permission & MCP syntax

[zpoint]

Problem

Qwen Code's agent lacks built-in knowledge of its own configuration system. When users ask the agent to configure fine-grained permissions or MCP servers, the agent cannot help — it doesn't know its own config schema, syntax, or capabilities. Users are forced to clone the repo and grep through source code (e.g., shell-utils.ts) to discover the correct configuration syntax.

The agent should be self-aware of its own configuration system and able to guide users through it without external research.

Core Issue: Agent Has No Self-Knowledge of Config

The agent cannot answer basic questions about itself:

User Question	What Agent Should Do	What Agent Actually Does
"Allow all bash except rm"	Provide correct tools.exclude syntax	Hallucinates Claude/Gemini syntax, fails
"Add an MCP server"	Guide through mcpServers config in settings.json	Searches web, finds wrong information
"What permissions can I configure?"	List available permission options	Makes up non-existent fields
"Where is my config file?"	Answer ~/.qwen/settings.json	Guesses ~/.config/qwen/ or other wrong paths

This is not a documentation problem — it's a missing capability. The agent needs to have its own configuration knowledge built-in, so it can self-serve config questions at runtime without users having to reverse-engineer source code.

Why This Matters

1. Self-service is broken — Users expect the agent to know how to configure itself. Every config question becomes a multi-hour session of cloning the repo and searching source code.
2. Wrong answers are worse than no answer — The agent confidently suggests Claude Code or Gemini CLI syntax that silently fails or errors out in Qwen Code (see detailed comparison below).
3. Migration barrier — Users coming from Claude Code or Gemini CLI hit a wall immediately when their existing config patterns don't work and the agent can't help.
4. Security risk — Users who can't figure out fine-grained permissions may give up and use overly permissive modes ("approvalMode": "yolo").

Detailed Configuration Comparison: What the Agent Confuses

1. Permission Systems Are Completely Different

Claude Code (~/.claude/settings.json):

{
  "permissions": {
    "allow": ["Bash", "Edit", "Write", "Read", "mcp__playwright__*"],
    "deny": [],
    "additionalDirectories": ["/"]
  }
}

• Flat allow/deny arrays of tool names
• Tools named by display name: Bash, Edit, Write, Read, Glob, Grep
• MCP tools prefixed: mcp__serverName__toolName, supports wildcards (mcp__playwright__*)

Gemini CLI (~/.gemini/policies/my-rules.toml):

[[rule]]
toolName = "run_shell_command"
commandPrefix = "rm"
decision = "ask_user"
priority = 200

[[rule]]
toolName = "run_shell_command"
decision = "allow"
priority = 100

• TOML-based rule engine with priority ordering
• Tools named differently: run_shell_command, replace, write_file, activate_skill
• Decisions: "allow", "ask_user", "deny"
• Higher priority rules evaluated first
• Also has ~/.gemini/settings.json with "general": {"defaultApprovalMode": "default"}

Qwen Code (~/.qwen/settings.json):

{
  "tools": {
    "approvalMode": "default",
    "core": ["run_shell_command"],
    "allowed": ["run_shell_command(git)", "run_shell_command(npm test)"],
    "exclude": ["run_shell_command(rm -rf)", "run_shell_command(sudo)"]
  }
}

• tools.core — Allowlist of available tools (restricts to only these)
• tools.allowed — Tools that bypass confirmation dialog
• tools.exclude — Tools to deny, supports command-specific patterns like run_shell_command(rm)
• tools.approvalMode — "plan" | "default" | "auto-edit" | "yolo"
• tools.autoAccept — Auto-accept safe (read-only) operations

The agent regularly suggests Claude's permissions.allow/permissions.deny or Gemini's defaultApprovalMode — none of which exist in Qwen Code.

2. MCP Server Configuration Differs

Claude Code (~/.claude.json or ~/.claude/.mcp.json):

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {}
    },
    "buildkite": {
      "type": "http",
      "url": "https://mcp.buildkite.com/mcp"
    }
  }
}

• Requires explicit "type": "stdio" or "type": "http"
• Per-project MCP in .claude.json under projects[path].mcpServers
• Tool permissions via permissions.allow: "mcp__serverName__*"

Gemini CLI — MCP support is limited/not a primary config surface.

Qwen Code (~/.qwen/settings.json):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "web-server": {
      "url": "https://mcp-server.example.com/sse"
    },
    "http-server": {
      "httpUrl": "https://api.example.com/mcp",
      "headers": {"Authorization": "Bearer token"}
    }
  },
  "mcp": {
    "allowed": ["playwright"],
    "excluded": ["untrusted-server"]
  }
}

• Transport type inferred from fields (command → stdio, url → SSE, httpUrl → HTTP, tcp → WebSocket)
• No explicit "type" field needed (unlike Claude Code)
• Per-server tool filtering: includeTools / excludeTools arrays
• Global MCP allow/exclude via separate mcp key (not inside mcpServers)
• Supports timeout, trust, description, oauth per server
• Environment variable interpolation: "env": {"KEY": "$MY_ENV_VAR"}

3. Config File Locations Are Different

	Claude Code	Gemini CLI	Qwen Code
User config	~/.claude/settings.json	~/.gemini/settings.json	~/.qwen/settings.json
Project config	.claude.json	.gemini-config/settings.json	.qwen/settings.json
Permissions	In settings.json under permissions	~/.gemini/policies/my-rules.toml	In settings.json under tools
MCP servers	~/.claude/.mcp.json or .claude.json	N/A	In settings.json under mcpServers
Context file	CLAUDE.md	GEMINI.md	QWEN.md
System config	N/A	N/A	macOS: /Library/Application Support/QwenCode/settings.json
Config format	JSON	JSON + TOML (policies)	JSON (with comments, env var interpolation)

4. Config Precedence Is Different

Claude Code: settings.local.json > settings.json > project .claude.json > defaults

Gemini CLI: Project .gemini-config/ > ~/.gemini/ > defaults

Qwen Code: CLI args > env vars > system settings > project .qwen/settings.json > user ~/.qwen/settings.json > system defaults > hardcoded defaults

What the Agent Should Know

The agent should have built-in knowledge of at minimum:

Permission Config

// ~/.qwen/settings.json
{
  "tools": {
    "approvalMode": "default",          // "plan" | "default" | "auto-edit" | "yolo"
    "core": ["run_shell_command"],       // Restricts to only these tools
    "allowed": ["run_shell_command(git)"], // Bypass confirmation for these
    "exclude": ["run_shell_command(rm)"], // Block these tools/commands
    "autoAccept": false,                 // Auto-accept read-only operations
    "sandbox": true                      // Enable sandboxed execution
  }
}

MCP Server Config

// ~/.qwen/settings.json
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "env": {"API_KEY": "$MY_API_KEY"},
      "timeout": 5000,
      "includeTools": ["tool1"],
      "excludeTools": ["tool2"]
    }
  },
  "mcp": {
    "allowed": ["my-server"],
    "excluded": ["untrusted-server"]
  }
}

Full Config Schema (top-level keys)

mcpServers, modelProviders, env, general, output, ui, ide, privacy, model, context, tools, mcp, security, advanced, webSearch, experimental, telemetry

Config File Locations & Precedence

• User: ~/.qwen/settings.json
• Project: .qwen/settings.json
• System: /Library/Application Support/QwenCode/settings.json (macOS)
• Supports JSON with comments, environment variable interpolation ($VAR / ${VAR})

Suggested Approach

1. Embed config schema awareness — The agent should have access to the valid settings.json schema (tool names, permission patterns, MCP config structure) either through system prompt context, a built-in skill/command, or a self-referencing config spec.
2. Intercept config-related questions — When a user asks about permissions, MCP, or settings, the agent should use its built-in knowledge first, not web search or hallucination.
3. Detect and translate cross-tool syntax — When the agent detects Claude Code patterns (permissions.allow, permissions.deny) or Gemini CLI patterns (defaultApprovalMode, TOML rules), it should recognize the mistake and provide the equivalent Qwen Code syntax.
4. Expose config via /config or /settings command — A built-in command that dumps the current effective config or shows available options would eliminate the need for source code diving entirely.

Related Roadmap

• OnBoarding (P1, Planned)
• Permission (P1, Planned)

[zpoint]

Meta note on this issue's own editing history:

Ironically, this issue itself demonstrates the problem. The first ~5 edits to this issue body were done using Qwen Code's agent — after many rounds of prompting, the result still didn't precisely capture the core problem. The expression was arguably worse than what I would have written manually.

The latest 2 edits were done using Claude CLI, which nailed the structure, detail level, and emphasis in far fewer iterations — reading through the actual config systems of all three tools (Qwen, Claude, Gemini) and producing a precise side-by-side comparison with real syntax examples.

This is part of why I still rely on Claude over Qwen for non-trivial tasks: the agent's ability to understand intent, self-research (reading source code, config files), and produce well-structured output on the first or second try matters a lot for productivity. Qwen Code has potential, but gaps like the one described in this issue (lack of self-knowledge) compound into a noticeably weaker experience for power users.

[LaZzyMan]

@zpoint Thank you for your feedback. This is a very meaningful idea, and we've noticed that many users are struggling with complex configuration options, especially when these options are the same as or similar to those in other products like Claude but differ in their configuration. Neither users nor LLMs can quickly and correctly configure them. Therefore, we plan to develop an official extension that uses custom commands and skills to help LLMs fully master qwen-code configuration, thus helping users achieve their goals faster. I will notify you as soon as the extension is released.

[hs-ye]

Another +1 to this - really annoying to have qwen not be aware of itself and constantly suggesting Claude/Gemini CLI options. I am literally doing the same thing where I have the Qwen repo loaded inside my working repo and constantly pointing itself to its own docs