AIClaw 3.7.33 如何管理 Python 和 Node.js 環境而不改寫用戶 Shell 設定

A desktop agent can find a skill or an MCP server and still fail to start it because python3, node, or npx is missing. Recovering a user's terminal PATH helps locate software that already exists. It cannot supply an interpreter that has never been installed.

AIClaw 3.7.33 introduced application-managed Python and Node.js environments for that gap. The app prepares pinned interpreters in the background and puts their executable directories ahead of the existing tool PATH. This is a published feature, not an unreleased proposal. The implementation links below are pinned to its introduction tag.

An earlier local-runtime article covered finding installed agent CLIs through a recovered login-shell environment. This change addresses provisioning Python and Node.js for desktop tools, skills, and stdio MCP processes.

Pin the artifacts, not a moving latest release

The runtime manifest records the interpreter version, download URL, expected archive root, executable path, and SHA-256 checksum for each supported target.

In this release, those versions are Node.js 24.22.2, including npm and npx, and Python 3.12.16+20261026 from python-build-standalone. The target list covers macOS Apple Silicon, macOS Intel, Windows x64, and Linux x64. An unlisted platform receives no managed-runtime entries from this manifest.

Node archives come from nodejs.org. Python archives come from the public Astral python-build-standalone release on GitHub. The app does not discover and adopt a newer interpreter version on every startup; changing the pinned version or checksum requires an application update.

This is background provisioning, not an offline interpreter embedded in the installer. The first preparation needs network access.

Verify before making an installation available

The installer first looks for an existing runtime whose saved version and checksum match the manifest. It also runs that executable with --version. A successful check lets the app reuse the installed copy without another download.

For a fresh installation, the sequence is:

download into a temporary directory
    → hash the archive while reading it
    → compare the pinned SHA-256
    → extract into staging
    → run the extracted executable with --version
    → write the runtime marker
    → move the prepared directory into place

The download has a five-minute abort deadline and a 192 MiB size ceiling. Staging is removed in a finally block, including when verification fails or preparation is cancelled.

These checks establish that the archive matches the pinned artifact and the extracted executable starts. They do not prove that every optional package or native extension will work.

Change the child environment, not the user's shell

The desktop session manager obtains the existing tool PATH, then passes a modified environment into the Go kernel process. Tool commands, skills, and stdio MCP processes inherit that environment unless their own configuration overrides it.

Managed executable directories are placed before the existing paths. The README's runtime section documents the storage root as ~/.aiclaw/runtimes. System installations and shell startup files are left unchanged.

Those paths are included before preparation finishes. Once a binary becomes available there, an already-running kernel can find it on a subsequent lookup. While preparation is incomplete, an existing system interpreter may still satisfy the lookup through the remaining PATH entries.

This is a default lookup policy. An explicit executable path, a command that changes PATH, or a separately activated virtual environment can select something else.

Keep dependencies across restarts

Python gets a persistent virtual environment with pip. npm gets an application-specific global package prefix and cache; pip has its own cache location as well. Recreating the runtime manager does not intentionally rebuild a valid Python environment or erase its extra dependencies.

Windows needs additional handling: environment variable names are case-insensitive, so the code preserves the existing PATH key's casing instead of adding a competing key. It also prepares both python and python3 executable names in the managed Python environment.

The runtime manager coalesces concurrent preparation calls. Node and Python preparation run independently, and a failure is reported without discarding the other runtime's ready state. A timer retries unfinished preparation every 30 minutes; starting the app attempts preparation again. Shutdown aborts work in progress.

What the verification establishes

For this article, I ran the public tag-pinned managed-runtime test suite in an isolated temporary directory on macOS. All 11 tests passed. The suite uses controlled download and process-runner fixtures to exercise checksum validation, offline reuse, cancellation, cleanup, Windows extraction arguments and environment handling, concurrent preparation, retries, and dependency retention.

That is not a fresh download of every production interpreter. The release notes separately report an isolated real macOS ARM64 download check, including Node/Python commands and stdio MCP launches, plus a complete local make check. They explicitly distinguish simulated Windows handling from verification on a real Windows machine. I did not repeat those broader checks for this article.

Additional packages still need installation, native extensions may need a compiler, and these tool environments do not replace the prerequisites for building AIClaw itself. The practical improvement is a predictable place to obtain and retain the common interpreters an agent's tools need, without asking users to rewrite their system Python or shell configuration.