Qwen Code native reference
Start with the Qwen Code setup.
Native mappings
Rules
- Project-wide rules go into
QWEN.md.scoperules go into<scope>/QWEN.md. - A rule with
globsorpathsand noscopegoes to.qwen/rules/<name>.mdwith apaths:list. Qwen leaves it out of the prompt until a tool reads or edits a matching file. alwaysApply: truekeeps a rule inQWEN.md.- See scoped context for the limits.
Agents
- Agents get YAML frontmatter and a prompt body.
- Portable tool names map to Qwen names. Use
x-qwen.toolsfor an explicit native list. readonly: truegivesdisallowedTools: [write_file, edit, notebook_edit]. The agent cannot write files, but shell stays allowed. An explicitx-qwen.disallowedToolswins.- Import reads that exact list back as
readonly: trueand keeps any other blocklist underx-qwen. - Native fields such as
approvalModeand record-valuedmcpServersbelong underx-qwen.
Skills
- Bundled files are kept.
- Qwen Code also reads
.agents/skills/. Its own.qwen/skills/wins a same-name clash. disable-model-invocation,user-invocable, andpaths(always a list) are written toSKILL.mdas Qwen reads them, unless another target writes the same skills folder.allowed-toolsis not written, since Qwen's ownallowedToolsgrants permissions.- Set
x-qwen.modelon a skill to select its native model. The shared skillmodelfield is not promoted.
Commands
- Markdown with optional
descriptionfrontmatter. - Qwen interprets
{{args}},!{shell}, and@{path}in bodies. Sync keeps that text as written. - Nested command paths become colon-separated names. A command named
git:commitis written as.qwen/commands/git/commit.md, on Windows too. - On Windows, a target that writes such a name as one file refuses it. See path semantics.
MCP
Servers share settings.json under mcpServers. See the native MCP reference.
- Stdio:
command,args,env, optionalcwd. HTTP:httpUrl. SSE:url. - MCP timeouts are milliseconds.
disabled: trueservers are omitted, because Qwen ignores that per-server field.- A same-name server in existing or inherited configuration can still load. Use native
mcp.excludedto block it. - Environment placeholders stay literal until Qwen resolves them.
Hooks
Hooks share settings.json under hooks.
- Portable
on,match, anddecision: stdoutmap to Qwen events, tool names, and blocking decisions. - Spec timeouts are seconds. Qwen reads a command hook timeout of 1000 or more as milliseconds. So sync multiplies a spec timeout of 1000 seconds or more by 1000 (
1200becomes1200000), capped at 2147483647 ms (about 24.8 days, the longest delay Qwen can time). Lower values stay as they are. x-qwen.timeoutand raw native handler groups are written as given, in Qwen's units.- Sync quotes portable arguments into the shell command, because Qwen has no
argsfield. - Portable hooks that exit 2 block pre-tool, prompt-submit, and stop events. After-tool and after-edit stop further execution. Session-start and session-end keep their native behavior.
Native FileChanged hooks (Qwen Code 0.27.0):
- They watch the literal filenames in
matcher, separated by|, in the working folder. - They run only in local, non-managed sessions.
- A pattern only filters paths that are already watched. Add more through
watchPaths. - A
SessionStartorFileChangedhook that runs synchronously and succeeds can returnhookSpecificOutput.watchPaths, with its own event name inhookEventName. - A list of absolute paths replaces the earlier list. An empty list clears it.
- Filenames named in
matcherstay watched either way. - Project import keeps native command, HTTP, and prompt handlers and their metadata.
Settings
See Qwen settings.
- Portable
modelbecomesmodel.name. Permission lists becomepermissions.allow,permissions.ask,permissions.deny. - Settings
effortbecomesmodel.reasoningEffort(Qwen Code 0.28.0). It acceptslow,medium,high,xhigh, andmax; each provider maps the value to what the active model supports. x-qwen.model.reasoningEffortoverrides the portable value.x-qwenkeys keep their native spelling.- Native
x-qwen.mcpServersrecords override portable servers with the same name. - Native and portable hook entries are combined.
- Sync keeps unrelated settings, including the active
disableAllHooks. - Legacy
hooks.enabled,hooks.disabled, andhooks.notificationsmetadata is kept but does not disable hooks in this release.
Global configuration
- Portable voice settings write
general.voice.enabled,general.voice.mode, andgeneral.voice.language. Choose a nativevoiceModelbefore using dictation. agnostic-ai sync --global -t qwenwrites instructions, agents, skills, MCP, hooks, and settings under~/.qwen/.approvalsset toreviewfor Qwen Code writestools.approvalMode: "auto"to~/.qwen/settings.json, unless a settings spec setsx-qwen.tools.approvalMode. See review through the tool's own reviewer.QWEN_HOMEreplaces that whole directory.QWEN_RUNTIME_DIRmoves runtime state, not configuration.agnostic-ai import --global qwenreads the user model, effort, permission lists, and MCP servers.- See global configuration.
Config keys
| Key | Default |
|---|---|
outputs.qwen.rules-file | unset, uses instruction files |
outputs.qwen.rules-dir | .qwen/rules |
outputs.qwen.agents-dir | .qwen/agents |
outputs.qwen.skills-dir | .qwen/skills |
outputs.qwen.commands-dir | .qwen/commands |
outputs.qwen.conf-file | .qwen/settings.json |
outputs.qwen.mcp-file | .qwen/settings.json |
outputs.qwen.hooks-file | .qwen/settings.json |
outputs.qwen.ignore-file | .qwenignore |
Root instructions use the shared entry-point configuration. Changing a path does not change where Qwen looks. Keep overrides aligned with your native configuration.
Import
agnostic-ai import qwen
agnostic-ai lint
agnostic-ai sync -t qwen
agnostic-ai sync --check -t qwen
Import reads:
- Root and scoped instructions.
- Rule files directly under
.qwen/rules/. - Agents.
- Skill folders and resources from
.qwen/skills/and.agents/skills/(.qwen/skills/wins a same-name clash). - Markdown and legacy TOML commands. Imported legacy commands emit as Markdown.
.qwenignore.- Settings, hooks, and MCP servers in
.qwen/settings.json.
Details:
- Supported settings effort becomes portable
effort. A value shadowed by another settings spec stays underx-qwen.model.reasoningEffort. - A rule file's
paths:becomes portableglobs. - A rule file without
paths:is named by import. Sync moves that rule intoQWEN.md, so delete the original file. - Rule files in subfolders are named and skipped. Import stops when a rule file shares its name with a rule in
QWEN.md. - Native fields stay under
x-qwen. HTTPhttpUrlbecomestype: http. SSEurlbecomestype: sse. - Import rejects credentials in retained agent and skill headers, hooks, and settings.
- Settings can refer to environment variables with
$NAMEor${NAME}. Qwen does not expand those in an agent's or skill's credential fields, so import rejects them there.