OpenClaw 容器化Docker 安装部署教程适配任意类似飞牛等NAS系统环境

枫影 · 昨天 21:58

编者：枫影

前言：

默认NAS系统为飞牛（其他例如群晖等NAS系统大同小异，以下内容基本通用）
几个优势：
linuxserver.io也算是互联网界比较有名气的组织了，在此平台上部署你的龙虾不用担心里面有不知名的后门或木马（提醒各位，谨慎为上）
及做到了完整的root权限的龙虾，能升级能更新可持续，又起到了隔离的效果，龙虾只能在debian环境内活动，编辑的文件和目录均映射出来方便操作
就算龙虾被养挂了，只要.openclaw目录内的内容均在，就可以重新启动个容器从头来过，起到原地满血复活的效果

一、制作容器

在你的NAS的管理界面内，找个准备放置openclaw容器的目录，例如：debian-openclaw
目录内新建两个容器配置文件：.env和docker-compose.yml

变量文件：.env

OPENCLAW_IMAGE=alpine/openclaw:latest
#OPENCLAW_IMAGE=alpine/openclaw:2026.3.22
#OPENCLAW_IMAGE=alpine/openclaw:2026.2.19
#OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest
OPENCLAW_GATEWAY_TOKEN=换成你的 #推荐使用openssl rand -hex 32生成
OPENCLAW_GATEWAY_BIND=lan
#OPENCLAW_GATEWAY_BIND=127.0.0.1
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790

OPENCLAW_CONFIG_DIR=./.openclaw
#OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=./.openclaw/workspace

#gmail的认证
GOG_KEYRING_PASSWORD=换成你的
#指定目录
XDG_CONFIG_HOME=/home/node/.openclaw

容器配置文件：docker-compose.yml

services:
  debian-openclaw:
    image: lsiobase/debian:trixie-version-1b7f8754 #伟大的linuxserver.io官方的debian镜像
    #restart: unless-stopped
    restart: always
    container_name: debian-openclaw
    #user: '1000:1001' #还在研究，暂不使用
    env_file:
      - .env #读取.env文件内的变量定义

    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - OPENCLAW_GATEWAY_MODE=local
      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - TZ=Asia/Shanghai
      - PGID=999 #根据你自己NAS内的id改变
      - PUID=999 #根根据你自己NAS内的id改变
      #- LANGUAGE=zh_CN.UTF-8
      #- LANG=zh_CN.UTF-8
      #这条命令是让容器构建时额外安装的包，一些apt-get需要装的包就可以写入，终于找到这个了
      #- OPENCLAW_DOCKER_APT_PACKAGES=ffmpeg build-essential pip vim git curl jq
      #这条命令是增加openclaw支持的扩展插件，只支持openclaw支持的插件，也就是list出来的
      #- OPENCLAW_EXTENSIONS=clawhub mcporter stock-sdk-mcp caiyun-weather markitdown-skill
      - CAIYUN_WEATHER_API_TOKEN=换成你的 #彩云天气的token
      - DEEPSEEK_API_KEY=换成你的 #deepseek的api key
      - TAVILY_API_KEY=换成你的 #超牛的tavily搜索的api key
      - Z_API_KEY=换成你的 #智普的
      - OPENROUTER_API_KEY=换成你的 #openrouter的key 有居多free的模型随便用
      #其他一些配置
      #clawhub login --token 换成你的

    volumes:
      - ./config:/config #配置文件目录，有用，例如我就将whisper_model模型提前下载好存入该目录
      - ./.openclaw:/home/node/.openclaw #openclaw的配置存储目录
      - ./workspace:/home/node/.openclaw/workspace #openclaw的工作空间目录
      - ./custom-cont-init:/custom-cont-init.d:ro #伟大的linuxserver.io镜像的特有机制，系统重启自动执行该目录下脚本，自由发挥
      - ./custom-services:/custom-services.d:ro #镜像的特有机制，系统重启自动运行该目录下服务，可以理解为systemd的服务自启动，自己自由发挥

#开放两个端口，一个http另一个https的。如果完全不需要web界面和模式可以完全屏蔽掉，自己按需配置
    ports:
      # 推荐：在 VPS 上保持 Gateway 网关仅限 loopback；通过 SSH 隧道访问。
      # 要公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
      #- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
      - ${OPENCLAW_GATEWAY_PORT}:18789
      - ${OPENCLAW_BRIDGE_PORT}:18790

