OpenClaw 在 Linux 和 macOS 系统下的手动安装流程、自启动配置及基础环境设置。主要内容包括：在用户目录下安装 Node.js、Git、pnpm 等依赖，避免污染系统路径；通过环境变量文件统一管理 OpenClaw 的状态目录、配置路径及工具链变量；配置 systemd 或 launchd 实现开机自启；以及初始化数据目录和日志目录。旨在帮助用户实现对安装环境的完全掌控，便于权限管理与故障排查。
本文涵盖环境准备、源码安装、自启动配置与基础配置要素说明，以及可能遇到的问题总结，适合喜欢全盘掌控自己管理程序安装的小伙伴，其中包含 macOS 和 Linux 系统操作说明。
核心安装和初始化命令：
# 一键快速安装 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 相关变量，以便控制权限和影响范围，避免污染系统路径、便于全局把控与排查。
在用户目录下单独划一块'运行时/工具'目录，例如：
~/Applications/ # 或 ~/.local、~/openclaw-env 等，任选其一统一即可
├── node/ # Node.js 安装目录
├── git/ # 可选：Git 独立安装
├── pnpm/ # 可选：pnpm 独立安装时的 store 等
└── python/ # 可选：Python 运行时（部分插件/构建可能用到）
OpenClaw 运行数据与日志单独放到一个'数据目录'，便于备份与排错：
~/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 指定
└── ...
方式 A：官方二进制解压到用户目录（不依赖 root）
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="$HOME/Applications/node/bin:$PATH"
node -v # 应 ≥ 22
npm -v
方式 B：nvm / fnm（推荐，便于多版本，如果不用多版本不需要安装） nvm 和通过 nvm 安装的 Node 都在用户目录下，不写系统目录、无需 root：
~/.nvm/（安装脚本默认即如此）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
~/Applications/git，并将 ~/Applications/git/bin 加入 PATH。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；新开终端即可用。~/.pyenv，或官方安装包指定用户目录，并将 bin 加入 PATH。pnpm：在已安装 Node 的前提下，用 Corepack 或 独立脚本，均在用户目录下，不写系统目录：
corepack enable
corepack prepare pnpm@latest --activate
# 或：curl -fsSL https://get.pnpm.io/install.sh | sh -pnpm -v
在用户目录下建一个仅本机使用的环境变量文件，所有 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：只放环境变量（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：
- 在当前已打开的终端里刚改过
.openclaw.env，希望本终端立即生效；- 在脚本里跑 openclaw，且该脚本不会读
.zshrc（例如 cron、某些 CI），需在脚本开头加source "$HOME/.openclaw.env"。日常开新终端即可，环境变量会自动带上；改过
.openclaw.env且想在本终端立刻生效时，再执行一次source ~/.openclaw.env。
首次使用前创建状态目录并统一日志到 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 目录下。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online