OpenClaw 源码安装（Linux+MAC）、自启动与基础配置手册 （小白必读 带避坑经验总结）
本文涵盖环境准备、源码安装、自启动配置与基础配置要素说明，以及可能遇到的问题总结，适合喜欢全盘掌控自己管理程序安装的小伙伴，其中包含mac和Linux系统操作说明。
注：如果是想快速尝鲜可以不考虑各类工具安装位置和环境变量配置，直接命令安装即可，本文不赘述，基本自行命令安装 Node.js ≥ 22 + Git 即可 核心安装和初始化命令：
# 一键快速安装 Linux 和 macOS 一样 curl -fsSL https://openclaw.ai/install.sh | bash # 使用国内加速镜像 curl -fsSL https://cdn.jsdelivr.net/gh/1186258278/openclawchinesetranslation@main/install.sh | bash # 一键脚本安装后通常会自动启动 openclaw onboard --install-daemon 零、环境准备（用户目录 + 统一环境变量）
建议将 Node、Git、pnpm、Python 等安装在用户目录下，并通过统一的环境变量文件管理 PATH 与 OpenClaw 相关变量，以便控制权限和影响范围，避免污染系统路径、便于全局把控与排查。
0.1 约定目录结构（示例）
在用户目录下单独划一块“运行时/工具”目录，例如：
```text ~/Applications/ # 或 ~/.local、~/openclaw-env 等，任选其一统一即可 ├── node/ # Node.js 安装目录 ├── git/ # 可选：Git 独立安装 ├── pnpm/ # 可选：pnpm 独立安装时的 store 等 └── python/ # 可选：Python 运行时（部分插件/构建可能用到） ```OpenClaw 运行数据与日志单独放到一个“数据目录”，便于备份与排错：
```text ~/openclaw-data/ # 由 OPENCLAW_STATE_DIR 指定 ├── openclaw.json # 或由 OPENCLAW_CONFIG_PATH 指向 ├── logs/ # 统一日志目录（见 0.4、第二节） │ ├── gateway.log # 守护进程 stdout（launchd/systemd 重定向） │ ├── gateway.err.log # 守护进程 stderr │ └── openclaw-YYYY-MM-DD.log # 可选：Gateway 文件日志（JSONL） ├── credentials/ ├── agents/ ├── workspace/ # 或通过 agents.defaults.workspace 指定 └── ... ```0.2 安装 Node.js（用户目录，≥22）
方式 A：官方二进制解压到用户目录（不依赖 root）
```bash mkdir -p ~/Applications/node cd ~/Applications # 从 https://nodejs.org/ 下载 Linux/macOS 二进制包，解压到 ~/Applications/node # 例如 Linux x64： # curl -sL https://nodejs.org/dist/v22.12.0/node-v22.12.0-linux-x64.tar.xz | tar -xJ -C ~/Applications # mv ~/Applications/node-v22.12.0-linux-x64 ~/Applications/node # macOS ARM64 示例： # curl -sL https://nodejs.org/dist/v22.12.0/node-v22.12.0-darwin-arm64.tar.xz | tar -xJ -C ~/Applications # mv ~/Applications/node-v22.12.0-darwin-arm64 ~/Applications/node export PATH="/Users/OpenClaw/Applications/node/bin:$PATH" node -v # 应 ≥ 22 npm -v ```方式 B：nvm / fnm（推荐，便于多版本，如果不用多版本不需要安装）
nvm 和通过 nvm 安装的 Node 都在**用户目录**下，不写系统目录、无需 root：
- nvm 自身：安装在
~/.nvm/（安装脚本默认即如此） - Node版本：通过
nvm install 22安装的 Node 在~/.nvm/versions/node/下，由 nvm 统一管理、切换。
# nvm 安装到 ~/.nvm，不写系统目录 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 按提示在 ~/.zshrc 或 ~/.bashrc 中加入 nvm 加载脚本，然后： source ~/.zshrc # 或 source ~/.bashrc nvm install 22 nvm use 22 node -v0.3 安装 Git、pnpm、Python（用户目录或 PATH 优先）
- Git：若系统已有且版本够用，可直接用；否则可从源码或官方包安装到
~/Applications/git，并将~/Applications/git/bin加入 PATH。- Corepack：pnpm 由 Node 自带的 corepack 管理，可执行文件在当前 Node 的 bin 目录里（与
node、npm同目录）。不会自动改你的 shell 配置：需要把 Node 的 bin 目录 加入 PATH（例如解压到~/Applications/node时加export PATH="$HOME/Applications/node/bin:$PATH"），pnpm才能用。若 Node 是系统包管理器或 nvm 装的，通常已配好 PATH；若是手动解压 Node，需自己在~/.zshrc里加 Node 的 bin。 - 独立脚本：默认安装到用户目录（如
~/.local/share/pnpm），脚本会在安装结束时把PNPM_HOME和对应 bin 写入~/.zshrc/~/.bashrc，即会自动配置 PATH；新开终端即可用。
- Corepack：pnpm 由 Node 自带的 corepack 管理，可执行文件在当前 Node 的 bin 目录里（与
- Python（可选）：部分构建/插件可能需要；可用 pyenv 安装到
~/.pyenv，或官方安装包指定用户目录，并将bin加入 PATH。
pnpm：在已安装 Node 的前提下，用 Corepack 或 独立脚本，均在用户目录下，不写系统目录：
corepack enable corepack prepare pnpm@latest --activate # 或：curl -fsSL https://get.pnpm.io/install.sh | sh -pnpm -v0.4 统一环境变量文件（控制权限与影响范围）
在用户目录下建一个仅本机使用的环境变量文件，所有 OpenClaw 与工具链相关变量集中在此，便于自启动与终端一致、全局把控。
创建并编辑（路径可自定，下面以 ~/.openclaw.env 为例）：
# ~/.openclaw.env — OpenClaw 与工具链环境（按需取消注释、修改路径） # 工具链 PATH（用户目录优先，避免动系统） export PATH="HOME/Applications/node/bin:PATH" # 若用 nvm，在 shell 配置里 source nvm 即可，此处可不写 PATH # OpenClaw 状态与配置（统一数据与日志到同一根目录） export OPENCLAWSTATEDIR="{OPENCLAW_STATE_DIR:-HOME/openclaw-data}" export OPENCLAWCONFIGPATH="{OPENCLAW_CONFIG_PATH:-OPENCLAWSTATEDIR/openclaw.json}" # 可选：Gateway 端口、Token 等 # export OPENCLAWGATEWAYPORT=18789 # export OPENCLAWGATEWAYTOKEN="your-token" `在 shell 配置中加载，使交互式终端与脚本使用同一套环境：
# 写入 /.zshrc （MAC系统） 或/.bashrc （Linux系统） if [ -f "$HOME/.openclaw.env" ]; thenset -a source "$HOME/.openclaw.env" set +a fi 之后新开终端即生效；自启动服务也会在下面第二节中通过 EnvironmentFile（systemd）或 EnvironmentVariables（launchd）加载同一文件，保证与终端一致、权限与影响范围可控。
.openclaw.env 与 .zshrc 的使用方式（是否需要每次加载）
方式说明
~/.openclaw.env： 只放环境变量（PATH、OPENCLAWSTATEDIR、OPENCLAWCONFIGPATH 等），供终端与守护进程共用。
~/.zshrc（或 /.bashrc）：Shell 配置：在这里写 `source/.openclaw.env`，并放补全、OpenClaw 命令补全等；不要把补全或 shell 命令写进 .openclaw.env。
需要每次都手动加载吗？不需要。 每次你新开一个终端，zsh 会自动执行.zshrc，里面的source ~/.openclaw.env会把环境变量加载好，无需再打source ~/.openclaw.env。守护进程（Gateway）：通过openclaw gateway install安装后，launchd/systemd 会在进程启动时读取环境（例如从 .openclaw.env），也是自动的。只有这两种情况需要手动执行一次source ~/.openclaw.env：
在当前已打开的终端里刚改过.openclaw.env，希望本终端立即生效；
在脚本里跑 openclaw，且该脚本不会读 .zshrc（例如 cron、某些 CI），需在脚本开头加source "$HOME/.openclaw.env"。
日常开新终端即可，环境变量会自动带上；改过 .openclaw.env 且想在本终端立刻生效时，再执行一次source ~/.openclaw.env。
0.5 初始化数据目录与统一 logs 目录
首次使用前创建状态目录并统一日志到 logs 子目录（便于排查）：
source ~/.openclaw.env # 若尚未在 shell 中加载 mkdir -p "$OPENCLAWSTATEDIR/logs" mkdir -p "$OPENCLAWSTATEDIR/workspace" # 配置文件可在 onboard 时生成，或事先创建空 JSON：echo '{}' > "$OPENCLAWCONFIGPATH" ` 说明： 守护进程（launchd/systemd）会把 Gateway 的 stdout/stderr 重定向到 $OPENCLAW_STATE_DIR/logs/gateway.log 和 gateway.err.log（见第二节）。若还需将 Gateway 的文件日志（JSONL）也落到同一 logs