#以下均是官方容器研究所用，均屏蔽掉
     #command: supervisord -c /etc/supervisor/supervisord.conf
     #command: openclaw gateway run
     #command: openclaw gateway run --bind ${OPENCLAW_GATEWAY_BIND} --port ${OPENCLAW_GATEWAY_PORT}
#    command: openclaw gateway start --bind ${OPENCLAW_GATEWAY_BIND} --port ${OPENCLAW_GATEWAY_PORT}
#    command: node dist/index.js gateway --bind ${OPENCLAW_GATEWAY_BIND} --port ${OPENCLAW_GATEWAY_PORT}
#    command: node openclaw.mjs gateway --bind ${OPENCLAW_GATEWAY_BIND} --port ${OPENCLAW_GATEWAY_PORT}
#    command: node openclaw.mjs gateway --bind ${OPENCLAW_GATEWAY_BIND} --port ${OPENCLAW_GATEWAY_PORT} --allow-unconfigured
#    command: node dist/index.js gateway --bind ${OPENCLAW_GATEWAY_BIND} --port ${OPENCLAW_GATEWAY_PORT} --allow-unconfigured

    # 资源限制
    deploy:
      resources:
        limits:        # 【上限】容器最多能使用的资源量（硬限制）
          cpus: '4.0'  # 最多使用4个CPU核心，每0.5一档
          memory: 8G   # 最多使用8G内存
        reservations:  # 【预留】保证容器至少能获得的资源量（软限制）
          cpus: '0.25' # 保证至少25%的CPU核心
          memory: 512M # 保证至少512MB内存

#networks:
#  openclaw:
#    driver: bridge

新建以下目录，与上述容器配置文件内的volumes容器目录映射对应：

config
.openclaw
workspace
custom-cont-init
custom-services

在飞牛NAS的管理界面上，打开Docker管理界面
954

点击Compose，点击新增项目，取个名称，例如openclaw，选择项目目录如：debian-openclaw，会自动提示导入文件，完成。
构建，等完成并自动启动，至此，一个用于跑openclaw的debian系统环境就完成了，容器内，安全可控，完美。

二、配置容器内debian系统环境

两种方式：

方式一直接可以使用docker管理界面自带的bash进行操作；
824
方式二就是开启飞牛的ssh端口，使用终端应用登录至飞牛os内，执行下列命令进入搭建好的容器debian系统，教程默认采用方式二。
顺便力荐：Netcetty，开源，免费，还带云同步，简直神器了。
开源地址：binaricat/Netcatty: SSH workspace, SFTP, and terminals in one
811

进入容器（需要先SSH入飞牛NAS，然后用 sudo -i 切换至root权限）
docker exec -it debian-openclaw /bin/bash
容器内的debian系统默认就是root用户（最高权限）因此下面均不需要sudo

安装应用和依赖包

执行命令
apt-get update
apt-get install pipx curl git sudo python3-pip python3-venv ffmpeg build-essential vim tesseract-ocr jq
注释：
pipx是替代pip的包安装应用，为什么用它替代后面会解释；python3的开发环境、ffmpeg等很多场景需要用到的包

如需要数据分析，继续安装数据分析包（股票、数据分析、表格处理等必装）
apt-get install python3-pandas

手动安装Node.js 24版本（否则默认安装的是22的版本，太低了）

执行命令
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
apt-get install -y nodejs

补全debian的中文环境和中文字体

执行命令
apt-get install locales locales-all fonts-wqy-microhei fonts-wqy-zenhei fonts-noto-cjk

注释：
否则，openclaw读取中文文件会提示乱码，且shell界面中文也是乱码，无法正常显示。
上述命令除了node.js外，其他均可以全部合并在一起，只不过如此安装时间会很长，自行安排。

调出语言配置界面

dpkg-reconfigure locales
输入中文语言编号，例如323
默认中文语言环境，例如3

安装自选应用包

==特别注释：==
python3.11之后的版本，为了避免pip安装影响系统apt的应用依赖库，因此使用pip安装，绝大多数应用都会遇到【error: externally-managed-environment】的错误提示，直接被系统拒绝，并给了三个方案。方案一，先用apt install python3-你的包，看是否有系统级别的编译版本。如果没有包，则方案二，创建venv虚拟环境，虚拟环境内pip安装，但这样太麻烦；方案三，pip安装包的命令最后面加参数--break-system-packages强制安装，但这样很容易导致整个系统依赖出问题；优选，方案四，使用pipx安装，也就是前面提到的为什么要提前安装pipx包的原因。

