UNRAID 部署 OpenClaw 的正确方式

我在 UNRAID 上部署 OpenClaw 的时候，用的是社区应用商店（CA）里的模板。容器确实跑起来了，Web UI 也能打开，但很快就发现不对劲——配置文件改了不生效，workspace 目录始终是空的，插件系统也挂了。折腾了一下午才发现，CA 模板里有两个路径映射完全错了。

这篇文章记录从踩坑到解决的过程，如果你也是 UNRAID 用户，希望能帮你跳过这些坑。

症状：能跑，但残了

容器启动后，几个问题同时出现：

第一，插件列表报错。进容器执行 openclaw plugins list，直接提示无法读取配置。我当时以为是权限问题，改了文件权限再试，没用。

第二，workspace 目录始终为空。宿主机上映射的 /mnt/user/appdata/openclaw/workspace 什么都没有——没有 AGENTS.md，没有 skills/，没有 memory/。但容器明明在运行。

第三，修改 openclaw.json 后重启容器，配置回去了。改了几次都这样，像是每次启动都重新生成了一份空配置。这最让人抓狂——你明明改了文件，重启后它又回到初始状态。

这几个症状指向同一个方向：路径不对。

排查：两个路径映射错误

我进容器看了几样东西。

先看进程以什么用户运行：


docker exec openclaw ps aux | grep node

输出显示运行用户是 node，不是 root。再看 HOME 目录：


docker exec openclaw echo $HOME
# 空
docker exec openclaw cat /etc/passwd | grep node
# node:x:1000:1000::/home/node:/bin/bash

用户是 node（UID 1000），家目录是 /home/node。但 CA 模板的配置路径映射到了 /root/.openclaw。node 用户不读那个目录——它读的是 /home/node/.openclaw。所以你在宿主机改 /mnt/user/appdata/openclaw/config/openclaw.json，文件确实变了，但容器里的 node 进程根本看不到它，读的是容器层自己的 /home/node/.openclaw/，那里面是空的。

再加一个变量：


docker exec openclaw ls -la /home/node/.openclaw
# 空的，或者根本没有这个目录
docker exec openclaw ls -la /root/.openclaw
# 有文件，但没人读

第二个错误是 workspace 路径。CA 模板把 workspace 目标设成了 /home/node/clawd。这个路径在官方文档里根本不存在——OpenClaw 期望的工作目录是 /home/node/.openclaw/workspace。这是配置目录的子目录，不是独立路径。

官方 docker-compose.yml 的 volumes 定义也能印证：


volumes:
  - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
  - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace

workspace 在 .openclaw 下面，层级关系很明确。而 CA 模板用了 /home/node/clawd——这可能是旧版 OpenClaw 的路径，新版已经改了。

还有第三个问题，CA 模板的 PostArgs 里有一段脚本：


sh -c "mkdir -p /root/.openclaw /home/linuxbrew;
  [ -s /root/.openclaw/openclaw.json ] || echo '...' > /root/.openclaw/openclaw.json;
  exec node dist/index.js gateway --bind lan"

它在 /root/.openclaw 下生成 openclaw.json，然后启动网关。问题是这个路径 node 用户不会去读，所以每次重启你都能看到一个新的初始配置文件出现在 /root/.openclaw/ 里，而真正被读取的 /home/node/.openclaw/ 里什么都没有——或者有，但因为是容器层，重启就没了。

修正：改什么、怎么改

搞清楚根因之后，修正其实很简单。在 UNRAID 的 Docker 页面编辑容器参数：

Config Path Target：/root/.openclaw → /home/node/.openclaw

这是最关键的一步。把它改过来后，你在宿主机修改 openclaw.json，容器里的 node 进程就能读到了。

Workspace Path Target：/home/node/clawd → /home/node/.openclaw/workspace

改了之后容器重启，workspace 里就会正常生成 AGENTS.md、SOUL.md、skills/、memory/ 等文件。

添加环境变量：

变量	值	作用
`HOME`	`/home/node`	`node` 用户家目录，影响配置读取路径
`PUID`	`1000`	匹配容器内 `node` 用户 UID
`PGID`	`100`	匹配容器内 `node` 用户组 GID

