Skip to content
Merged
Show file tree
Hide file tree
Changes from 21 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
870ae88
docs: Align docs with current CLI behavior
doudouOUC Jun 22, 2026
a82a9a6
chore: merge main into docs audit branch
doudouOUC Jun 22, 2026
71c8c4e
codex: address PR review feedback (#5589)
doudouOUC Jun 22, 2026
5122c47
codex: address PR review feedback (#5589)
doudouOUC Jun 22, 2026
6023f47
codex: address PR review feedback (#5589)
doudouOUC Jun 22, 2026
d704c11
codex: address PR review feedback (#5589)
doudouOUC Jun 22, 2026
a56b5cf
codex: address PR review feedback (#5589)
doudouOUC Jun 22, 2026
ac2a3d9
codex: address PR review feedback (#5589)
doudouOUC Jun 22, 2026
57f6048
codex: address PR review feedback (#5589)
doudouOUC Jun 22, 2026
2fe19a0
codex: address PR review feedback (#5589)
doudouOUC Jun 22, 2026
265b103
codex: address PR review feedback (#5589)
doudouOUC Jun 22, 2026
269c864
codex: address PR review feedback (#5589)
doudouOUC Jun 22, 2026
6b68eaf
codex: fix BaseTextInput Ink import (#5589)
doudouOUC Jun 22, 2026
1ff883f
codex: address PR review feedback (#5589)
doudouOUC Jun 23, 2026
5e7c3b0
fix(core): surface MCP OAuth credential read failures
doudouOUC Jun 23, 2026
adc69e0
chore: merge main into PR 5589
doudouOUC Jun 23, 2026
02052e1
fix(core): harden MCP OAuth error handling
doudouOUC Jun 23, 2026
6dcca8d
fix(core): keep SSE OAuth pre-read best effort
doudouOUC Jun 23, 2026
7881659
fix(core): handle SSE OAuth validation errors
doudouOUC Jun 23, 2026
8732cd7
fix(core): surface MCP OAuth recovery guidance
doudouOUC Jun 23, 2026
6f4af39
fix(core): cover MCP OAuth retry paths
doudouOUC Jun 23, 2026
31b649b
fix(core): address OAuth guidance review
doudouOUC Jun 23, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ To run the integration tests, use the following command:
npm run test:e2e
```

For more detailed information on the integration testing framework, please see the [Integration Tests documentation](./docs/integration-tests.md).
For more detailed information on the integration testing framework, please see the [Integration Tests documentation](./docs/developers/development/integration-tests.md).

### Linting and Preflight Checks

Expand Down
2 changes: 1 addition & 1 deletion docs/developers/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ To run the integration tests, use the following command:
npm run test:e2e
```

For more detailed information on the integration testing framework, please see the [Integration Tests documentation](./docs/integration-tests.md).
For more detailed information on the integration testing framework, please see the [Integration Tests documentation](./development/integration-tests.md).

### Linting and Preflight Checks

Expand Down
2 changes: 1 addition & 1 deletion docs/developers/daemon/00-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ It complements, rather than replaces, these existing docs:
| [`../../users/qwen-serve.md`](../../users/qwen-serve.md) | Operators | User quickstart, flags, threat model |
| [`../qwen-serve-protocol.md`](../qwen-serve-protocol.md) | Protocol implementers | HTTP route catalog, request/response shapes, error codes |
| [`../examples/daemon-client-quickstart.md`](../examples/daemon-client-quickstart.md) | SDK users | End-to-end TypeScript walkthrough |
| [`../daemon-client-adapters/`](../daemon-client-adapters/) | Adapter authors | Client adapter design notes |
| [`14-cli-tui-adapter.md`](./14-cli-tui-adapter.md) | Adapter authors | Client adapter design notes |
| [`../../design/f2-mcp-transport-pool.md`](../../design/f2-mcp-transport-pool.md) | F2 maintainers | Workspace MCP transport pool design v2.2 |

If you want to **start a daemon and use it**, read `qwen-serve.md` first. If you want to **build a client against the wire format**, read `qwen-serve-protocol.md`. If you want to **understand, extend, or debug the daemon internals**, read this set.
Expand Down
4 changes: 3 additions & 1 deletion docs/developers/daemon/12-auth-security.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,9 @@ details.

### Device-flow auth

Separate OAuth surface for provider authentication (Qwen OAuth, etc.):
Separate OAuth surface for provider authentication. The v1 provider identifier is
`qwen-oauth`, but Qwen OAuth free tier was discontinued on 2026-04-15; new
setups should use a currently supported auth provider when one is available.

- `POST /workspace/auth/device-flow` — start a flow; returns `{deviceFlowId, providerId, expiresAt, verificationUrl, userCode}`.
- `GET /workspace/auth/device-flow/:id` — poll state.
Expand Down
4 changes: 4 additions & 0 deletions docs/developers/daemon/13-sdk-daemon-client.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,10 @@ sequenceDiagram
AF-->>App: final state
```

`qwen-oauth` is the legacy v1 provider identifier. Qwen OAuth free tier was
discontinued on 2026-04-15, so new clients should prefer a currently supported
auth provider when one is available.

## State & Lifecycle

- `DaemonClient` is connection-less; nothing happens at construction. Every method opens a fresh `fetch`.
Expand Down
2 changes: 1 addition & 1 deletion docs/developers/development/telemetry.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ OpenTelemetry names: `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`,
The `QWEN_TELEMETRY_OTLP_*` variants take precedence over the `OTEL_*` variants.

For detailed information about all configuration options, see the
[Configuration Guide](./cli/configuration.md).
[Configuration Guide](../../users/configuration/settings.md).

### Resource attributes

Expand Down
9 changes: 8 additions & 1 deletion docs/developers/qwen-serve-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -1559,7 +1559,14 @@ After a successful vote, every connected client sees `permission_resolved` with

The daemon brokers an OAuth 2.0 Device Authorization Grant (RFC 8628) so a remote SDK client can trigger a login whose tokens land on the **daemon** filesystem — not on the client. The daemon polls the IdP itself; the client's only job is to display the verification URL + user code and (optionally) subscribe to SSE for completion events.

Capability tag: `auth_device_flow` (always advertised). Supported providers in v1: `qwen-oauth`.
Capability tag: `auth_device_flow` (always advertised). Supported providers in
v1: `qwen-oauth`.

> [!note]
>
> Qwen OAuth free tier was discontinued on 2026-04-15. Treat `qwen-oauth` as the
> legacy v1 provider identifier in this protocol; new clients should prefer a
> currently supported auth provider when one is available.

**Runtime locality.** The daemon never spawns a browser — even if it can. The client decides whether to call `open(verificationUri)` locally; on a headless pod (the canonical Mode B deployment) the user opens the URL on whatever device they have a browser on. See `docs/users/qwen-serve.md` for the recommended UX.

Expand Down
2 changes: 1 addition & 1 deletion docs/developers/sdk-java.md
Original file line number Diff line number Diff line change
Expand Up @@ -308,4 +308,4 @@ A: Yes, use the `setEnv()` method in `TransportOptions` to pass environment vari

## License

Apache-2.0 - see [LICENSE](./LICENSE) for details.
Apache-2.0 - see [LICENSE](../../LICENSE) for details.
30 changes: 20 additions & 10 deletions docs/developers/sdk-typescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,12 +68,17 @@ Creates a new query session with the Qwen Code.
| `abortController` | `AbortController` | - | Controller to cancel the query session. Call `abortController.abort()` to terminate the session and cleanup resources. |
| `debug` | `boolean` | `false` | Enable debug mode for verbose logging from the CLI process. |
| `maxSessionTurns` | `number` | `-1` (unlimited) | Maximum number of conversation turns before the session automatically terminates. A turn consists of a user message and an assistant response. |
| `coreTools` | `string[]` | - | Equivalent to `tool.core` in settings.json. If specified, only these tools will be available to the AI. Example: `['read_file', 'write_file', 'run_shell_command']`. |
| `excludeTools` | `string[]` | - | Equivalent to `tool.exclude` in settings.json. Excluded tools return a permission error immediately. Takes highest priority over all other permission settings. Supports pattern matching: tool name (`'write_file'`), tool class (`'ShellTool'`), or shell command prefix (`'ShellTool(rm )'`). |
| `allowedTools` | `string[]` | - | Equivalent to `tool.allowed` in settings.json. Matching tools bypass `canUseTool` callback and execute automatically. Only applies when tool requires confirmation. Supports same pattern matching as `excludeTools`. |
| `authType` | `'openai' \| 'qwen-oauth'` | `'openai'` | Authentication type for the AI service. Using `'qwen-oauth'` in SDK is not recommended as credentials are stored in `~/.qwen` and may need periodic refresh. |
| `coreTools` | `string[]` | - | Uses the legacy `coreTools` / CLI `--core-tools` allowlist semantics. If specified, only matching core tools are registered for the session. This is separate from `permissions.allow`, which auto-approves matching tool calls but does not restrict tool registration. Example: `['read_file', 'edit', 'run_shell_command']`. |
| `excludeTools` | `string[]` | - | Equivalent to `permissions.deny` in settings.json. Excluded tools return a permission error immediately. Takes highest priority over all other permission settings. Supports tool name aliases and pattern matching: tool name (`'write_file'`), shell command prefix (`'Bash(rm *)'`), or path patterns (`'Read(.env)'`, `'Edit(/src/**)'`). |
| `allowedTools` | `string[]` | - | Equivalent to `permissions.allow` in settings.json. Matching tools bypass `canUseTool` callback and execute automatically. Only applies when tool requires confirmation. Supports same pattern matching as `excludeTools`. Example: `['Bash(git status)', 'Bash(npm test)']`. |
| `authType` | `'openai' \| 'qwen-oauth'` | `'openai'` | Authentication type for the AI service. Qwen OAuth free tier was discontinued on 2026-04-15; new SDK setups should use OpenAI-compatible authentication or another supported provider. |
| `agents` | `SubagentConfig[]` | - | Configuration for subagents that can be invoked during the session. Subagents are specialized AI agents for specific tasks or domains. |
| `includePartialMessages` | `boolean` | `false` | When `true`, the SDK emits incomplete messages as they are being generated, allowing real-time streaming of the AI's response. |
| `resume` | `string` | - | Resume a previous session by providing its session ID. Equivalent to CLI's `--resume` flag. |
| `sessionId` | `string` | - | Specify a session ID for the new session. Ensures SDK and CLI use the same ID without resuming history. Equivalent to CLI's `--session-id` flag. |

> [!note]
> For `coreTools`, aliases like `Read`, `Edit`, and `Bash` also work, but invocation specifiers such as `Bash(git *)` are stripped. `coreTools` restricts tool registration, not invocation patterns.

### Timeouts

Expand Down Expand Up @@ -163,12 +168,17 @@ The SDK supports different permission modes for controlling tool execution:

### Permission Priority Chain

1. `excludeTools` - Blocks tools completely
2. `permissionMode: 'plan'` - Blocks non-read-only tools
3. `permissionMode: 'yolo'` - Auto-approves all tools
4. `allowedTools` - Auto-approves matching tools
5. `canUseTool` callback - Custom approval logic
6. Default behavior - Auto-deny in SDK mode
Decision priority (highest first): `deny` > `ask` > `allow` > _(default/interactive mode)_

The first matching rule wins.

1. `excludeTools` / `permissions.deny` - Blocks tools completely (returns permission error)
2. `permissions.ask` - Always requires user confirmation
3. `permissionMode: 'plan'` - Blocks all non-read-only tools
4. `permissionMode: 'yolo'` - Auto-approves all tools
5. `allowedTools` / `permissions.allow` - Auto-approves matching tools
6. `canUseTool` callback - Custom approval logic (if provided, not called for allowed tools)
7. Default behavior - Auto-deny in SDK mode (write tools require explicit approval)

## Examples

Expand Down
8 changes: 3 additions & 5 deletions docs/developers/tools/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ You will typically see messages in the CLI indicating when a tool is being calle
Many tools, especially those that can modify your file system or execute commands (`write_file`, `edit`, `run_shell_command`), are designed with safety in mind. Qwen Code will typically:

- **Require confirmation:** Prompt you before executing potentially sensitive operations, showing you what action is about to be taken.
- **Utilize sandboxing:** All tools are subject to restrictions enforced by sandboxing (see [Sandboxing in Qwen Code](../sandbox.md)). This means that when operating in a sandbox, any tools (including MCP servers) you wish to use must be available _inside_ the sandbox environment. For example, to run an MCP server through `npx`, the `npx` executable must be installed within the sandbox's Docker image or be available in the `sandbox-exec` environment.
- **Utilize sandboxing:** All tools are subject to restrictions enforced by sandboxing (see [Sandboxing in Qwen Code](./sandbox.md)). This means that when operating in a sandbox, any tools (including MCP servers) you wish to use must be available _inside_ the sandbox environment. For example, to run an MCP server through `npx`, the `npx` executable must be installed within the sandbox's Docker image or be available in the `sandbox-exec` environment.

It's important to always review confirmation prompts carefully before allowing a tool to proceed.

Expand All @@ -54,8 +54,6 @@ Qwen Code's built-in tools can be broadly categorized as follows:
Additionally, these tools incorporate:

- **[MCP servers](./mcp-server.md)**: MCP servers act as a bridge between the model and your local environment or other services like APIs.
- **[MCP Quick Start Guide](../mcp-quick-start.md)**: Get started with MCP in 5 minutes with practical examples
- **[MCP Example Configurations](../mcp-example-configs.md)**: Ready-to-use configurations for common scenarios
- **[MCP User Guide](../../users/features/mcp.md)**: Configure MCP servers and manage them from Qwen Code
- **[Web Search via MCP](./web-search.md)**: Connect to web search services (Bailian, Tavily, GLM) through MCP
- **[MCP Testing & Validation](../mcp-testing-validation.md)**: Test and validate your MCP server setups
- **[Sandboxing](../sandbox.md)**: Sandboxing isolates the model and its changes from your environment to reduce potential risk.
- **[Sandboxing](./sandbox.md)**: Sandboxing isolates the model and its changes from your environment to reduce potential risk.
34 changes: 16 additions & 18 deletions docs/developers/tools/mcp-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,18 +183,8 @@ OAuth will not work in:

#### Managing OAuth Authentication

Use the `/mcp auth` command to manage OAuth authentication:

```bash
# List servers requiring authentication
/mcp auth

# Authenticate with a specific server
/mcp auth serverName

# Re-authenticate if tokens expire
/mcp auth serverName
```
Use the `/mcp` dialog inside an interactive Qwen Code session to inspect MCP
servers and manage OAuth authentication.

#### OAuth Configuration Properties

Expand All @@ -212,11 +202,14 @@ Use the `/mcp auth` command to manage OAuth authentication:

OAuth tokens are automatically:

- **Stored securely** in `~/.qwen/mcp-oauth-tokens-v2.json` (AES-256-GCM encrypted), with keychain storage preferred when available
- **Stored** in `~/.qwen/mcp-oauth-tokens.json` (plaintext, mode 0600) by default. If `QWEN_CODE_FORCE_ENCRYPTED_FILE_STORAGE=true` is set, Qwen Code uses keychain-backed storage where available, or `~/.qwen/mcp-oauth-tokens-v2.json` with AES-256-GCM encryption.
- **Refreshed** when expired (if refresh tokens are available)
- **Validated** before each connection attempt
- **Cleaned up** when invalid or expired

> [!WARNING]
> By default, OAuth tokens are stored unencrypted on disk. On shared or multi-user machines, set `QWEN_CODE_FORCE_ENCRYPTED_FILE_STORAGE=true` to protect credentials.

#### Authentication Provider Type

You can specify the authentication provider type using the `authProviderType` property:
Expand Down Expand Up @@ -859,9 +852,10 @@ qwen mcp add --transport sse oauth-server https://api.example.com/sse/ \
--oauth-token-url https://provider.example.com/token
```

### Managing Servers (`qwen mcp`)
### Managing Servers (`/mcp`)

To view and manage all MCP servers currently configured, use the `manage` command or simply `qwen mcp`. This opens an interactive TUI dialog where you can:
To view and manage all MCP servers currently configured, open the `/mcp`
dialog inside an interactive Qwen Code session. This dialog lets you:

- View all MCP servers with their connection status
- Enable/disable servers
Expand All @@ -872,9 +866,13 @@ To view and manage all MCP servers currently configured, use the `manage` comman
**Command:**

```bash
qwen mcp
# or
qwen mcp manage
qwen
```

Then enter:

```text
/mcp
```

The management dialog provides a visual interface showing each server's name, configuration details, connection status, and available tools/prompts.
Expand Down
Loading
Loading