说人话：就是你准备安装某包时，先使用apt-get install python3-某包，如果提示没有，再用pipx install 某包，即可。

以下是我提前安装的应用包，用于范例

微软官方markitdown工具（可将docx等一票文档转换为md、txt等，带ocr功能）
执行命令
pipx install 'markitdown[all]'
==特别注释：==
第一次使用了pipx后，需要修复一下路径，该命令执行一次即可
pipx ensurepath
注释：
自动的，意思就是把 '/home/node/.local/bin' 加入到了$PATH变量内，每次启动路径对了，就可以直接用装好的python应用，不会出现找不到的情况。
修复完毕，退出你当前的shell界面（或bash界面），建议再重启一下容器，让系统变量等全部更新。
openai的本地版语音转文字工具
pipx install openai-whisper
安装完毕后，需要手动执行一次该应用，因为需要应用自动下载语言模型。首先，找个语音文件，保存到/config目录（前面再三提到过的映射的目录）。容器内切换至/config目录，执行以下命令：
whisper "/config/你的语音文件.mp3" --model turbo --language zh --output_format md --output_dir . --model_dir /config/whisper_model --device cpu --fp16 False
注释：

上述命令分别对应的是：语音文件、模型名字、语音所属语言、输出文件格式、输出目录、模型目录、禁用CPU FP16（被禁则自动使用FP32加速）
命令模型目录内是真有模型（我提前下载好的）。如果你从来没下载过，则删除--model_dir参数，应用会自动下载模型至/tmp/whisper_cache/目录内，事后你拷贝到/config/自己目录保存就好。
默认用turbo模型（1.5G），6G内存4核CPU就行，硬件要求高但识别率也高，力推。什么？！你用ARM跑飞牛？那你老实用base模型（138M）吧。

三、容器系统内安装openclaw

执行官方安装脚本，不自动执行配置

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

手动配置openclaw

openclaw onboard --install-daemon
注释：

==重点提醒下，在skills环节，一定要把clawhub和mcpoter两个服务用空格选上安装，安装方式选择npm，绝大部分场景都需要这两个服务！==
具体配置流程啥啥啥的此教程不赘述，网上大把
安装完成后会看到openclaw提示gateway不能以systemd服务安装，正常现象，具体看最下面的解释和注意事项。
配置完毕，各种文件会自动生成，至此openclaw安装完成。

配上几个技能，都是我常用的

技能官方安装命令：
openclaw skills install 技能名
技能名：

skill-vetter
markitdown-skill
caldav-calendar
caiyun-weather
注释：

都干嘛用的不说了，自行搜索
安装时如遇429限流（clawhub经常限流），则需要去clawhub.ai上注册个账号，并拿到你账号的token，然后用以下命令登录clawhub即可。至此，以后的安装或update均不会再429限流了，登录命令：clawhub login --token 你的token值

修复.openclaw/workspace目录的映射（很重要）

注释：为什么这么做？由于刚刚安装的openclaw会生成配置文件和工作区文件，两者是嵌套的目录环境，但对于容器却是两个不同的目录（当然你也可以用同一个目录，但这样以后文件多了很难管理），通过这种方式手动修复一下，确保容器的目录挂载正常。

第一步： exit退出容器shell，停止容器，在飞牛的文件夹管理界面下，将.openclaw/workspace目录内容，全部剪切，粘贴到容器目录的workspace目录内
第二步： 再次启动容器（今后新生成的文件或目录，会根据容器的目录映射保存）

- [ ] 安装股票分析能力

服务应用开源地址：https://github.com/chengzuopeng/stock-sdk-mcp
全局安装：
npm install -g stock-sdk-mcp
安装后可直接运行 stock-mcp 命令。然后，告诉你的虾：
我给你安装了stock-mcp服务，这是个股票分析、行情监测等综合性股票服务。以小米股票为例，调用stock-mcp服务，查询、分析小米股票近日情况，并学习这个服务的技能及用法，保存为你的技能。
你的虾会很听话的搞定，OK，万事大吉。
不安装，通过npx调用：

配置mcp服务
mcpoter config add stock-mcp
编辑/config/mcpoter.json文件为以下内容

{
  "mcpServers": {
      "stock-mcp": {
        "command": "npx",
        "args": ["-y", "stock-sdk-mcp"]
    }
  },
  "imports": []
}