HOME 是最容易被忽略的。不设这个变量，即使配置路径映射对了，某些依赖 $HOME 解析相对路径的场景仍然会翻车。

清空 PostArgs：把那段自动生成配置的脚本删掉。不需要它了——路径映射正确之后，用 onboard 命令交互式初始化，比脚本自动生成更可靠。

ExtraParams 保留 --user root：虽然 OpenClaw 以 node 用户运行，但容器入口需要 root 来做 Tailscale 初始化等操作。注意不要加 --hostname，这个参数在 UNRAID 的 Tailscale 集成下可能引起冲突。

Privileged 设为 true：UNRAID 环境下的权限模型需要这个。没有它，即使 PUID/PGID 设对了，某些系统调用也会失败。

Shell 从 sh 改为 bash：UNRAID Web UI 的容器控制台用 sh 时，PATH 环境变量加载不完整，openclaw、docker 等命令可能提示找不到。改成 bash 就正常了。

初始化：用 onboard 而不是脚本

改完模板参数后启动容器。启动后不要急着开 Web UI，先进容器控制台执行初始化：


openclaw onboard --install-daemon

这是一个交互式引导，会问你模型 API key、想连接哪些平台、工作区路径等。完成之后，检查几个东西：


# 检查 workspace 是否生成
ls /home/node/.openclaw/workspace/
# 应该能看到 AGENTS.md、SOUL.md、USER.md、MEMORY.md

# 检查插件
openclaw plugins list
# 应该列出已安装的插件

# 检查配置文件
cat /home/node/.openclaw/openclaw.json | head -20

宿主机上对应的目录也应该有相同的文件了。修改 openclaw.json 后重启容器，配置能够正确保存。

为什么不用 PostArgs 自动化初始化？因为 onboard 交互式流程会做几件事 PostArgs 做不了：检测已有的 auth profiles、提示安全警告、验证路径权限、生成合适的默认配置。你可以跳过不想填的项目，不会被自动生成的模板锁死。

修正后的 UNRAID 模板

以下是我最终生效的模板配置。如果你也是从 CA 模板起步，直接对照这个改就行：




  OpenClaw
  ghcr.io/openclaw/openclaw:latest
  bridge
  bash
  true
  --user root
  
  
  
  18789
  
  
  /mnt/disk1/appdata/openclaw/config
  
  
  /mnt/disk1/appdata/openclaw/workspace
  
  
  /home/node
  1000
  100
  
  
  
  
  
  true
  openclaw
  serve
  18789
  /mnt/disk1/appdata/openclaw/tailscale_state

跟 CA 原版模板的关键差异都在这几行里：

Target="/home/node/.openclaw" 替代了错误的 /root/.openclaw

Target="/home/node/.openclaw/workspace" 替代了废弃的 /home/node/clawd

HOME=/home/node 补充了缺失的家目录变量

Shell=bash 替代了残缺的 sh

Privileged=true 和 PUID/PGID 解决了 UNRAID 的权限问题

PostArgs 清空，改用 onboard 手动初始化

如果你已经用了旧模板

旧模板用了一段时间，工作区文件可能散落在两个位置。迁移步骤：


# 1. 停止容器
docker stop openclaw

# 2. 如果有旧配置在 /root/.openclaw，备份出来
docker exec openclaw tar czf /tmp/old-config.tar.gz /root/.openclaw
docker cp openclaw:/tmp/old-config.tar.gz ./

# 3. 修改容器参数（按上面的模板改）

# 4. 启动容器，执行 onboard 重新初始化
docker start openclaw
docker exec -it openclaw openclaw onboard --install-daemon

# 5. 把旧配置文件（如 auth-profiles.json）手动合并到新配置目录

最后

CA 模板的错误看起来是两个路径字符串，但它引发了一连串的问题：配置不生效、插件失效、workspace 空载。排错过程中比较浪费时间的是——容器能启动、Web UI 能打开，第一眼看上去是正常的，问题藏得比较深。

关键是记住三个数字：1000（node 用户 UID）、/home/node/.openclaw（配置目录）、/home/node/.openclaw/workspace（工作目录）。只要 UNRAID 的 Docker 参数里这三样对了，剩下的就是常见的容器调优。

