#Python environment

1 messages · Page 1 of 1 (latest)

craggy oyster
#

What is the recommended Python environment setup on MacOS for OpenClaw and skills?

I installed OpenClaw on a new Mac Mini. I tried adding some skills via ClawHub. I'm using the default Python that comes with MacOS (not the homebrew). The skill required python-docx so I installed that via "pip install python-docx". OpenClaw can't seem to find the python library.

Should I use the Homebrew Python instead of the system default? And setup a virtual environment to install the python libraries? How would I get OpenClaw to run in the python virtual environment?

runic pivotBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> âś… Mark Solution

quick barnBOT
#

On macOS there isn’t a special “OpenClaw Python environment” — a skill that runs Python is just running whatever python3 OpenClaw can see in that execution context, and that often differs from the one you used when you typed pip install ….

The two most common causes of “installed it, but the skill can’t import it” are:

  1. Interpreter mismatch (you installed into Python A, the skill runs Python B)
  2. Sandboxing (the skill is running inside a Docker sandbox, so host-installed packages are invisible)

1) First: confirm which Python the skill is actually using

Avoid plain pip. Always pair pip with the interpreter:

python3 -c "import sys; print(sys.executable); print(sys.version)"
python3 -m pip --version
python3 -m pip show python-docx
python3 -c "import docx; print(docx.__version__)"
#

Whichever python3 you see there is the one that must have python-docx installed.

(Also: the package is python-docx, but the import is import docx.)

2) Recommended setup on macOS: Homebrew Python + venv

Yes: I’d recommend Homebrew Python (or pyenv) and using a virtualenv for skill deps.

Example (shared venv for skills):

brew install python
/opt/homebrew/bin/python3 -m venv ~/.openclaw/venvs/skills
~/.openclaw/venvs/skills/bin/python -m pip install -U pip
~/.openclaw/venvs/skills/bin/python -m pip install python-docx

How to make OpenClaw use the venv: have the skill run the venv interpreter explicitly, e.g. in the skill instructions / wrapper script call:

# 
~/.openclaw/venvs/skills/bin/python your_script.py

(or set the script’s shebang to that venv python).

This is the most reliable approach, especially if the Gateway runs as a service where PATH may not match your interactive shell.

3) If you enabled sandboxing: install deps inside the sandbox (or turn it off)

If the session/agent is sandboxed, tools (including exec) run in a Docker container. Host Python + venv won’t be visible there. Docs:
https://docs.openclaw.ai/gateway/sandboxing
https://docs.openclaw.ai/tools/skills

In that case you have two options:

  • Simplest: disable sandboxing for that agent while you’re getting skills working.
  • Or: install Python + python-docx in the sandbox image via agents.defaults.sandbox.docker.setupCommand (requires sandbox networking + writable root, etc.; see sandboxing doc for the pitfalls).