同样的，告诉你的虾上述内容。

- [ ] 安装语音转文字能力

教程上述部分已经安装好了【openai-whisper】，且下载了语言模型。告诉你的虾：
记住，如需调用whisper命令进行语音转文字，使用如下命令格式：
whisper "语音文件" --model turbo --language zh --output_format md --output_dir “输出目录” --model_dir /config/whisper_model --device cpu --fp16 False
注释：必须给虾规定好whisper应用的调用方式，否则openclaw既不默认中文语言，且会自动给你下载模型。

- [ ] 安装文档转换能力

教程上述部分已经安装好了【markitdown】应用和用于调用该应用的【markitdown-skill】技能
因此，告诉你的虾：
我给你安装了markitdown-skill技能，学习该技能用法，今后就用该技能转换文档。

- [ ] 安装语音对话能力（也就是TTS、语音转文字和文字转语音）

写累了，以后补充：）

四、正式投入生产环境

配置自动启动服务

在容器目录的custom-services目录下，新建文件
文件名：openclaw-root

#!/usr/bin/with-contenv bash

openclaw gateway run

注释：我的docker-compose.yml配置文件内就已经写了注解，linuxserver.io封装的debian环境，这两个目录内一个放需要自动启动的服务，另一个【custom-cont-init】放需要自动启动的脚本。因此之前为何提出根本不需要systemd自启服务就是这个原因，完全不需要，这种方式更加的灵活，也就是说，你再启动容器时，可以把任意你需要自动启动的服务和脚本分别放入。通过这种方式启动的openclaw，可以很直观的看到运行的信息，既便于调试，也便于监测，完美。
798

平时文件管理

.openclaw目录
注释：该目录虽然有workspace目录，单已经做了映射修复，因此该目录是空的。
793
workspace目录
820

==特别注释：平时需要启动和停止openclaw，直接停止容器即可。==

需要安装新的应用或包，可直接用容器的终端机操作，简直不要太方便，如下图：

955

我要更新openclaw了怎么办？

直接上图执行：openclaw update，搞定。是不是很方便。

该容器一经制作投入运行就不需要再动它了。只要不让你的虾乱来（例如执行exec等命令瞎干活啥的）。

五、其他事项

记录一些本人还在研究的一些事情。

初始化龙虾的常规动作

操作文档转换，告诉你的龙虾：

在我的工作区的"我的文档/待转换文档"目录内有一些docx文件，使用markitdown-skill技能转换为md文档，并存储到该目录下的"已完成"目录内。

关于龙虾的分层记忆逻辑，避免龙虾以后记忆错乱，告诉你的龙虾：

以后都按照以下逻辑分层记忆。  
分层记忆：  
1、MEMORY.md只放长期有效的信息（用户偏好、决策原因、失败教训），关键原则：只记为什么和教训，不记做了什么。  
2、每日记录放入memory/YYYY-MM-DD.md，完整保留最近7天。  
3、7天后至30天内的记录只保留“关键决策和教训”，压缩成 SUMMARY.md，删除执行日志。  
4、30天后的记录只存索引（日期+关键词），正文移到archive/，保留30天后删除。

其他欢迎补充

使用龙虾干活的场景

会议纪要

我是飞牛的NAS，自带webdav，并通过私人域名，把很多服务均已经域名发布。自然，我的手机的mix文件管理应用，能够直接访问飞牛某文件夹。我是通过飞书与我的虾交流的。适用场景自然就成了：开会时，用手机将会议录音，将录音文件mp3（也可能是其他）通过mix文件，存到虾自己的工作目录下，通过飞书告诉虾，将工作目录下的这个录音文件转换为文字，整理为会议纪要。将该纪要保存为md文件，存到/会议纪要/目录内，并发给我。

欢迎补充

关于文件权限的事情

注释：

能看到，文件和目录所属均是root，虽然不影响使用，但看着别扭。其实linuxserver.io的容器有完备的权限修复及继承机制（例如官方封装的freshrss、nextcloud等容器保存的文件均能完美与NAS用户对应），只是我还没完全掌握，下面是部分研究成果，目的就是做到保存的文件均与你NAS当前用户一致。
容器内有个abc的用户，该用户就是与容器配置的PUID PGID一一对应的存在。除非是通过abc用户执行openclaw gateway run，否则，默认root执行的一旦修改过文件或目录，所属者会自动变为root。
我做了以下事情，首先，修复一下目录权限：
设置共享组

