@dhf-qwen/grix

Connect your local Qwen Code to Grix.

After installation, you can chat with this Qwen agent directly in Grix and let it work inside the project directory bound to the current session.

What You Need First

Prepare these four things before you start:

1. A Grix account
2. A Qwen type agent already created in Grix
3. The Agent ID, Endpoint, and API Key copied from the Grix page
4. Qwen Code already installed on your local machine

The shortest path to get the Grix parameters:

1. Open https://grix.dhf.pub
2. Sign up and log in
3. Create a new agent
4. Choose Agent API
5. Select Qwen as the integration type
6. Copy the Agent ID, Endpoint, and API Key shown on the page

Keep these three points in mind:

• Use the Endpoint exactly as provided by Grix. Do not guess or rewrite it.
• --workspace is the default local directory and runtime base directory.
• The first time you enter a new session, Grix will ask you to submit the working directory for that session. Qwen will then prefer that directory for the rest of the session.

Install

npm install -g @qwen-code/qwen-code @dhf-qwen/grix

Start

grix-qwen start \
  --agent-id <Agent ID> \
  --endpoint <Service Endpoint> \
  --api-key <Secret Key> \
  --workspace /path/to/your/project

On the first start, the local integration config is set up automatically. You do not need to edit any config files manually.

Use It in Grix

1. Open https://grix.dhf.pub
2. Find the Qwen agent you just created
3. Send it messages like a normal chat
4. The first time you enter a new session, submit the working directory for that session
5. Keep grix-qwen start running locally. It will work in that directory and send the results back to Grix

Other Commands

Run in the foreground:

grix-qwen agent \
  --agent-id <Agent ID> \
  --endpoint <Service Endpoint> \
  --api-key <Secret Key> \
  --workspace /path/to/your/project

Check status:

grix-qwen status

Stop:

grix-qwen stop

If you only want to write the config first and not start it yet:

grix-qwen install \
  --agent-id <Agent ID> \
  --endpoint <Service Endpoint> \
  --api-key <Secret Key> \
  --workspace /path/to/your/project

Logs

Runtime logs are written under ~/.grix-qwen/ by default. Service stdout/stderr and per-session conversation.jsonl logs are rotated automatically.

| Variable | Default | Purpose | |----------|---------|---------| | GRIX_QWEN_LOG_MAX_BYTES | 10485760 | Maximum bytes per active log file | | GRIX_QWEN_LOG_MAX_FILES | 5 | Number of log files to keep, including rotated history |

Testing

Unit & Integration Tests

npm test

E2E Tests

E2E tests launch a real Qwen Code subprocess, drive it through a mock WebSocket server, and verify full round-trip behavior. qwen must be installed and logged in before running.

Prerequisites

# Verify qwen is available
qwen channel --help

Run All E2E Scenarios

npm run test:e2e

Or use the wrapper script (also runs npm install):

./scripts/check_qwen_plugin_e2e.sh

Run a Specific Scenario

GRIX_QWEN_E2E_SCENARIO=file-read-write npm run test:e2e

Available scenarios:

| Scenario | What it tests | |----------|---------------| | roundtrip | Send a prompt, receive a reply with the expected marker | | approval | Qwen executes a shell command that triggers a permission approval | | developer-flow | Qwen fixes a broken Node.js project so npm test passes | | stop | Cancel a running prompt mid-stream | | file-read-write | Qwen writes a new file and reads an existing file in a temp workspace |

Inspect Artifacts

By default, temp directories are cleaned up after each scenario. Preserve them for debugging:

GRIX_QWEN_E2E_KEEP_TMP=1 \
GRIX_QWEN_E2E_SCENARIO=file-read-write \
npm run test:e2e

The kept directory path is printed to stderr, e.g.:

[grix-qwen e2e] kept artifacts at /tmp/grix-qwen-e2e.XXXXXX

Inside that directory:

| File | Content | |------|---------| | file-read-write-events.log | JSONL log of all send_msg, local_action, local_action_result, event_result packets | | file-read-write-summary.json | Full summary with checklist field showing pass/fail for each assertion | | packets.json | All captured WebSocket packets | | timeline.jsonl | Timestamped packet timeline | | plugin.stdout.log / plugin.stderr.log | Agent process output | | workspace/ | The temp workspace — result.txt (Qwen wrote), notes.txt (pre-existing), AGENTS.md |

统一出站端到端测试

统一出站 E2E 测试代码在 AIBot 后端仓库中。测试会启动本适配器作为真实子进程，连接到真实后端，通过后端发送消息，验证 Qwen 的回复能完整走通协议链路返回。

前置条件：

• AIBot 后端已启动（在后端仓库执行 make dev-up）
• Qwen CLI 已安装且已认证
• 本仓库已构建（npm run build）

运行：

cd <aibot-backend-repo>

GRIX_ADAPTER_E2E=1 \
GRIX_ADAPTER_QWEN_AGENT_ID=<agent-id> \
GRIX_ADAPTER_QWEN_API_KEY=<api-key> \
GRIX_ADAPTER_E2E_USER_ACCOUNT=<account> \
GRIX_ADAPTER_E2E_USER_PASSWORD=<password> \
go test ./e2e/ -run TestLiveAdapterQwenRoundtrip -v -timeout 10m

测试流程：启动 node dist/cli.js agent --endpoint <url> --agent-id <id> --api-key <key>，等待适配器上线，打开会话，发送带 marker 的消息，验证 Qwen 的回复包含 marker。

Environment Variables

| Variable | Default | Purpose | |----------|---------|---------| | GRIX_QWEN_E2E_QWEN_COMMAND | qwen | Path to the Qwen CLI binary | | GRIX_QWEN_E2E_SCENARIO | all | Comma-separated scenario names, or all | | GRIX_QWEN_E2E_TIMEOUT_MS | 120000 | Default timeout per assertion (ms) | | GRIX_QWEN_E2E_DEV_TIMEOUT_MS | 300000 | Timeout for developer-flow and file-read-write (ms) | | GRIX_QWEN_E2E_KEEP_TMP | 0 | Set 1 to preserve temp directories | | GRIX_QWEN_E2E_DEBUG_LOG | (empty) | Path to append debug trace log |

FAQ

qwen Command Not Found

Install Qwen Code first:

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

Cannot Connect to Grix

Check these three items first:

• Whether endpoint was copied directly from the Grix page
• Whether agent-id and api-key are correct
• Whether your machine can reach the corresponding Grix service address

Not Working in the Expected Directory

First check whether the current session has already submitted its working directory.

--workspace is only the default local directory and runtime base directory used at startup. When handling messages, Qwen will prefer the directory bound to the current session.