另外推荐用 onboard 交互式初始化而不是靠脚本自动生成。它能检测已有配置、跳过已设置的项、在失败时给出明确提示。自动脚本看起来省事，但出问题时你都不知道它到底写了什么、写在了哪里。

附录

完整模板文件展示

模板 A：修正后的 UNRAID 模板（my-OpenClaw.xml）




  OpenClaw
  ghcr.io/openclaw/openclaw:latest
  https://github.com/openclaw/openclaw/pkgs/container/openclaw
  bridge
  
  bash
  true
  https://forums.unraid.net/topic/196865-support-openclaw-ai-personal-assistant
  https://github.com/openclaw/openclaw
  
  OpenClaw is a powerful AI assistant gateway that connects Claude and other LLMs to messaging platforms like Discord, Telegram, WhatsApp, and more. Features include file access, shell commands, web browsing, cron jobs, and a web-based Control UI.

To access the Control UI, add your token to the URL: http://YOUR-IP:18789/?token=YOUR-GATEWAY-TOKEN

For setup details and documentation, see: https://github.com/jdhill777/openclaw-unraid

OpenClaw project and source: https://github.com/openclaw/openclaw

Requires at least one LLM API key. Anthropic (Claude) is recommended, but many providers are supported.

Optional Homebrew: Some skills require tools installed via brew/go. This is completely optional and at your own discretion. If needed, open OpenClaw's container console and run:

NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

We recommend reviewing the install script at brew.sh before running. You can ignore the "Next steps" output - the template has already configured the PATH for you.
  Productivity: Tools:Utilities AI:
  http://[IP]:[PORT:18789]/
  https://raw.githubusercontent.com/selfhosters/unRAID-CA-templates/master/templates/openclaw.xml
  https://raw.githubusercontent.com/selfhosters/unRAID-CA-templates/master/templates/img/openclaw.png
  --user root
  
  
  1775638320
  
  
  
  18789
  /mnt/disk1/appdata/openclaw/config
  /mnt/disk1/appdata/openclaw/workspace
  /home/node
  18790
  1000
  100
  true
  false
  openclaw
  
  false
  false
  false
  serve
  https://[hostname][magicdns]/
  18789
  
  
  
  
  
  
  
  
  false
  /mnt/disk1/appdata/openclaw/tailscale_state

关键特征：

Config Path Target: /home/node/.openclaw

Workspace Path Target: /home/node/.openclaw/workspace

Environment Variables: HOME=/home/node, PUID=1000, PGID=100

PostArgs: 空

ExtraParams: --user root

Privileged: true

Shell: bash

---

模板 B：官方 Docker Compose 参考（docker-compose.yml）


services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
      OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: ${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}
      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-}
      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-}
      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-}
      TZ: ${OPENCLAW_TZ:-UTC}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
      ## Uncomment the lines below to enable sandbox isolation
      ## (agents.defaults.sandbox). Requires Docker CLI in the image
      ## (build with --build-arg OPENCLAW_INSTALL_DOCKER_CLI=1) or use
      ## scripts/docker/setup.sh with OPENCLAW_SANDBOX=1 for automated setup.
      ## Set DOCKER_GID to the host's docker group GID (run: stat -c '%g' /var/run/docker.sock).
      # - /var/run/docker.sock:/var/run/docker.sock
    # group_add:
    #   - "${DOCKER_GID:-999}"
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
    init: true
    restart: unless-stopped
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND:-lan}",
        "--port",
        "18789",
      ]
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))",
        ]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s

  openclaw-cli:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    network_mode: "service:openclaw-gateway"
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
      OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: ${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}
      BROWSER: echo
      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-}
      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-}
      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-}
      TZ: ${OPENCLAW_TZ:-UTC}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    stdin_open: true
    tty: true
    init: true
    entrypoint: ["node", "dist/index.js"]
    depends_on:
      - openclaw-gateway

参考要点：

volumes 映射逻辑：/home/node/.openclaw 与 /home/node/.openclaw/workspace

环境变量 HOME: /home/node 的定义位置

无 PostArgs 或 Entrypoint 覆盖，依赖镜像默认命令

---

