From c0c94bd4fcb38d75b2077c8060f6a6cb848c0f35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E4=BC=9F=E5=85=89?= Date: Tue, 13 Jan 2026 10:39:32 +0800 Subject: [PATCH 1/3] feat: Customizing the sandbox environment --- docs/developers/tools/_meta.ts | 1 + docs/developers/tools/sandbox.md | 13 +++++++++++++ docs/users/features/sandbox.md | 9 --------- docs/users/quickstart.md | 2 +- packages/cli/src/utils/sandbox.ts | 6 +++--- 5 files changed, 18 insertions(+), 13 deletions(-) create mode 100644 docs/developers/tools/sandbox.md diff --git a/docs/developers/tools/_meta.ts b/docs/developers/tools/_meta.ts index 9964b9976..7d4f494b8 100644 --- a/docs/developers/tools/_meta.ts +++ b/docs/developers/tools/_meta.ts @@ -10,4 +10,5 @@ export default { 'web-search': 'Web Search', memory: 'Memory', 'mcp-server': 'MCP Servers', + sandbox: 'Sandboxing', }; diff --git a/docs/developers/tools/sandbox.md b/docs/developers/tools/sandbox.md new file mode 100644 index 000000000..b55964bca --- /dev/null +++ b/docs/developers/tools/sandbox.md @@ -0,0 +1,13 @@ +## Customizing the sandbox environment (Docker/Podman) + +If you need extra tools inside the container (e.g., `git`, `python`, `rg`), create a custom Dockerfile: + +1. `cd packages/cli` +2. `npm link` +3. `which qwen` +4. `cd your-project` + +- Path: `.qwen/sandbox.Dockerfile` +- Then run with: `BUILD_SANDBOX=1 qwen -s ...` + +This builds a project-specific image based on the default sandbox image. diff --git a/docs/users/features/sandbox.md b/docs/users/features/sandbox.md index 66ea359cc..23ea89fe7 100644 --- a/docs/users/features/sandbox.md +++ b/docs/users/features/sandbox.md @@ -166,15 +166,6 @@ export SANDBOX_SET_UID_GID=true # Force host UID/GID export SANDBOX_SET_UID_GID=false # Disable UID/GID mapping ``` -## Customizing the sandbox environment (Docker/Podman) - -If you need extra tools inside the container (e.g., `git`, `python`, `rg`), create a custom Dockerfile: - -- Path: `.qwen/sandbox.Dockerfile` -- Then run with: `BUILD_SANDBOX=1 qwen -s ...` - -This builds a project-specific image based on the default sandbox image. - ## Troubleshooting ### Common issues diff --git a/docs/users/quickstart.md b/docs/users/quickstart.md index 1fa249abc..eac8f9474 100644 --- a/docs/users/quickstart.md +++ b/docs/users/quickstart.md @@ -159,7 +159,7 @@ Qwen Code will: ### Test out other common workflows -There are a number of ways to work with Claude: +There are a number of ways to work with Qwen Code: **Refactor code** diff --git a/packages/cli/src/utils/sandbox.ts b/packages/cli/src/utils/sandbox.ts index ee518f438..a35985b04 100644 --- a/packages/cli/src/utils/sandbox.ts +++ b/packages/cli/src/utils/sandbox.ts @@ -360,10 +360,10 @@ export async function start_sandbox( // // note this can only be done with binary linked from gemini-cli repo if (process.env['BUILD_SANDBOX']) { - if (!gcPath.includes('gemini-cli/packages/')) { + if (!gcPath.includes('qwen-code/packages/')) { throw new FatalSandboxError( - 'Cannot build sandbox using installed gemini binary; ' + - 'run `npm link ./packages/cli` under gemini-cli repo to switch to linked binary.', + 'Cannot build sandbox using installed qwencode binary; ' + + 'run `npm link ./packages/cli` under qwencode-cli repo to switch to linked binary.', ); } else { console.error('building sandbox ...'); From 85473210e5f3ea1618cfb5d8b198d7c8d698c64a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E4=BC=9F=E5=85=89?= Date: Tue, 13 Jan 2026 10:47:08 +0800 Subject: [PATCH 2/3] feat: Customizing the sandbox environment --- packages/cli/src/utils/sandbox.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/utils/sandbox.ts b/packages/cli/src/utils/sandbox.ts index a35985b04..749d7193e 100644 --- a/packages/cli/src/utils/sandbox.ts +++ b/packages/cli/src/utils/sandbox.ts @@ -362,8 +362,8 @@ export async function start_sandbox( if (process.env['BUILD_SANDBOX']) { if (!gcPath.includes('qwen-code/packages/')) { throw new FatalSandboxError( - 'Cannot build sandbox using installed qwencode binary; ' + - 'run `npm link ./packages/cli` under qwencode-cli repo to switch to linked binary.', + 'Cannot build sandbox using installed Qwen Code binary; ' + + 'run `npm link ./packages/cli` under QwenCode-cli repo to switch to linked binary.', ); } else { console.error('building sandbox ...'); From f762a62a2e20ac2ec26f4bc795a1bcb0e90d8f71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E4=BC=9F=E5=85=89?= Date: Tue, 13 Jan 2026 18:54:26 +0800 Subject: [PATCH 3/3] feat: Improve the usage documentation --- docs/developers/tools/sandbox.md | 89 +++++++++++++++++++++++++++++--- 1 file changed, 83 insertions(+), 6 deletions(-) diff --git a/docs/developers/tools/sandbox.md b/docs/developers/tools/sandbox.md index b55964bca..92550f164 100644 --- a/docs/developers/tools/sandbox.md +++ b/docs/developers/tools/sandbox.md @@ -1,13 +1,90 @@ ## Customizing the sandbox environment (Docker/Podman) -If you need extra tools inside the container (e.g., `git`, `python`, `rg`), create a custom Dockerfile: +### Currently, the project does not support the use of the BUILD_SANDBOX function after installation through the npm package -1. `cd packages/cli` -2. `npm link` -3. `which qwen` -4. `cd your-project` +1. To build a custom sandbox, you need to access the build scripts (scripts/build_sandbox.js) in the source code repository. +2. These build scripts are not included in the packages released by npm. +3. The code contains hard-coded path checks that explicitly reject build requests from non-source code environments. + +If you need extra tools inside the container (e.g., `git`, `python`, `rg`), create a custom Dockerfile, The specific operation is as follows + +#### 1、Clone qwen code project first, https://github.com/QwenLM/qwen-code.git + +#### 2、Make sure you perform the following operation in the source code repository directory + +```bash +# 1. First, install the dependencies of the project +npm install + +# 2. Build the Qwen Code project +npm run build + +# 3. Verify that the dist directory has been generated +ls -la packages/cli/dist/ + +# 4. Create a global link in the CLI package directory +cd packages/cli +npm link + +# 5. Verification link (it should now point to the source code) +which qwen +# Expected output: /xxx/xxx/.nvm/versions/node/v24.11.1/bin/qwen +# Or similar paths, but it should be a symbolic link + +# 6. For details of the symbolic link, you can see the specific source code path +ls -la $(dirname $(which qwen))/../lib/node_modules/@qwen-code/qwen-code +# It should show that this is a symbolic link pointing to your source code directory + +# 7.Test the version of qwen +qwen -v +# npm link will overwrite the global qwen. To avoid being unable to distinguish the same version number, you can uninstall the global CLI first +``` + +#### 3、Create your sandbox Dockerfile under the root directory of your own project - Path: `.qwen/sandbox.Dockerfile` -- Then run with: `BUILD_SANDBOX=1 qwen -s ...` + +- Official mirror image address:https://github.com/QwenLM/qwen-code/pkgs/container/qwen-code + +```bash +# Based on the official Qwen sandbox image (It is recommended to explicitly specify the version) +FROM ghcr.io/qwenlm/qwen-code:sha-570ec43 +# Add your extra tools here +RUN apt-get update && apt-get install -y \ + git \ + python3 \ + ripgrep +``` + +#### 4、Create the first sandbox image under the root directory of your project + +```bash +GEMINI_SANDBOX=docker BUILD_SANDBOX=1 qwen -s +# Observe whether the sandbox version of the tool you launched is consistent with the version of your custom image. If they are consistent, the startup will be successful +``` This builds a project-specific image based on the default sandbox image. + +#### Remove npm link + +- If you want to restore the official CLI of qwen, please remove the npm link + +```bash +# Method 1: Unlink globally +npm unlink -g @qwen-code/qwen-code + +# Method 2: Remove it in the packages/cli directory +cd packages/cli +npm unlink + +# Verification has been lifted +which qwen +# It should display "qwen not found" + +# Reinstall the global version if necessary +npm install -g @qwen-code/qwen-code + +# Verification Recovery +which qwen +qwen --version +```