vrr/qwen-code: mirror of https://github.com/QwenLM/qwen-code?tab=readme-ov-file#-free-options-available

mirror of https://github.com/QwenLM/qwen-code.git synced 2026-05-19 16:28:28 +00:00

mirror of https://github.com/QwenLM/qwen-code?tab=readme-ov-file#-free-options-available

Find a file

Shaojin Wen 84ecb5b8a3 feat(cli): add --json-schema for structured output in headless mode (#3598 ) * feat(cli): add --json-schema for structured output in headless mode Registers a synthetic `structured_output` tool whose parameter schema IS the user-supplied JSON Schema. In headless mode (`qwen -p`), the first successful call terminates the session and exposes the validated payload via the result message's `structured_result` field. Invalid schemas are rejected at CLI parse time via a new strict Ajv compile helper so they can't silently no-op at runtime. * fix(cli): honour "first structured_output call ends session" + reject non-object root schemas Two review fixes for the `--json-schema` feature: 1. `runNonInteractive` now breaks out of the tool-call loop as soon as the first successful `structured_output` invocation is captured, rather than continuing to execute any trailing tool calls the model emitted in the same turn. This restores the documented single-shot contract and prevents side-effecting tools from running after the final answer has already been accepted. 2. `resolveJsonSchemaArg` rejects schemas whose root `type` is anything other than "object" (or a type array including "object"). Function- calling APIs require tool arguments to be JSON objects, so a schema like `{"type": "array"}` would have registered an unusable synthetic tool the model could never satisfy. Absent `type` and `type: "object"` remain accepted. Adds tests for both paths and updates the existing Ajv-compile test to exercise that path without tripping the new root-type guard first. * fix(cli): also reject root anyOf/oneOf schemas whose branches can't accept objects Addresses a review follow-up: the previous root-object check only inspected the top-level `type` keyword, so a schema like `{"anyOf":[{"type":"array"},{"type":"string"}]}` slipped through even though none of its branches can ever validate the object-shaped arguments that function-calling APIs send. Replace the single `type` check with `schemaRootAcceptsObject`, which recursively walks root-level anyOf/oneOf branches and requires at least one to accept objects. Absent `type`, `type: "object"`, `type: ["object", ...]`, and mixed anyOf branches where one accepts object all still pass. `allOf` is left to Ajv's runtime behaviour — guessing intent across contradictory allOf branches at parse time is fragile. * fix(cli): propagate exitCode from --json-schema failure path + tests Address two PR-3598 review findings: 1. gemini.tsx unconditionally called process.exit(0) after runNonInteractive/runNonInteractiveStreamJson, clobbering the process.exitCode = 1 set by nonInteractiveCli.ts when the model emits plain text instead of the structured_output tool. Switch both call sites to process.exit(process.exitCode ?? 0) so CI can detect the failure via the exit code. 2. nonInteractiveCli.test.ts: strengthen the structured-output success path to assert registry.abortAll() is called and that the stdout result envelope carries the JSON-stringified args under `result` plus the raw object under `structured_result`. Add a retry-path test that mocks executeToolCall to return an error on the first structured_output call, then verifies sendMessageStream is called a second time so the model can retry rather than the session terminating early. * fix(cli): suppress non-structured tool calls when structured_output is in the same turn When --json-schema is active and the model emits a batch like [write_file(...), structured_output(...)], the previous implementation ran the leading side-effecting tool before accepting the structured result, violating the "structured_output is the terminal contract" guarantee. The trailing-only break also let an invalid first structured_output fall through to subsequent tools before the retry turn. Pre-scan the batch: if a structured_output request is present, execute ONLY the first one and skip everything else (leading and trailing). This is consistent with the existing terminal-path semantics — the suppressed tool_use blocks lack a matching tool_result, the same way max-turns / cancellation leave the stream. Adds a test covering the reverse-order [side_effect, structured_output] case alongside the existing trailing-suppression and retry tests. * fix(cli): tighten --json-schema root validation per review feedback Three small holes flagged in the latest pass: 1. `schemaRootAcceptsObject` returned early when a root `type` keyword was present, ignoring sibling `anyOf`/`oneOf`. JSON Schema applies keywords at the same level conjunctively, so e.g. `{type:"object", anyOf:[{type:"string"}]}` is unsatisfiable for any value but used to pass. Now both `type` AND any sibling `anyOf`/`oneOf` must independently admit object. 2. The FatalConfigError text said "Every branch of a root anyOf/oneOf must be satisfiable by an object", but the actual logic only requires at least one branch (and tests still accept `anyOf:[object, string]`). Reworded to "at least one branch" so the message matches the behaviour. 3. `compileStrict` used `typeof schema !== 'object'` to gate input, which lets arrays through (`typeof [] === 'object'`). The contract says "schema must be a JSON object", so add an `Array.isArray` check so array input gets the intended error rather than a less helpful Ajv compile message. Tests cover the new rejection paths and the array case. * fix(cli): handle root $ref and allOf in --json-schema accept-object check `schemaRootAcceptsObject` previously only inspected `type`, `anyOf`, and `oneOf` at the root, so a couple of unsatisfiable shapes still slipped through: 1. `{"$ref":"#/$defs/Foo","$defs":{"Foo":{"type":"array"}}}` would be accepted because we don't follow $refs, but registers a synthetic tool whose params resolve to "array" — the model can never produce a valid object. Now reject any root $ref unless the user adds a sibling `type:"object"` as an explicit anchor. 2. `allOf` was deferred to Ajv runtime, but allOf is conjunctive at the same level as `type` / `anyOf` / `oneOf`, so an entry like `{"allOf":[{"type":"object"},{"type":"string"}]}` is unsatisfiable for any value. Walk it like the others, requiring every branch to admit object. Tests cover the new $ref-rejected / $ref+anchor-accepted paths and the allOf reject/accept paths. * fix(cli): explicit exit code from runNonInteractive + pair suppressed tool calls Three review threads on the structured-output flow: 1. The break that ends the for-loop on a successful structured_output call sat before the responseParts.push and modelOverride capture. SyntheticOutputTool currently returns neither, so it was safe today — but anyone wiring extra signals into the synthetic tool later would see them silently dropped. Move the break after both captures so the contract is explicit, not implicit. 2. The failure path used to set process.exitCode = 1 and return void, relying on global mutable state across an async boundary. Any cleanup task between runNonInteractive and process.exit could silently turn the structured-output failure into exit 0. Switch runNonInteractive to Promise<number>, return 0 / 1 directly from each function-level exit, and have gemini.tsx use the captured return value. 3. The pre-scan from the prior commit suppresses sibling tool calls when structured_output is in the same turn. On the retry path — when structured_output fails validation — the next-turn payload has tool_result for structured_output but no entry for the suppressed siblings, leaving the prior assistant turn's tool_use blocks unpaired. Anthropic and OpenAI both reject that batch shape, so the retry would surface as an opaque provider error. Synthesize a "skipped" functionResponse for every suppressed call so every tool_use in the prior assistant message has a matching tool_result. Tests cover the new retry-pairing contract and update the existing plain-text-failure test to assert on the return value rather than process.exitCode. * fix: address Copilot follow-up review on --json-schema scaffolding Five small but real findings flagged on the latest pass: 1. core/src/index.ts re-exported `SyntheticOutputTool` via `export type`, but it's a runtime class — that erased it from the emitted JS and would break value imports. Split into a value `export { ... }` and a `export type { StructuredOutputParams }`. 2. The structured-output success path returned without flushing `localQueue` notifications or finalising one-shot monitors. If a background task had already emitted `task_started`, exiting here could drop its paired `task_notification` and leave SDK consumers with unpaired lifecycle events. Mirror the regular terminal path's `flushQueuedNotificationsToSdk` + `finalizeOneShotMonitors` calls before `emitResult`. 3. `schemaRootAcceptsObject` ignored the `not` keyword, so `{not:{type:"object"}}` (which forbids every object value) slipped through. Add a best-effort `not` check that rejects when `not.type` directly excludes object. Deeper negated patterns still fall through to Ajv at runtime. 4. `compileStrict`'s JSDoc claimed it errored on "Ajv versions we can't support", but the function doesn't actually check Ajv versions. Reword to "malformed or uses unsupported draft/features for our Ajv configuration" so the contract matches the implementation. 5. The pre-scan suppressed sibling tool calls but only synthesised tool_result events for them on the retry path — the success path left those tool_use blocks unpaired in the emitted JSONL/stream-json event log. Move the synthesis after the for loop so it runs for both the success break and the validation-failure fall-through; the event log is now consistent regardless of which path the run takes. Tests cover the new \`not\`-rejection paths, the success-path tool_result synthesis, and the existing retry-pairing test still passes against the restructured emit ordering. * fix(cli): tighten --json-schema parse-time gate per Copilot review Two more shapes that used to slip through: 1. `schemaRootAcceptsObject` defaulted to true when no narrowing keyword was present, so root-value constraints like `{const: 1}` or `{enum: [1, 2]}` registered an unsatisfiable structured_output contract — the model could never produce a value matching the tool's parameter schema, and the run would loop on validation failures until max-turns. Reject `const` whose literal isn't an object, and `enum` whose members include no object. 2. The yargs check rejected `--json-schema` with `-i` and with no prompt, but not with `--input-format stream-json`. Stream-json keeps the process open waiting for protocol messages, so "terminate on the first valid structured_output call" silently drops everything queued after that point. Refuse the combination at parse time so the contradiction surfaces immediately. Tests cover the new const/enum reject and accept paths. * fix(cli): handle empty/boolean subschemas + allow stdin-only prompt Three more shapes flagged on the latest review pass: 1. `schemaRootAcceptsObject` treated an empty root `anyOf`/`oneOf` as "no constraint" (skipped when length === 0), but per JSON Schema an empty union is unsatisfiable — no value can match a member of the empty set. Reject those at parse time so users get a clear parse error instead of an opaque runtime never-validates loop. 2. JSON Schema (draft-06+) allows boolean subschemas anywhere a schema is accepted: `true` matches every value, `false` matches nothing. The `anyOf`/`oneOf`/`allOf` walks were rejecting booleans via the typeof-object guard, which incorrectly rejected `{anyOf:[true]}` and `{allOf:[true,{type:"object"}]}` while letting `{anyOf:[false]}` slip through. Replace the per-branch object guard with a `variantAcceptsObject` helper that treats `true` as accepting and `false` as rejecting, then recurses on object subschemas. 3. The yargs `.check` rejected `--json-schema` when no `-p` / positional prompt was given, but the headless CLI also reads the prompt from stdin (`cat prompt.txt \| qwen --json-schema '...'`) — a legit usage pattern that was being blocked. Drop the parse-time no-prompt rejection; the existing runtime "No input provided via stdin..." error in gemini.tsx still catches genuinely empty input. Tests cover the empty-union, all-`false`, mixed-boolean accept, and `false`-in-allOf reject paths. Live-verified against the bundled CLI: `echo "..." \| qwen --json-schema '...'` now reaches the model call, and the four schema edge cases all surface the expected error text or proceed past parse time. * docs(core): note SyntheticOutputTool as the value-export exception The block comment above the lazy-load type re-exports said tool classes "are now lazy-loaded and are not exported as values from the package root", but `SyntheticOutputTool` was just promoted to a runtime export in `62038527c` so the CLI's `--json-schema` flow can construct it from the package root. Document that exception inline so downstream consumers reading the comment don't get told the wrong story. * fix(cli): try every structured_output in a same-turn batch in order The pre-scan used to pick only the FIRST structured_output call from a turn and suppress everything else, even other structured_output calls. That created two avoidable failure modes: 1. `[structured_output(bad), structured_output(good)]` would attempt only the bad one, fail validation, and force a full retry turn. The model already produced a valid structured payload — we should try it before asking again. 2. The trailing structured_output's tool_result was synthesised with the "Skipped: structured_output was also requested in this turn..." message, which is misleading because that call WAS the structured output we should have tried. Filter `requestsToExecute` to ALL structured_output calls (in original order) when --json-schema is active, and let the existing loop break on the first success. Track an `executedCallIds` set, then synthesise tool_result + retry parts after the loop for every tool_use the model emitted that we never actually executed — covering both non-structured siblings (always suppressed) and any structured_output left over after the success break (only one terminal contract per turn). Reworded the synthesised "skipped" output to "this turn's structured_output contract took precedence" so it reads correctly regardless of whether the suppressed call was structured or not. Tests cover the multi-structured retry-free success path; the existing single-structured retry and trailing/leading suppression tests still pass against the updated emit ordering. * fix: address gpt-5.5 review on --json-schema (privacy + $ref + core-tools) Three findings, three changes: 1. Reject every root `$ref` in --json-schema, even with a sibling `type: "object"` anchor. Ajv applies `$ref` conjunctively with sibling keywords, so the previous "accept when type:object is present" carve-out was unsound: `{type:"object",$ref:"#/$defs/Foo", $defs:{Foo:{type:"array"}}}` parsed fine but no object value can satisfy both at runtime, leaving the model to loop until maxTurns. Updated docstring + test cases (replaced the accept-with-anchor case with a reject case for both anchored and well-formed $ref shapes — users wanting composition should inline at the root). 2. Redact `function_args` for structured_output in ToolCallEvent. The args ARE the user's structured payload (already emitted via stdout `result` / `structured_result`); recording them again as ordinary tool-call function_args duplicates that data into OTLP exports, QwenLogger, ui-telemetry, and the chat-recording UI event mirror — surfaces that can leak off-device. Replace with a stable `__redacted` placeholder so consumers still see the call happened (duration, success, decision metrics preserved) but the payload itself doesn't ride along. Two new uiTelemetry tests cover the redacted vs non-redacted paths. 3. Document and test that structured_output bypasses the --core-tools allowlist (same as agent / skill / exit_plan_mode / ask_user_question etc.). The synthetic tool only exists when --json-schema is set, so adding it to CORE_TOOLS would let `--core-tools read_file --json-schema X` silently drop the terminal contract and loop the model until maxTurns — bypass is intentional. Expanded the CORE_TOOLS docstring to enumerate the synthetic-tool exclusions and added a permission-manager test mirroring the pattern used for agent / skill / exit_plan_mode. * fix(cli): apply structured_output terminal handling to drain turns The synthetic structured_output tool is registered for the entire headless session, so it can be invoked from EITHER the main assistant-turn loop OR from a drain turn (queued cron-job / notification reply). The drain path (drainOneItem) was treating it like any other tool: execute, append the response back into itemMessages, keep going. The submitted args were never captured and no structured_result envelope was emitted, so a run that legitimately satisfied --json-schema mid-drain ended up failing the contract with "Model produced plain text..." anyway. Apply the same terminal handling to drain turns: - Hoist `structuredSubmission` to session scope so both paths write to one variable. - In `drainOneItem`, run the same pre-scan: when --json-schema is active and structured_output is in the batch, execute every structured_output in original order until one succeeds; suppress every non-structured sibling. Synthesise tool_results for any unexecuted tool_use the model emitted, mirroring the main path. - On capture, return early from drainOneItem so the drained item's inner while loop stops. - `drainLocalQueue` short-circuits when a captured submission is in flight, so subsequent queued items don't run. - The cron `checkCronDone` watches the same flag and stops the scheduler immediately on capture, releasing the surrounding `await new Promise(...)`. - The final holdback loop bails out on capture so monitor lifecycle doesn't extend past the structured submission. - After the holdback, before the existing failure / regular-success emit, emit the structured success envelope and return 0. Adds a focused unit test that drives the drain path end-to-end via a synchronously-fired monitor notification: main turn produces plain text, the drain reply calls structured_output, and the test asserts exit 0 + structured_result populated + no "Model produced plain text..." error. * fix(cli): address gpt-5.5 review follow-ups on --json-schema scaffolding Six review findings, six small fixes: 1. Nested $ref incorrectly rejected. `schemaRootAcceptsObject` recurses into anyOf/oneOf/allOf branches and used to apply the root-only $ref rejection at every level, blocking common composition shapes like `{anyOf:[{$ref:"#/$defs/Foo"},{type:"string"}]}`. Add an `isRoot=true` parameter; non-root recursion treats `$ref` as opaque and defers to Ajv at runtime. Tests cover nested refs in anyOf / oneOf / allOf. 2. Inaccurate package-root export comment. `core/src/index.ts` claimed `SyntheticOutputTool` was exported as a runtime value for the CLI's --json-schema flow, but the only construction is inside `Config.registerLazy` via a relative dynamic import — no value consumer reaches into `@qwen-code/qwen-code-core`. Revert to a type-only re-export so `SyntheticOutputTool` lines up with every other lazy-loaded tool class. 3. Unused constructor parameter. `SyntheticOutputTool` took `(_config: Config, schema)` but never read `_config`. Drop the parameter (and the corresponding pass-through at the registration call site) so readers don't wonder why a Config is being threaded through. 4. Tool description claimed "exactly once". The retry path explicitly tolerates multiple calls until one validates, so "Call this tool exactly once" is misleading to a model that tried twice. Reword to "Call this tool to deliver the final result; the first call with valid arguments ends the session" so the description matches the actual contract. 5. Asymmetric shutdown on the structured-output success path. The regular terminal path waits in a holdback loop until `hasUnfinalizedTasks()` is false; the structured-output path used to call `abortAll()` and flush immediately, dropping the matching `task_notification` for any agent whose natural handler hadn't yet enqueued it. Add a bounded holdback (capped at 500ms via STRUCTURED_SHUTDOWN_HOLDBACK_MS) — long enough for typical abort callbacks to enqueue, short enough that a hung agent can't block exit. 6. gemini.tsx exit-code asymmetry. `runNonInteractive` returns an explicit exit code, but `runNonInteractiveStreamJson` still reads `process.exitCode` after `runExitCleanup`. Currently safe because the yargs `.check` rejects --json-schema with stream-json input, but a future stream-json equivalent of structured output would need to plumb the exit code through the return value too. Document this in a comment so the constraint is visible at the call site. Plus: strengthen `synthesises tool_result for suppressed sibling calls when structured_output fails validation` to assert the failed structured_output's `functionResponse.response` carries the actual validation error string ("args invalid"), not the synthesised "Skipped:" prose — a regression that overwrote it would otherwise slip past the existing pairing assertion. * fix(cli): close --json-schema gaps surfaced in self-audit + review Five fixes layered onto the same robustness pass over the `--json-schema` flow: 1. bare-mode registration (`packages/core/src/config/config.ts`): `qwen --bare --json-schema X -p "..."` previously skipped the synthetic `structured_output` registration entirely (the registration block lives below the bare-mode early-return), so the model had no way to terminate and the run looped to `maxSessionTurns`. Register the synthetic tool inside the bare branch too. 2. TTY interactive rejection (`packages/cli/src/gemini.tsx`): `qwen --json-schema X` on a TTY with no `-p` and no piped stdin routes to `isInteractive=true` (priority-3 fallback) and would launch the TUI, where `structured_output` is just an inert tool that prints "accepted" and lets the chat continue. Parse-time gating can't catch this (stdin isn't probed yet at parse time), so reject at runtime before the UI launches; runs `runExitCleanup` first so MCP subprocesses get torn down. 3. drain-turn structured-success flush (`packages/cli/src/nonInteractiveCli.ts`): when a drain turn captures `structured_output`, `drainLocalQueue` returns early, leaving any items the drain didn't process in `localQueue`. The prior emit path then ran `registry.abortAll()` + `emitResult` without flushing — stream-json consumers saw `task_started` events without paired `task_notification`. Add the same 500ms holdback + `flushQueuedNotificationsToSdk` the main-turn structured-success path uses, so the two paths agree. 4. ACP mutual-exclusion (`packages/cli/src/config/config.ts`): `--acp` runs an independent `runAcpAgent` turn loop that doesn't honour the synthetic-tool terminal contract, so `--acp --json-schema X` would register the tool but never terminate. Add a yargs `.check` rejection covering both `--acp` and the deprecated `--experimental-acp` alias. 5. max-turns + Skipped wording (review comments #3198579251/#3198579389/#3198579567 from yiliang114): - `handleMaxTurnsExceededError` now appends a `--json-schema`- specific hint pointing at the common stuck-run causes (structured_output denied by `permissions.deny` / `--exclude-tools`, unsatisfiable schema, prompt didn't instruct the model). Without this, three different failures all surfaced as the same generic "increase maxSessionTurns" line. - The synthesised "Skipped:" tool_result for suppressed sibling calls drops the trailing "Re-issue this call in a separate turn if needed." sentence on the success path, where the session terminates immediately and no consumer (model or SDK) can act on the advice. Retry path keeps the sentence — the model is about to receive these parts and may legitimately re-issue. Tests cover each fix: bare-mode registration order, ACP / experimental- acp rejection (×2), `--json-schema` hint in both text and JSON max-turns output, and explicit Skipped-text assertions on the success and retry paths. * fix: address 9 self-qreview comments on --json-schema PR Folds the 9 Suggestion-level comments from the previous /qreview pass into code/test fixes. Each one is a real issue, but mostly defensive — none changes the user-visible happy path. Refactors (F4/F5/F6 — code-quality) - F4 `nonInteractiveCli.ts`: extract `SUPPRESSED_OUTPUT_SUCCESS` / `SUPPRESSED_OUTPUT_RETRY` module-level constants and a `suppressedOutputBody(structuredCaptured)` helper. Both the main-turn and drain-turn synthesis sites previously had a 4-way duplicated ternary; future wording changes can no longer drift between them. - F5 `nonInteractiveCli.ts`: extract `emitStructuredSuccess()` closure inside `runNonInteractive`. The "abortAll → bounded holdback → flush → finalize one-shot monitors → emitResult → return 0" terminal block is now defined once and called from both the main-turn and drain-turn success paths. `finalizeOneShotMonitors` is idempotent (`oneShotMonitorsFinalized` guard) so the unconditional invocation is safe even when the drain-turn already finalized monitors before reaching the helper. - F6 `core/config/config.ts`: extract `registerStructuredOutputIfRequested()` helper. The synthetic-tool registration block is no longer duplicated between the bare-mode early-return branch and the regular registration branch. Tests (F7/F8/F9 — pin existing behaviour) - F7 `nonInteractiveCli.test.ts`: new test "holds back for in-flight background tasks before emitting structured success" — flips `hasUnfinalizedTasks: true → false` mid-poll so the holdback `while` body actually executes; spies on `abortAll` and asserts ordering of `task_notification` (must precede the result envelope) and the bounded elapsed-time cap. None of the existing structured-output success tests entered this branch (they all pinned `hasUnfinalizedTasks: () => false`). - F8 `gemini.test.tsx`: new test "rejects --json-schema when running in interactive (TUI) mode" — pins the TUI guard at gemini.tsx:694, asserting the headless-only stderr message AND the exact ordering `writeStderrLine → runExitCleanup → process.exit(1)` so a future refactor can't swap any of those steps. - F9 `cli/config.test.ts`: pin the two previously-untested `--json-schema` mutual-exclusion branches: `-i`/`--prompt-interactive` and `--input-format stream-json`. The stream-json check is load-bearing — `gemini.tsx:768` explicitly relies on this rejection holding (the parse-time `process.exitCode ?? 0` plumbing in the stream-json branch is only safe because `--json-schema` can't reach it). Behaviour fixes (F1/F2/F15 — privacy / security / correctness) - F1 `core/core/geminiChat.ts`: redact `functionCall.args` for `structured_output` tool calls before passing them to `chatRecordingService.recordAssistantTurn`. Without this, the user's structured payload (already emitted on stdout via `result` / `structured_result`) was persisted verbatim to `<projectDir>/chats/<sessionId>.jsonl` and re-fed into model context on `--continue` / `--resume`, contradicting the privacy contract documented next to the existing `ToolCallEvent` redaction. Each validation-failure retry was also recorded. Now mirrors the same `__redacted` placeholder. Helper extracted as `redactStructuredOutputArgsForRecording` so it's unit-testable. - F2 `cli/config/config.ts`: `resolveJsonSchemaArg`'s `@path` reader now (a) `fs.statSync`s first to refuse non-regular files (FIFOs, character devices like `/dev/zero`, directories), (b) caps the schema file at 1 MiB so an attacker who can influence the path through a wrapping process can't OOM the run, and (c) on JSON parse failure for `@path` source emits a generic "content of <path> is not valid JSON" instead of echoing the SyntaxError — Node ≥18's SyntaxError embeds a ~10-char file-content prefix in its message, which would otherwise ride out on stderr through any wrapper that surfaces the error. Inline (non-`@path`) JSON keeps the SyntaxError detail because the user is the source. - F15 `core/tools/tool-registry.ts`: `registerTool` now also checks the lazy `factories` map for name collisions, not just the eager `tools` map. An MCP server registering a tool whose name shadows a built-in lazy factory (e.g. `structured_output`) now gets auto-qualified to `mcp__<server>__<name>`, instead of silently winning the resolution. The synthetic structured-output tool no longer needs renaming for the corner case to be safe. Targeted suite (13 changed-area test files): 883/886 pass — 3 pre-existing skips. Typecheck clean on both packages. * fix: address 3 deepseek-v4-pro qreview comments on --json-schema PR Three Suggestion-level comments from the latest /qreview pass. N1 — `schemaRootAcceptsObject` skips `if/then/else` (cli/config/config.ts): A schema like `{"if": true, "then": {"type": "string"}}` passed parse-time gating but is unsatisfiable for object-typed tool args at runtime — the model would loop until maxSessionTurns. Add a best-effort check for the two decidable shapes: - `if: true` → object MUST match `then`; if `then` excludes objects (boolean `false`, non-object `type`, etc.), reject at parse time. - `if: false` → object MUST match `else` (`true` if absent); same check. Object-schema `if` cases stay runtime-decidable and fall through to Ajv, matching the existing best-effort scope on `not`. 4 new test cases pin both reject and accept paths. N2 — subagent registries register `structured_output` too (core/config/config.ts, core/tools/agent/agent.ts, core/agents/backends/InProcessBackend.ts): `createApprovalModeOverride` and `buildSubagentContextOverride` rebuild the tool registry on a `Object.create(base)` config. `this.jsonSchema` propagates through the prototype chain, so `registerStructuredOutputIfRequested` was firing for every subagent registry rebuild — but only `runNonInteractive`'s main / drain loops detect a successful `structured_output` call as terminal. A subagent that called the tool would receive "Session will end now" and then keep running because its own loop has no terminator: wasted tokens, no structured payload on stdout. Add a `forSubAgent: true` option to `createToolRegistry` (alongside the existing `skipDiscovery`), and propagate it from both subagent rebuild sites. The structured-output registration helper short-circuits when the flag is set. Bare-mode init does NOT set the flag, preserving the F6 fix where `qwen --bare --json-schema X -p "..."` still gets the synthetic tool. New test asserts the registry rebuilt with `forSubAgent: true` registers READ_FILE / EDIT / SHELL but NOT STRUCTURED_OUTPUT. N3 — TEXT-mode `structuredResult` not integration-tested (nonInteractiveCli.test.ts): All 8 existing `--json-schema` tests pin `OutputFormat.JSON` or `STREAM_JSON`. TEXT (the default for `qwen -p ...`) has no integration coverage, so a regression in `BaseJsonOutputAdapter.buildResultMessage`'s `hasStructured ? JSON.stringify(structuredResult) : resultText` contract or in `JsonOutputAdapter.emitResult`'s text-mode `process.stdout.write(`${result}\n`)` path would only surface to plain `qwen -p` users. New test pins TEXT-mode behaviour: stdout is exactly `${JSON.stringify(structuredArgs)}\n` — no JSON envelope, no event log. Targeted suite (13 spec files): 945/948 pass — 3 pre-existing skips. Typecheck clean on both packages. * fix(cli): narrow `not` rejection in schemaRootAcceptsObject Address Critical review comment #3216123734. `schemaRootAcceptsObject`'s `not` handler previously rejected any schema whose `not.type` included `"object"`, regardless of what other constraints `not` had. That's a false positive for schemas where the extra constraints NARROW what `not` excludes: { "not": { "type": "object", "required": ["error"] } } excludes only objects with an `error` key — the value `{}` satisfies this schema fine, but the old check rejected it at parse time with "--json-schema root must accept object-typed values". Fix: only reject when `not` is exactly `{type: ...}` with no narrowing siblings (the unambiguous "every object is excluded" case). When other keywords are present (`required`, `properties`, `minProperties`, `enum`, etc.), defer to Ajv at runtime — same best-effort scope as the sibling `anyOf`/`oneOf`/`allOf` deep-content checks. 3 new test cases pin the fixed accept paths (`{not:{type:"object",required:[...]}}`, `{not:{type:"object",properties:...,required:[...]}}`, `{not:{type:"object",minProperties:1}}`). The existing reject test for bare `{not:{type:"object"}}` still passes. * refactor: dedupe structured_output handling per qreview C1/C2/C3 Three Suggestion-level review comments from the latest /qreview pass. C1 — main-turn / drain-turn `structured_output` dispatch was duplicated ~120 lines (`nonInteractiveCli.ts`) The two batch-handling sites had near-identical bodies (filter `structured_output` from the batch when `--json-schema` is active → iterate with `executeToolCall` → write to `structuredSubmission` on first valid call → synthesise tool_result events for suppressed siblings). The only meaningful difference was which `modelOverride` binding the loop wrote to (session-scoped `modelOverride` for the main turn vs per-drain-item `itemModelOverride`). Extracted `processToolCallBatch(batchRequests, setModelOverride)` defined inside `runNonInteractive`: - Closes over session-scoped state (`adapter`, `config`, `abortController`, `options`, `structuredSubmission`, `executeToolCall`, `handleToolError`, `suppressedOutputBody`, the progress-handler helpers). - Takes the `modelOverride` setter as the one call-site-specific parameter so the main turn binds to the session var and the drain binds to the per-item var. Main-turn body went from ~120 lines to a single call; drain-turn body likewise. Net file shrink ~80 lines, no behaviour change. All 42 existing structured-output tests still pass (including `stops executing remaining tool calls...`, `tries multiple structured_output calls in the same turn...`, `synthesises tool_result for suppressed sibling calls...`, `captures structured_output emitted from a drain-turn (queued notification)`). C2 + C3 — `{__redacted: '…'}` placeholder duplicated in two files (`telemetry/types.ts` + `core/geminiChat.ts`) The `ToolCallEvent` constructor (for telemetry surfaces — OTLP / QwenLogger / ui-telemetry / chat-recording UI event mirror) and `redactStructuredOutputArgsForRecording` (for the on-disk chat-recording JSONL) each had a verbatim copy of: { __redacted: 'structured_output payload (see stdout result)' } If the redaction wording (or the `__redacted` key, or the placeholder text) ever drifted between the two surfaces, the privacy contract would be subtly broken on one and not the other. Hoisted to `STRUCTURED_OUTPUT_REDACTED_ARGS` exported from `packages/core/src/tools/syntheticOutput.ts`, imported in both sites. The constant carries its rationale in a JSDoc block so future readers see both call sites at once. Targeted suite (13 spec files): 961/964 pass — 3 pre-existing skips. Typecheck clean on both packages. --------- Co-authored-by: wenshao <wenshao@U-K7F6PQY3-2157.local>		2026-05-11 14:21:55 +08:00
.github	feat(installer): add standalone archive installation (#3776 )	2026-05-11 13:25:48 +08:00
.husky	Sync upstream Gemini-CLI v0.8.2 (#838 )	2025-10-23 09:27:04 +08:00
.qwen	chore: Add bilingual requirement to create-issue command (#3952 )	2026-05-08 17:51:22 +08:00
.vscode	Merge branch 'main' into feat/sandbox-config-improvements	2026-03-06 14:38:39 +08:00
docs	feat(cli): Ctrl+B promote keybind (#3831 PR-3 of 3) (#3969 )	2026-05-11 14:03:38 +08:00
docs-site	feat: update docs	2025-12-15 09:47:03 +08:00
eslint-rules	pre-release commit	2025-07-22 23:26:01 +08:00
integration-tests	test: stabilize main e2e flakes (#3992 )	2026-05-10 21:50:04 +08:00
packages	feat(cli): add --json-schema for structured output in headless mode (#3598 )	2026-05-11 14:21:55 +08:00
scripts	feat(installer): add standalone archive installation (#3776 )	2026-05-11 13:25:48 +08:00
.dockerignore	fix(cli): skip stdin read for ACP mode	2026-03-27 11:47:01 +00:00
.editorconfig	pre-release commit	2025-07-22 23:26:01 +08:00
.gitattributes	pre-release commit	2025-07-22 23:26:01 +08:00
.gitignore	feat(installer): add standalone archive installation (#3776 )	2026-05-11 13:25:48 +08:00
.npmrc	chore: remove google registry	2025-08-08 20:45:54 +08:00
.nvmrc	chore: Expand node version test matrix (#2700 )	2025-07-21 16:33:54 -07:00
.prettierignore	Merge branch 'main' into feat/add-vscode-settings-json-schema	2026-03-03 11:21:57 +08:00
.prettierrc.json	pre-release commit	2025-07-22 23:26:01 +08:00
.yamllint.yml	Sync upstream Gemini-CLI v0.8.2 (#838 )	2025-10-23 09:27:04 +08:00
AGENTS.md	feat(vscode): expose /skills as slash command with secondary picker (#2548 )	2026-04-24 23:28:53 +08:00
CONTRIBUTING.md	docs: add Screenshots/Video Demo section to PR template	2026-03-20 16:59:53 +08:00
Dockerfile	refactor: Extract web-templates package and unify build/pack workflow	2026-02-26 21:02:46 +08:00
esbuild.config.js	feat: add wasm build config (#2985 )	2026-04-09 14:21:00 +08:00
eslint.config.js	feat(cli): add API preconnect to reduce first-call latency (#3318 )	2026-04-27 06:54:55 +08:00
LICENSE	Sync upstream Gemini-CLI v0.8.2 (#838 )	2025-10-23 09:27:04 +08:00
Makefile	feat: update docs	2025-12-22 21:11:33 +08:00
package-lock.json	chore(release): v0.15.10 [skip ci]	2026-05-10 16:38:09 +08:00
package.json	feat(installer): add standalone archive installation (#3776 )	2026-05-11 13:25:48 +08:00
README.md	feat(installer): add standalone archive installation (#3776 )	2026-05-11 13:25:48 +08:00
SECURITY.md	fix: update security vulnerability reporting channel	2026-02-24 14:22:47 +08:00
tsconfig.json	# 🚀 Sync Gemini CLI v0.2.1 - Major Feature Update (#483 )	2025-09-01 14:48:55 +08:00
vitest.config.ts	test(channels): add comprehensive test suites for channel adapters	2026-03-27 15:26:39 +00:00

README.md

An open-source AI agent that lives in your terminal.

🎉 News

2026-04-15: Qwen OAuth free tier has been discontinued. To continue using Qwen Code, switch to Alibaba Cloud Coding Plan, OpenRouter, Fireworks AI, or bring your own API key. Run qwen auth to configure.
2026-04-13: Qwen OAuth free tier policy update: daily quota adjusted to 100 requests/day (from 1,000).
2026-04-02: Qwen3.6-Plus is now live! Get an API key from Alibaba Cloud ModelStudio to access it through the OpenAI-compatible API.
2026-02-16: Qwen3.5-Plus is now live!

Why Qwen Code?

Qwen Code is an open-source AI agent for the terminal, optimized for Qwen series models. It helps you understand large codebases, automate tedious work, and ship faster.

Multi-protocol, flexible providers: use OpenAI / Anthropic / Gemini-compatible APIs, Alibaba Cloud Coding Plan, OpenRouter, Fireworks AI, or bring your own API key.
Open-source, co-evolving: both the framework and the Qwen3-Coder model are open-source—and they ship and evolve together.
Agentic workflow, feature-rich: rich built-in tools (Skills, SubAgents) for a full agentic workflow and a Claude Code-like experience.
Terminal-first, IDE-friendly: built for developers who live in the command line, with optional integration for VS Code, Zed, and JetBrains IDEs.

Installation

Quick Install (Recommended)

The installer uses a standalone Qwen Code archive when one is available for your platform, so the default path does not require a preinstalled Node.js runtime. If a standalone archive is not available, it falls back to npm and then requires Node.js 20 or later with npm on PATH.

Linux / macOS

bash -c "$(curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh)"

Windows

Works in both Command Prompt and PowerShell:

powershell -Command "Invoke-WebRequest 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat' -OutFile (Join-Path $env:TEMP 'install-qwen.bat'); & (Join-Path $env:TEMP 'install-qwen.bat')"

Note

qwen is not immediately available on PATH. For offline installation, download a release archive such as qwen-code-linux-x64.tar.gz or qwen-code-win-x64.zip plus SHA256SUMS, then run the installer with --archive PATH.

Manual Installation

Prerequisites

Manual npm installation requires Node.js 20 or later. Download it from nodejs.org.

NPM

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

Homebrew (macOS, Linux)

brew install qwen-code

Quick Start

# Start Qwen Code (interactive)
qwen

# Then, in the session:
/help
/auth

On first use, you'll be prompted to sign in. You can run /auth anytime to switch authentication methods.

Example prompts:

What does this project do?
Explain the codebase structure.
Help me refactor this function.
Generate unit tests for this module.

Click to watch a demo video

🦞 Use Qwen Code for Coding Tasks in Claw

Copy the prompt below and paste it into your agent:

Use Qwen Code as a coding agent. First, fetch and read this skill reference:
https://raw.githubusercontent.com/QwenLM/qwen-code/refs/heads/main/.qwen/skills/qwen-code-claw/SKILL.md
Then follow the instructions inside to install, authenticate, and use Qwen Code via acpx for all coding tasks.

Authentication

Qwen Code supports the following authentication methods:

API Key (recommended): use an API key from Alibaba Cloud Model Studio (Beijing / intl) or any supported provider (OpenAI, Anthropic, Google GenAI, and other compatible endpoints).
Coding Plan: subscribe to the Alibaba Cloud Coding Plan (Beijing / intl) for a fixed monthly fee with higher quotas.

⚠️ Qwen OAuth was discontinued on April 15, 2026. If you were previously using Qwen OAuth, please switch to one of the methods above. Run qwen and then /auth to reconfigure.

API Key (recommended)

Use an API key to connect to Alibaba Cloud Model Studio or any supported provider. Supports multiple protocols:

OpenAI-compatible: Alibaba Cloud ModelStudio, ModelScope, OpenAI, OpenRouter, and other OpenAI-compatible providers
Anthropic: Claude models
Google GenAI: Gemini models

The recommended way to configure models and providers is by editing ~/.qwen/settings.json (create it if it doesn't exist). This file lets you define all available models, API keys, and default settings in one place.

Quick Setup in 3 Steps

Step 1: Create or edit ~/.qwen/settings.json

Here is a complete example:

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.6-plus",
        "name": "qwen3.6-plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "description": "Qwen3-Coder via Dashscope",
        "envKey": "DASHSCOPE_API_KEY"
      }
    ]
  },
  "env": {
    "DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3.6-plus"
  }
}

Step 2: Understand each field

Field	What it does
`modelProviders`	Declares which models are available and how to connect to them. Keys like `openai`, `anthropic`, `gemini` represent the API protocol.
`modelProviders[].id`	The model ID sent to the API (e.g. `qwen3.6-plus`, `gpt-4o`).
`modelProviders[].envKey`	The name of the environment variable that holds your API key.
`modelProviders[].baseUrl`	The API endpoint URL (required for non-default endpoints).
`env`	A fallback place to store API keys (lowest priority; prefer `.env` files or `export` for sensitive keys).
`security.auth.selectedType`	The protocol to use on startup (`openai`, `anthropic`, `gemini`, `vertex-ai`).
`model.name`	The default model to use when Qwen Code starts.

Step 3: Start Qwen Code — your configuration takes effect automatically:

qwen

Use the /model command at any time to switch between all configured models.

More Examples

Coding Plan (Alibaba Cloud ModelStudio) — fixed monthly fee, higher quotas

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.6-plus",
        "name": "qwen3.6-plus (Coding Plan)",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "description": "qwen3.6-plus from ModelStudio Coding Plan",
        "envKey": "BAILIAN_CODING_PLAN_API_KEY"
      },
      {
        "id": "qwen3.5-plus",
        "name": "qwen3.5-plus (Coding Plan)",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "description": "qwen3.5-plus with thinking enabled from ModelStudio Coding Plan",
        "envKey": "BAILIAN_CODING_PLAN_API_KEY",
        "generationConfig": {
          "extra_body": {
            "enable_thinking": true
          }
        }
      },
      {
        "id": "glm-4.7",
        "name": "glm-4.7 (Coding Plan)",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "description": "glm-4.7 with thinking enabled from ModelStudio Coding Plan",
        "envKey": "BAILIAN_CODING_PLAN_API_KEY",
        "generationConfig": {
          "extra_body": {
            "enable_thinking": true
          }
        }
      },
      {
        "id": "kimi-k2.5",
        "name": "kimi-k2.5 (Coding Plan)",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "description": "kimi-k2.5 with thinking enabled from ModelStudio Coding Plan",
        "envKey": "BAILIAN_CODING_PLAN_API_KEY",
        "generationConfig": {
          "extra_body": {
            "enable_thinking": true
          }
        }
      }
    ]
  },
  "env": {
    "BAILIAN_CODING_PLAN_API_KEY": "sk-xxxxxxxxxxxxx"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3.6-plus"
  }
}

Subscribe to the Coding Plan and get your API key at Alibaba Cloud ModelStudio(Beijing) or Alibaba Cloud ModelStudio(intl).

Multiple providers (OpenAI + Anthropic + Gemini)

{
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1"
      }
    ],
    "anthropic": [
      {
        "id": "claude-sonnet-4-20250514",
        "name": "Claude Sonnet 4",
        "envKey": "ANTHROPIC_API_KEY"
      }
    ],
    "gemini": [
      {
        "id": "gemini-2.5-pro",
        "name": "Gemini 2.5 Pro",
        "envKey": "GEMINI_API_KEY"
      }
    ]
  },
  "env": {
    "OPENAI_API_KEY": "sk-xxxxxxxxxxxxx",
    "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxxxxxxx",
    "GEMINI_API_KEY": "AIzaxxxxxxxxxxxxx"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "gpt-4o"
  }
}

Enable thinking mode (for supported models like qwen3.5-plus)

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.5-plus",
        "name": "qwen3.5-plus (thinking)",
        "envKey": "DASHSCOPE_API_KEY",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "generationConfig": {
          "extra_body": {
            "enable_thinking": true
          }
        }
      }
    ]
  },
  "env": {
    "DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3.5-plus"
  }
}

Tip: You can also set API keys via export in your shell or .env files, which take higher priority than settings.json → env. See the authentication guide for full details.

Security note: Never commit API keys to version control. The ~/.qwen/settings.json file is in your home directory and should stay private.

Local Model Setup (Ollama / vLLM)

You can also run models locally — no API key or cloud account needed. This is not an authentication method; instead, configure your local model endpoint in ~/.qwen/settings.json using the modelProviders field.

Set generationConfig.contextWindowSize inside the matching provider entry and adjust it to the context length configured on your local server.

Ollama setup

Install Ollama from ollama.com
Pull a model: ollama pull qwen3:32b
Configure ~/.qwen/settings.json:

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3:32b",
        "name": "Qwen3 32B (Ollama)",
        "baseUrl": "http://localhost:11434/v1",
        "description": "Qwen3 32B running locally via Ollama",
        "generationConfig": {
          "contextWindowSize": 131072
        }
      }
    ]
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3:32b"
  }
}