groupadd shared
usermod -aG shared abc
usermod -aG shared root

lsiown -R abc:shared /home/node/.openclaw
chmod -R 775 /home/node/.openclaw
chmod g+s /home/node/.openclaw

注释：

/home/node/.openclaw这个目录，就是容器已经映射的目录，对应你的NAS的目录。
abc就是容器PUID的对应用户，也就是说，任何用abc创建的文件，在容器内是abc用户的权限，在NAS内是你NAS系统ID的PUID权限。
lsiown和chown的区别。lsiown就是重新封装的chown命令，是linuxserver.io封装镜像的特有命令，更好的修复目录权限。
将上述命令写成脚本，放入容器【custom-cont-init】脚本目录，每次启动均会自动修复一次权限：
脚本名：99-fix-openclaw

#!/bin/bash
# 这个脚本会在容器启动时自动执行
# 修正所有权为 abc 用户
lsiown -R abc:shared /home/node/.openclaw

# 可选：设置 SGID，让新建文件继承组
chmod g+s /home/node/.openclaw

删除之前在服务自启目录创建的文件openclaw-root，重新创建一个文件（直接修改内部命令也可以）：
文件名：openclaw-abc

#!/usr/bin/with-contenv bash

s6-setuidgid abc openclaw gateway run

注释：

【s6-setuidgid】是linuxserver.io封装的特有命令，意在切换当前用户为abc用户，让你的openclaw进程以abc用户运行（来执行目标服务），如此保存的文件自然也是abc的继承权了。这样权限对等puid参数。
我亲测过，只要openclaw不涉及root类权限的操作，就不会有任何问题。当然，还没做到linuxserver官方封装的效果，还需研究。

关于openclaw官方镜像

官方镜像，默认是node的用户，如果需要安装依赖包等，则需要root权限，通过以下方式解决：
docker exec -it --user root openclaw-gateway /bin/bash

关于systemd自启服务

之前就提到，安装openclaw完毕后会提示systemd服务未启动，自然，openclaw gateway start命令也不能运行。
错误原因：
1、systemctl --user命令需要D-Bus总线支持
root用户环境下默认没有用户级D-Bus总线，导致无法连接到用户级systemd服务。
2、OpenClaw的设计机制
openclaw gateway install/restart等命令内部使用systemctl用户服务，需要用户级别的systemd总线支持。
三个选择：

选1-可以参考该文修复systemd服务：
OpenClaw部署Gateway报错：Failed to connect to bus-腾讯云开发者社区-腾讯云
但我觉得实在没有这个必要，因为本质上仍然执行的是openclaw gateway run命令，相较于上述的自启服务不香么？！
选2-也可以安装supervisor服务

# 安装 supervisor
apt-get install -y supervisor

# 创建 supervisor 配置
[program:openclaw-gateway]
command=/usr/bin/openclaw gateway run
autostart=true
autorestart=true
stderr_logfile=/var/log/openclaw-gateway.err.log
stdout_logfile=/var/log/openclaw-gateway.out.log

# 启动 supervisor
supervisord -c /etc/supervisor/supervisord.conf

选3-也是最佳选择，就是上述都不选。上述虽然都可以修复，但容器启动后，是否能在飞牛界面上看到openclaw的实时日志，我不知道。上述都是我做过的研究，不忍删除，因此单纯的保留记录下。

关于openrouter的免费模型

z-ai/glm-4.5-air:free

关于pip安装提示空间不足

报缓存错误，则增加参数--cache-dir指定安装时使用哪个目录缓存，避免出现空间不足的错误。
更改pip缓存目录:
如果某个分区空间充足，可以将pip的缓存目录更改为该分区。创建一个新的目录，例如 /mnt/data/pip_cache，然后在使用pip安装软件包时，通过 --cache-dir 选项指定新的缓存目录。
--cache-dir /mnt/pip_cache

最后：

转载请注明出处。
文件存储权限的事情，以及其他几个研究事项，通过我抛砖引玉出那位大神搞定了，欢迎发邮件交流：mapleshadow@gmail.com
我估计linuxserver官方大概率会封装openclaw，但那是以后的事情了。

教程编制时间：2026年3月30日

枫影 · 昨天 22:01

排版有些乱（直接从obsidian复制来的），图片也没上传，下次再说。

		自动登录	找回密码
密码			立即注册