模板 C：CA 市场原始模板（openclaw.xml）




  OpenClaw
  ghcr.io/openclaw/openclaw:latest
  https://github.com/openclaw/openclaw/pkgs/container/openclaw
  bridge
  sh
  false
  https://forums.unraid.net/topic/196865-support-openclaw-ai-personal-assistant
  https://github.com/openclaw/openclaw
  OpenClaw is a powerful AI assistant gateway that connects Claude and other LLMs to messaging platforms like Discord, Telegram, WhatsApp, and more. Features include file access, shell commands, web browsing, cron jobs, and a web-based Control UI.

To access the Control UI, add your token to the URL: http://YOUR-IP:18789/?token=YOUR-GATEWAY-TOKEN

For setup details and documentation, see: https://github.com/jdhill777/openclaw-unraid

OpenClaw project and source: https://github.com/openclaw/openclaw

Requires at least one LLM API key. Anthropic (Claude) is recommended, but many providers are supported.

Optional Homebrew: Some skills require tools installed via brew/go. This is completely optional and at your own discretion. If needed, open OpenClaw's container console and run:

NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

We recommend reviewing the install script at brew.sh before running. You can ignore the "Next steps" output - the template has already configured the PATH for you.
  Productivity: Tools: AI
  http://[IP]:[PORT:18789]/
  https://raw.githubusercontent.com/jdhill777/openclaw-unraid/master/openclaw-icon.png
  https://raw.githubusercontent.com/jdhill777/openclaw-unraid/master/screenshot.png
  --user root --hostname OpenClaw
  sh -c "mkdir -p /root/.openclaw /home/linuxbrew; [ -s /root/.openclaw/openclaw.json ] || echo '{\"gateway\":{\"mode\":\"local\",\"bind\":\"lan\",\"controlUi\":{\"allowInsecureAuth\":true},\"auth\":{\"mode\":\"token\"}}}' > /root/.openclaw/openclaw.json; exec node dist/index.js gateway --bind lan"
  Support the template maintainer
  https://buymeacoffee.com/jdhill777
  OpenClaw is a powerful AI assistant gateway that connects Claude and other LLMs to messaging platforms like Discord, Telegram, WhatsApp, and more. Features include file access, shell commands, web browsing, cron jobs, and a web-based Control UI. To access the Control UI, add your token to the URL: http://YOUR-IP:18789/?token=YOUR-GATEWAY-TOKEN

  
  18789

  
  /mnt/user/appdata/openclaw/config
  /mnt/user/appdata/openclaw/workspace
  /mnt/user/appdata/openclaw/projects
  /mnt/user/appdata/openclaw/homebrew

  
  

  
  
  
  
  
  
  
  

  
  

  
  
  

  
  18789
  /home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin:/root/.bun/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

问题点标注：

← 错误用户目录

← 错误路径名称与层级

字段包含复杂初始化逻辑，在错误路径生成配置

缺少 HOME、PUID、PGID 环境变量定义

sh ← 导致 Web UI 终端功能受限

---

菜单

分享

UNRAID 部署 OpenClaw 的正确方式

症状：能跑，但残了

排查：两个路径映射错误

修正：改什么、怎么改

初始化：用 onboard 而不是脚本

修正后的 UNRAID 模板

如果你已经用了旧模板

最后

附录

完整模板文件展示

模板 A：修正后的 UNRAID 模板（my-OpenClaw.xml）

模板 B：官方 Docker Compose 参考（docker-compose.yml）

模板 C：CA 市场原始模板（openclaw.xml）

OpenClaw 更新后 QQ Bot 失联始末：从一场迁移事故到架构演进的教训

qBittorrent Docker Host验证设置错误导致Web UI无法访问的解决方案

解决 Jupyter Lab systemd 服务启动失败（203／EXEC 错误）完整指南

UNRAID Docker中Plex播放ASS字幕失败并提示TPU错误的解决方案

UNRAID 与 Ubuntu 之间 NFS 共享配置完全指南

1panel忘记账户密码之后怎么重置

使用1panel的面板设置中的打开 SSL 功能，结果证书设置错误，无法打开1panel的管理面板网站

UNRAID 部署 OpenClaw 的正确方式

穿透内网访问qBittorrent时"Unauthorized"错误的根源与优雅解决方案

在UNRAID上为OpenClaw配置外置浏览器自动化服务