vLLM setup

Install vLLM: pip install vllm
Start the server: vllm serve Qwen/Qwen3-32B
Configure ~/.qwen/settings.json:

{
  "modelProviders": {
    "openai": [
      {
        "id": "Qwen/Qwen3-32B",
        "name": "Qwen3 32B (vLLM)",
        "baseUrl": "http://localhost:8000/v1",
        "description": "Qwen3 32B running locally via vLLM",
        "generationConfig": {
          "contextWindowSize": 131072
        }
      }
    ]
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "Qwen/Qwen3-32B"
  }
}

Usage

As an open-source terminal agent, you can use Qwen Code in four primary ways:

Interactive mode (terminal UI)
Headless mode (scripts, CI)
IDE integration (VS Code, Zed)
SDKs (TypeScript, Python, Java)

Interactive mode

cd your-project/
qwen

Run qwen in your project folder to launch the interactive terminal UI. Use @ to reference local files (for example @src/main.ts).

Headless mode

cd your-project/
qwen -p "your question"

Use -p to run Qwen Code without the interactive UI—ideal for scripts, automation, and CI/CD. Learn more: Headless mode.

IDE integration

Use Qwen Code inside your editor (VS Code, Zed, and JetBrains IDEs):

SDKs

Build on top of Qwen Code with the available SDKs:

Python SDK example:

import asyncio

from qwen_code_sdk import is_sdk_result_message, query


async def main() -> None:
    result = query(
        "Summarize the repository layout.",
        {
            "cwd": "/path/to/project",
            "path_to_qwen_executable": "qwen",
        },
    )

    async for message in result:
        if is_sdk_result_message(message):
            print(message["result"])


asyncio.run(main())

Commands & Shortcuts

Session Commands

/help - Display available commands
/clear - Clear conversation history
/compress - Compress history to save tokens
/stats - Show current session information
/bug - Submit a bug report
/exit or /quit - Exit Qwen Code

Keyboard Shortcuts

Ctrl+C - Cancel current operation
Ctrl+D - Exit (on empty line)
Up/Down - Navigate command history

Learn more about Commands

Tip: In YOLO mode (--yolo), vision switching happens automatically without prompts when images are detected. Learn more about Approval Mode

Configuration

Qwen Code can be configured via settings.json, environment variables, and CLI flags.

File	Scope	Description
`~/.qwen/settings.json`	User (global)	Applies to all your Qwen Code sessions. Recommended for `modelProviders` and `env`.
`.qwen/settings.json`	Project	Applies only when running Qwen Code in this project. Overrides user settings.

The most commonly used top-level fields in settings.json:

