OpenClaw Linux 与 macOS 源码安装、自启动与基础配置手册

方式 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 -v

0.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；新开终端即可用。
• 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 -v

0.4 统一环境变量文件（控制权限与影响范围）

在用户目录下建一个仅本机使用的环境变量文件，所有 OpenClaw 与工具链相关变量集中在此，便于自启动与终端一致、全局把控。

创建并编辑（路径可自定，下面以 ~/.openclaw.env 为例）：

# ~/.openclaw.env — OpenClaw 与工具链环境（按需取消注释、修改路径）
# 工具链 PATH（用户目录优先，避免动系统）
export PATH="$HOME/Applications/node/bin:$PATH"
# 若用 nvm，在 shell 配置里 source nvm 即可，此处可不写 PATH
# OpenClaw 状态与配置（统一数据与日志到同一根目录）
export OPENCLAW_STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/openclaw-data}"
export OPENCLAW_CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-$OPENCLAW_STATE_DIR/openclaw.json}"
# 可选：Gateway 端口、Token 等
# export OPENCLAW_GATEWAY_PORT=18789
# export OPENCLAW_GATEWAY_TOKEN="your-token"

在 shell 配置中加载，使交互式终端与脚本使用同一套环境：

# 写入 ~/.zshrc （MAC 系统）或 ~/.bashrc （Linux 系统）
if [ -f "$HOME/.openclaw.env" ]; then
    set -a
    source "$HOME/.openclaw.env"
    set +a
fi

之后新开终端即生效；自启动服务也会在下面第二节中通过 EnvironmentFile（systemd）或 EnvironmentVariables（launchd）加载同一文件，保证与终端一致、权限与影响范围可控。

.openclaw.env 与 .zshrc 的使用方式

• ~/.openclaw.env：只放环境变量（PATH、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH 等），供终端与守护进程共用。
• ~/.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：

1. 在当前已打开的终端里刚改过 .openclaw.env，希望本终端立即生效；
2. 在脚本里跑 openclaw，且该脚本不会读 .zshrc（例如 cron、某些 CI），需在脚本开头加 source "$HOME/.openclaw.env"。

日常开新终端即可，环境变量会自动带上；改过 .openclaw.env 且想在本终端立刻生效时，再执行一次 source ~/.openclaw.env。

0.5 初始化数据目录与统一 logs 目录

首次使用前创建状态目录并统一日志到 logs 子目录（便于排查）：

source ~/.openclaw.env # 若尚未在 shell 中加载
mkdir -p "$OPENCLAW_STATE_DIR/logs"
mkdir -p "$OPENCLAW_STATE_DIR/workspace"
# 配置文件可在 onboard 时生成，或事先创建空 JSON：
echo '{}' > "$OPENCLAW_CONFIG_PATH"

说明：守护进程（launchd/systemd）会把 Gateway 的 stdout/stderr 重定向到 $OPENCLAW_STATE_DIR/logs/gateway.log 和 gateway.err.log（见第二节）。若还需将 Gateway 的文件日志（JSONL）也落到同一 logs 目录下。