1. 为什么我劝你先搞懂 OpenClaw 的安装链路OpenClaw 是一个可以自己托管、自己掌控数据流向的智能体网关程序它能对接多种对话渠道、跑本地或云端模型、把工具调用和会话状态都收拢到你自己机器上。适合谁适合那些不满足于“网页里点一点”、想把 Agent 跑在自己 Linux 服务器或 Mac 上、并且希望开机就自动运行的人。但它的安装链路比一般 npm 包要长源码编译、环境变量、守护进程、配置文件校验任何一环出错都会让你卡在command not found或者 Gateway 起不来。我见过太多小白在这一步翻车Node 版本不对、openclaw命令找不到、自启动服务读不到环境变量、API Key 散落在各个配置文件里改一次崩一次。这篇就按 Linux macOS 两条线从源码编译讲到 systemd/launchd 自启动再重点解决 Key 管理这个高频坑——用 TaoToken 的统一 Key 接入让你只维护一份凭证配置骨架直接复制就能用。全程命令可复制报错有排查清单。你不需要是运维老手跟着敲就行。2. 前置准备环境、目录与 TaoToken 统一 Key2.1 环境要求与目录约定OpenClaw 源码构建要求 Node.js ≥ 22、pnpm、Git。我建议把工具链全装在用户目录下不污染系统路径权限也好控制。约定一个运行时目录~/Applications/ ├── node/ # Node.js 解压目录 ├── pnpm/ # 可选 └── python/ # 可选部分插件构建用数据与日志单独放一个目录由OPENCLAW_STATE_DIR指定~/openclaw-data/ ├── openclaw.json ├── logs/ │ ├── gateway.log │ ├── gateway.err.log │ └── openclaw.log ├── credentials/ └── workspace/2.2 安装 Node.js用户目录≥22方式 A官方二进制解压不依赖 rootmkdir -p ~/Applications/node cd ~/Applications # 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 export PATH$HOME/Applications/node/bin:$PATH node -v # 应 ≥ 22macOS ARM64 把文件名换成node-v22.12.0-darwin-arm64.tar.xz即可。方式 B 用 nvmNode 会落在~/.nvm/versions/node/下同样不写系统目录curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash source ~/.zshrc nvm install 22 nvm use 222.3 统一环境变量文件这是整篇的关键设计所有 OpenClaw 相关变量集中到一个文件终端和守护进程共用同一套避免“终端能跑、服务起不来”。# ~/.openclaw.env export PATH$HOME/Applications/node/bin:$PATH export OPENCLAW_STATE_DIR${OPENCLAW_STATE_DIR:-$HOME/openclaw-data} export OPENCLAW_CONFIG_PATH${OPENCLAW_CONFIG_PATH:-$OPENCLAW_STATE_DIR/openclaw.json}在 shell 配置里加载它macOS 写~/.zshrcLinux 写~/.bashrcif [ -f $HOME/.openclaw.env ]; then set -a; source $HOME/.openclaw.env; set a fi新开终端自动生效不用每次手动 source。只有两种情况需要手动执行一次刚改过.openclaw.env想让当前终端立即生效或者在 cron/CI 脚本里跑 openclaw脚本不读.zshrc。2.4 TaoToken 统一 Key 接入OpenClaw 支持配置多个模型提供商但如果你每个渠道、每个 Agent 都塞一份 Key改起来就是灾难。TaoToken 提供统一 Key一个凭证走所有模型调用配置里只维护一处。先去控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建后拿到形如sk-xxxx的 KeyAPI 基地址用https://taotoken.net/api注意 API 地址不带 UTM 参数直接写进配置即可。Key 建议不要硬编码进openclaw.json而是放进环境变量文件配置里引用变量名这样备份配置、分享骨架时不会泄露凭证。# 追加到 ~/.openclaw.env export TAOTOKEN_API_KEYsk-你的统一Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api想先验证 Key 是否可用可以直接在模型对话页试一条https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite3. 源码安装与可复制配置3.1 克隆与构建git clone https://github.com/openclaw/openclaw.git ~/Applications/openclaw cd ~/Applications/openclaw pnpm install pnpm ui:build pnpm buildpnpm build会生成dist/openclaw.mjs是官方入口脚本运行时会动态加载dist/entry.js。所以必须先 build 再跑否则入口找不到编译产物。3.2 让 openclaw 命令随处可用源码安装不会把openclaw装进系统 PATH新终端直接敲会报command not found。两种解法任选其一。自建 wrapper 并加入 PATHmacOS 示例mkdir -p ~/bin cat ~/bin/openclaw EOF #!/usr/bin/env bash exec node $HOME/Applications/openclaw/openclaw.mjs $ EOF chmod x ~/bin/openclawLinux 把路径换成$HOME/openclaw/openclaw.mjs放到~/.local/bin/openclaw并确保该目录在 PATH 里。或者在 shell 配置里加别名alias openclawnode /Users/你的用户名/Applications/openclaw/openclaw.mjs关键点全局命令要指向openclaw.mjs不要只把node_modules/.bin加进 PATH那样无效。3.3 config.toml / openclaw.json 骨架OpenClaw 的配置是 JSON5 格式支持注释和尾逗号路径由OPENCLAW_CONFIG_PATH决定。下面这份骨架把 TaoToken 统一 Key 接进去直接复制改路径即可{ // 网关基础 gateway: { port: 18789, bind: loopback, auth: { mode: token, token: 换成你自己的网关token }, reload: { mode: hybrid } }, // 模型提供商统一走 TaoToken models: { providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: [claude-sonnet-4-5, gpt-4o] } }, default: taotoken/claude-sonnet-4-5 }, // 智能体默认工作区 agents: { defaults: { workspace: ~/openclaw-data/workspace, model: taotoken/claude-sonnet-4-5 } }, // 日志统一到 state 目录 logging: { file: ~/openclaw-data/logs/openclaw.log, level: info } }${TAOTOKEN_API_KEY}这种写法让配置引用环境变量Key 只存在.openclaw.env里。改 Key 只改一处所有 Agent 和渠道同步生效。3.4 初始化数据目录并引导source ~/.openclaw.env mkdir -p $OPENCLAW_STATE_DIR/logs $OPENCLAW_STATE_DIR/workspace pnpm openclaw onboard --install-daemon--install-daemon会顺带装好自启动服务下面第二节展开。4. 自启动配置与验证4.1 安装守护进程source ~/.openclaw.env openclaw gateway install已安装时重复执行是无操作要重写单元文件用--force。安装前务必先 source 环境文件这样生成的 plist/systemd 单元会带上相同的OPENCLAW_STATE_DIR日志才会落到你期望的 logs 目录。4.2 macOSlaunchd安装结果是用户级 LaunchAgent路径~/Library/LaunchAgents/bot.molt.gateway.plist。常用命令openclaw gateway status openclaw gateway restart launchctl kickstart -k gui/$UID/bot.molt.gateway注意 LaunchAgent 依赖已登录图形会话无头服务器需要自建 LaunchDaemon。4.3 Linux / WSL2systemd 用户服务单元文件在~/.config/systemd/user/openclaw-gateway.service。示例内容[Unit] DescriptionOpenClaw Gateway Afternetwork-online.target Wantsnetwork-online.target [Service] EnvironmentFile%h/.openclaw.env ExecStart/home/你的用户名/bin/openclaw gateway --port 18789 Restartalways RestartSec5 WorkingDirectory%h StandardOutputappend:%h/openclaw-data/logs/gateway.log StandardErrorappend:%h/openclaw-data/logs/gateway.err.log [Install] WantedBydefault.target启用并验证sudo loginctl enable-linger $USER systemctl --user daemon-reload systemctl --user enable --now openclaw-gateway.service systemctl --user status openclaw-gateway.serviceenable-linger让服务在你登出后仍运行新手引导会尝试执行它。4.4 验证请求成功服务起来后先看状态再发一条真实请求openclaw gateway status openclaw health openclaw logs --followgateway status会区分两件事监管程序launchd/systemd是否在跑以及 Gateway RPC 是否可达。两个都绿才算真正成功。然后通过模型对话页发一条消息确认 TaoToken 统一 Key 生效https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite如果返回正常内容说明从源码编译到自启动再到 Key 接入整条链路通了。5. 常见报错排查清单5.1 command not found: openclaw源码安装没配 PATH。用pnpm openclaw ...在源码目录跑或按 3.2 建 wrapper/别名。别只加node_modules/.bin。5.2 Gateway 拒绝启动提示配置校验失败配置不符合内置 schema未知键或类型错误都会导致拒启。此时只允许诊断命令openclaw doctor openclaw doctor --fix5.3 自启动服务读不到环境变量systemd 单元里EnvironmentFile路径写错或安装前没 source。检查%h/.openclaw.env是否存在OPENCLAW_STATE_DIR是否和日志路径一致。5.4 pnpm install 中途失败cd ~/Applications/openclaw rm -rf node_modules pnpm store prune pnpm install保留pnpm-lock.yaml按锁定版本解析成功率更高。若是 postinstall 脚本被拦执行pnpm approve-builds -g勾选后重装。5.5 端口冲突Gateway 端口优先级是--portOPENCLAW_GATEWAY_PORTgateway.port 默认 18789。多实例时每个 profile 要有唯一端口、唯一 state 目录、唯一 workspace。5.6 日志找不到守护进程 stdout/stderr 在$OPENCLAW_STATE_DIR/logs/gateway.logGateway 文件日志由logging.file决定。排查时只看 logs 目录即可Linux 还能用journalctl --user -u openclaw-gateway.service -n 200 --no-pager。6. 长期编码与 Agent 场景的 Key 管理如果你打算把 OpenClaw 当长期编码助手或跑常驻 AgentKey 的稳定性和额度管理比一次性接入更重要。TaoToken 的 Coding Plan 适合这种持续调用的场景统一 Key 不用频繁轮换https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite需要新建或轮换 Key 时去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你用 Claude Code 这类工具配合 OpenClawAnthropic 兼容接入的说明在这里https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite我自己的做法是.openclaw.env只放 Key 和路径openclaw.json用变量引用自启动单元用EnvironmentFile加载同一个文件。这样无论终端、systemd 还是 launchd读到的都是同一份凭证改 Key 只动一行重启服务即可。踩过的坑基本都集中在“环境变量没对齐”和“命令没进 PATH”这两类把这两点理顺剩下的就是复制粘贴。