Field	Description
`modelProviders`	Define available models per protocol (`openai`, `anthropic`, `gemini`, `vertex-ai`).
`env`	Fallback environment variables (e.g. API keys). Lower priority than shell `export` and `.env` files.
`security.auth.selectedType`	The protocol to use on startup (e.g. `openai`).
`model.name`	The default model to use when Qwen Code starts.

See the Authentication section above for complete settings.json examples, and the settings reference for all available options.

Benchmark Results

Terminal-Bench Performance

Agent	Model	Accuracy
Qwen Code	Qwen3-Coder-480A35	37.5%
Qwen Code	Qwen3-Coder-30BA3B	31.3%

Ecosystem

Looking for a graphical interface?

AionUi A modern GUI for command-line AI tools including Qwen Code
Gemini CLI Desktop A cross-platform desktop/web/mobile UI for Qwen Code

Troubleshooting

If you encounter issues, check the troubleshooting guide.

Common issues:

Qwen OAuth free tier was discontinued on 2026-04-15: Qwen OAuth is no longer available. Run qwen → /auth and switch to API Key or Coding Plan. See the Authentication section above for setup instructions.

To report a bug from within the CLI, run /bug and include a short title and repro steps.

Connect with Us

Acknowledgments

This project is based on Google Gemini CLI. We acknowledge and appreciate the excellent work of the Gemini CLI team. Our main contribution focuses on parser-level adaptations to better support Qwen-Coder models.