1. 为什么要把 OpenClaw 装到自定义目录OpenClaw 默认会把 CLI 和状态文件塞进~/.openclaw对大多数尝鲜用户来说够用。但如果你和我一样习惯把工具链按项目隔离——比如把机器人相关的东西统一放在~/J222_private_space或者某个挂载盘里——那默认路径就会变成麻烦备份脚本要单独排除、多版本共存会互相覆盖、磁盘配额也难管理。这篇就聚焦一件事在 Ubuntu 上把 OpenClaw 安装到自定义目录并且对照 openai official docs 那套配置骨架把config.toml的结构、路径参数、环境变量讲清楚。装完之后你能用openclaw config file确认配置生效用openclaw onboard --flow quickstart跑通初始化最后验证可执行文件和状态目录都落在你指定的位置。适合谁看已经在 Ubuntu 上折腾过 Node 工具链、想给 OpenClaw 做非默认目录部署的人或者你之前照着官方一行命令装完结果发现状态文件散落各处、想重新规划目录结构的。全程命令可直接复制路径按你自己的替换即可。先说清楚一个容易踩的坑--prefix是 OpenClaw 安装脚本的参数不是curl的参数。很多人写成curl ... --prefix ... | bash结果--prefix被 curl 吃掉脚本根本没收到最后还是装到默认目录。正确结构是curl 参数 URL | bash -s -- 脚本参数这个后面会用完整命令演示。2. 装之前先把 TaoToken 的 Key 和文档准备好OpenClaw 本身是运行框架真正干活要接模型。我这边习惯用 TaoToken 做统一入口一个 Key 覆盖对话、编码、Agent 几类场景省得每个工具单独配一遍。你可以在官网注册后进控制台创建 API Key地址是 https://taotoken.net/api-keys 创建完复制那串sk-开头的密钥后面写进config.toml。接入文档在 https://taotoken.net/doc 里面有 base_url 和模型名的对照表。OpenClaw 的配置骨架和 openai official docs 基本一致都是base_urlapi_keymodel三件套所以你把 TaoToken 的地址填进base_url字段就行不用改代码逻辑。如果你只是想先验证模型通不通可以直接开模型对话页面 https://taotoken.net/model-chat 发一句话试试要是打算长期跑编码或 Agent 任务建议看下 Coding Plan https://taotoken.net/coding-plan 额度模型更适合高频调用。API 根地址统一用 https://taotoken.net/api 注意这个不带任何查询参数写进配置时别多加斜杠。提示Key 只创建一次就够多个工具可以复用同一个。但别把 Key 直接提交到 Git建议用环境变量注入后面配置章节会给写法。3. 自定义目录安装的完整命令与参数说明3.1 先建目录再决定 prefix安装脚本不会帮你建父目录所以先手动创建。假设我要装到~/J222_private_space/.openclawmkdir -p $HOME/J222_private_space/.openclaw chmod 700 $HOME/J222_private_spacechmod 700是给私有空间收权限避免同机器其他用户读到你的状态文件。这一步不是必须但状态目录里会存会话和凭据收一下更稳妥。3.2 正确区分 curl 参数和脚本参数这是全文最关键的一行。错误写法# 错误示范--prefix 被 curl 当成自己的参数 curl -fsSL --proto https --prefix $HOME/J222_private_space/.openclaw --tlsv1.2 https://openclaw.ai/install-cli.sh | bash正确写法是把脚本参数放在bash -s --后面curl -fsSL --proto https --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix $HOME/J222_private_space/.openclaw --version latest结构拆解一下curl -fsSL --proto https --tlsv1.2 URL是下载部分| bash -s --表示把下载内容交给 bash 执行--之后的--prefix和--version才是传给安装脚本的。--prefix默认值是~/.openclaw你传了自定义路径它就按你的来--version latest拉最新版想锁版本就换成具体号。3.3 安装脚本参数对照参数作用默认值建议--prefix安装前缀目录~/.openclaw填你的自定义绝对路径--version指定版本latest生产环境锁具体版本--onboard安装后自动进初始化关闭想手动控制就省略安装过程会输出下载进度和落盘路径看到installed to ...字样就说明二进制已经进到你的 prefix 下的bin目录了。4. 配置 PATH 与状态目录让 openclaw 命令可用4.1 把 bin 加进 PATH装完直接敲openclaw大概率提示 command not found因为自定义目录不在 PATH 里。追加一行到~/.bashrcecho export PATH$HOME/J222_private_space/.openclaw/bin:$PATH ~/.bashrc source ~/.bashrc如果你用的是 zsh把~/.bashrc换成~/.zshrc。改完source一下当前会话立即生效新开终端也会自动加载。4.2 用 OPENCLAW_STATE_DIR 固定状态目录PATH 解决的是命令能不能找到状态目录解决的是配置和会话存哪。显式声明一下更清晰export OPENCLAW_STATE_DIR$HOME/J222_private_space/.openclaw export PATH$OPENCLAW_STATE_DIR/bin:$PATH同样写进~/.bashrc并source。这样即使以后 prefix 变了状态目录也能独立控制。4.3 确认配置生效openclaw config file这条命令会打印当前生效的配置文件绝对路径。如果输出指向你自定义目录下的config.toml说明 PATH 和状态目录都对上了。要是还指向~/.openclaw回头检查OPENCLAW_STATE_DIR有没有 export 成功。5. 对照 openai official docs 写 config.toml 骨架5.1 目录结构长什么样自定义安装后你的 prefix 下大致是这样$HOME/J222_private_space/.openclaw/ ├── bin/ │ └── openclaw ├── config.toml └── state/ ├── sessions/ └── logs/bin放可执行文件config.toml是主配置state存运行时会话和日志。对照 openai official docs 的配置习惯核心就是 provider、model、api_key 三段OpenClaw 的config.toml也沿用这个骨架。5.2 可复制的 config.toml 骨架# ~/J222_private_space/.openclaw/config.toml [provider] name taotoken base_url https://taotoken.net/api api_key sk-你的密钥 [model] default gpt-4o-mini fallback gpt-4o [agent] workspace /home/yourname/J222_private_space/workspace max_turns 20 [log] level info dir /home/yourname/J222_private_space/.openclaw/state/logsbase_url填 TaoToken 的 API 根地址api_key换成你控制台创建的那串。model.default按你实际能用的模型名填接入文档里有对照表。agent.workspace是 Agent 读写文件的根目录建议单独开一个别直接指到家目录。注意api_key明文写在 toml 里方便调试但生产环境建议改成读环境变量比如api_key ${TAOTOKEN_API_KEY}然后在~/.bashrc里 export 真实值。5.3 路径参数逐项说明base_url必须是根地址不要带/v1或结尾斜杠OpenClaw 会自己拼路径。workspace和log.dir都写绝对路径用~在某些版本里不展开。max_turns控制单次 Agent 任务的最大轮数调太小任务跑一半就断调太大又容易烧额度20 是个折中值。6. 验证安装可执行、配置、初始化三步走6.1 验证可执行文件which openclaw openclaw --versionwhich应该输出你自定义目录下的bin/openclaw--version打印版本号。两条都正常说明 PATH 配置没问题。6.2 验证配置读取openclaw config file openclaw config get provider.base_url第二条会回显你填的 base_url。如果报 key 不存在多半是 toml 段落名写错检查[provider]有没有拼对。6.3 跑初始化并验证模型连通openclaw onboard --flow quickstart这个流程会引导你选频道、确认模型、发一条测试请求。走到选择频道那步如果暂时只想验证模型可以先跳过其他软件接入直接让它发测试消息。返回 200 且能看到模型回复说明 Key 和 base_url 都通了。想单独测模型也可以开 https://taotoken.net/model-chat 发一句话对照两边结果一致就基本没问题。7. 本篇常见报错排查7.1 command not found: openclawPATH 没生效。先echo $PATH看有没有你的 bin 目录没有就回去检查~/.bashrc那行有没有写对然后source ~/.bashrc。注意source只影响当前终端已经开着的其他窗口要重新 source 或新开。7.2 装完还在 ~/.openclaw九成是--prefix被 curl 吃了。回去看第 3.2 节确认参数在bash -s --后面。另一个可能是你之前装过默认版本旧的状态目录还在openclaw config file读到了旧的手动删掉或改OPENCLAW_STATE_DIR指过去。7.3 config.toml 解析失败toml 对格式敏感字符串必须用双引号段落用[section]。常见错误是base_url结尾多了斜杠或者api_key忘了引号。用openclaw config get逐项读哪项报错改哪项。7.4 401 或模型不可用Key 错了或模型名不在你的可用列表里。先去 https://taotoken.net/api-keys 确认 Key 没被删再对照 https://taotoken.net/doc 的模型名。base_url 写成https://taotoken.net/api/带斜杠也会 401去掉结尾斜杠。7.5 Gateway 起不来初始化时如果提示 Gateway 服务没正常起来先别急着 hatch bot。用openclaw gateway status查状态再看state/logs下的日志。多数是端口被占或状态目录权限不对chmod 700收一下权限再重启。8. 后续接入与长期使用建议自定义目录部署跑通后你可以在config.toml里继续加频道配置把 OpenClaw 接到聊天软件里。每加一个频道就重启一次 Gateway用openclaw gateway status确认起来了再继续别一次改一堆配置再排查。长期跑编码或 Agent 任务的话建议把max_turns和日志级别调一下日志太详细会拖慢磁盘。Key 管理上如果你有多个工具共用统一在 https://taotoken.net/console 看用量避免某个脚本跑飞了烧额度。接入文档 https://taotoken.net/doc 里有各语言的调用示例OpenClaw 的 toml 字段和它一一对应遇到不确定的字段名直接翻文档比对。最后留一个实用习惯把~/.bashrc里那几行 export 单独抽成一个openclaw.env需要时source一下。这样换机器或重装系统配置迁移只要带走这个文件和config.toml状态目录整个拷过去就能接着用。