Docker 运行PicoClaw#

准备工作#

• NAS 已安装 Docker 和 Docker Compose
• 可以访问外网，方便拉取镜像和调用模型 API
• 至少准备一个可用模型配置，例如 OpenAI、OpenRouter、DeepSeek，或者本地 Ollama

1. 拉取项目#

1
git clone https://github.com/sipeed/picoclaw.git
2
cd picoclaw

如果你平时就习惯把容器项目统一放在一个目录里，也可以提前建个文件夹，例如 /volume1/docker/picoclaw 或 /mnt/data/docker/picoclaw，再把仓库克隆进去。

2. 首次启动，生成配置文件#

PicoClaw 第一次运行时会自动生成配置目录，容器完成初始化后会退出，这是正常现象。

1
docker compose -f docker/docker-compose.yml --profile launcher up

看到 First-run setup complete. 之后，就说明初始化完成了。

这一步会生成：

• docker/data/config.json
• docker/data/workspace/

3. 修改配置#

编辑配置文件：

1
vim docker/data/config.json

如果你只是想先把 PicoClaw 跑起来，至少要配置一个默认模型。下面是一个最小示例：

1
{
2
  "agents": {
3
    "defaults": {
4
      "model_name": "gpt-5.4"
5
    }
6
  },
7
  "model_list": [
8
    {
9
      "model_name": "gpt-5.4",
10
      "model": "openai/gpt-5.4"
11
    }
12
  ]
13
}

如果你使用本地 Ollama，可以改成这样：

1
{
2
  "agents": {
3
    "defaults": {
4
      "model_name": "local-llama"
5
    }
6
  },
7
  "model_list": [
8
    {
9
      "model_name": "local-llama",
10
      "model": "ollama/llama3.1:8b",
11
      "api_base": "http://宿主机IP:11434/v1"
12
    }
13
  ]
14
}

如果是新版配置，敏感信息通常会单独放到 .security.yml，API Key 相关内容按官方文档补充即可。

如果只是测试能不能跑起来，建议先用一个最简单的模型配置，确认 Web UI 能打开、对话能成功，再慢慢补其他 provider、channel 或自动化能力。

适合 NAS 的 docker-compose 示例#

官方仓库已经自带 docker/docker-compose.yml，直接用当然没问题。

但如果你想把配置整理成一个更适合 NAS 的独立 compose 文件，也可以在项目根目录新建一个 compose.yaml，内容参考下面这样：

1
services:
2
  picoclaw:
3
    image: docker.io/sipeed/picoclaw:launcher
4
    container_name: picoclaw
5
    restart: on-failure
6
    environment:
7
      PICOCLAW_GATEWAY_HOST: 0.0.0.0
8
    ports:
9
      - "18800:18800"
10
      - "18790:18790"
11
    volumes:
12
      - ./data:/root/.picoclaw

启动命令：

1
docker compose up -d

这个写法比较适合 NAS 场景，原因也很直接：

• 18800 用来访问 PicoClaw 的 Web UI
• 18790 是网关端口，后续接 webhook 或聊天平台时可能会用到
• ./docker/data 统一保存配置、workspace 和运行数据，迁移也方便
• PICOCLAW_GATEWAY_HOST=0.0.0.0 让容器内服务可以被局域网访问

如果你只想自己在 NAS 本机上访问，也可以把端口写成 127.0.0.1:18800:18800 这种形式，安全性会更高一些。

4. 启动 PicoClaw#

推荐直接启动 launcher，这样可以通过 Web UI 管理配置和对话：

1
docker compose -f docker/docker-compose.yml --profile launcher up -d

如果你已经改成了上面的独立 compose.yaml，那就直接执行：

1
docker compose up -d

启动完成后，在浏览器打开：

1
http://NAS-IP:18800

第一次在浏览器里看到页面出来的时候，基本就说明方向对了。后面不管是接 OpenAI、OpenRouter，还是连本地 Ollama，都会轻松很多。

如果你是放在 Docker、虚拟机或者 NAS 容器环境里，记得确认监听地址是不是 0.0.0.0，否则可能只能容器内部访问。

5. 查看日志#

1
docker compose -f docker/docker-compose.yml logs -f

如果只想看网关日志，也可以执行：

1
docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway

6. 停止与更新#

停止：

1
docker compose -f docker/docker-compose.yml --profile launcher down

更新：

1
docker compose -f docker/docker-compose.yml pull
2
docker compose -f docker/docker-compose.yml --profile launcher up -d

如果你用的是自己的 compose.yaml，更新就更简单：

1
docker compose pull
2
docker compose up -d

7. 只在命令行里临时使用#

如果你不需要常驻服务，只想临时问一个问题，可以直接跑 agent 模式：

1
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "帮我总结今天的待办"

进入交互模式：

1
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent

这种方式很适合在 NAS 上偶尔调用，不需要一直挂着后台服务。

我自己更推荐的用法还是：平时让 launcher 常驻，需要调试时再临时跑 agent。这样既有 Web UI，也保留了命令行的灵活性。

常见问题#

Refer#

• sipeed/picoclaw - GitHub
• Docker Deployment - PicoClaw