OpenClaw 上手实践: 使用 Docker 从构建到可用全流程指南

墨渊君2026-03-23 10:00

引言

最近, OpenClaw 可用说是遍地开花。

从最初的小范围讨论, 到 GitHub 上的持续增长, 再到各个社区里不断刷屏, 越来越多的人开始把它当成下一代 AI Agent 基础设施来看待。有人在惊叹它的能力, 有人在研究它的架构, 也有人开始焦虑------担心自己会不会错过这一波。

但说实话, 技术浪潮从来不会因为焦虑而停下。

那么既然打不过那就加入, 本文主要讲解如何在本地通过 Docker 来部署一个 openClaw...

一、编译 Docker 镜像

Docker 的下载安装就不展开了, 这里直接问 AI 或者查阅 官网 就行.

1.1 构建镜像

这边直接使用 OpenClaw 官方 提供的构建脚本来

  1. 先把 OpenClaw 仓库拉到本地来
sh 复制代码 
git clone https://github.com/openclaw/openclaw.git
  1. 执行构建脚本: 进入仓库并执行构建镜像脚本 docker-setup.sh
sh 复制代码 
cd openclaw
./docker-setup.sh

⌛️ 等待构建...

1.2 配置 OpenClaw

上面脚本, 在构建完成后, 会出现一个可交互命令, 我们需要根据提示完成相关基础配置:

  1. 首先是安全告知: 提示风险, 这边选择 Yes 开始
  1. 配置模式选择: 这边有两种安装模式分别是 QuickStart(快速开始) 和 Manual(手动), 这里我们选择 QuickStart(快速开始), 它们两点区别就是如果选择 Manual(手动) 很多默认配置信息都要我们进行配置、确认(配置起来会更繁琐点, 要填写的内容更多)

这边如果我们之前构建过镜像并且有过配置, 则会在 ~/.openclaw 内生成一份缓存。那么到这一步就会有提示「是否复用、或者重置」, 具体效果没试过, 了解下即可。

  1. 模型配置(Model/auth provider): 我这边打算使用 CodeX 订阅账号, 所以选择了 openAI, 如果没有可直接跳过, 后续手动配置即可

下面选择鉴权方式: 这里我选的是 OpenAI Codex (ChatGPT OAuth) (Browser sign-in)

浏览器登录鉴权: 这里会吐出一个鉴权的链接, 直接复制到浏览器, 按照提示完成登录即可

登录鉴权成功后这边会, 会重定向回来, 这时直接把 URL 复制到终端中, 并回车即可

校验通过则会让选择默认模型, 这边我直接选择最新的 Gpt-5.4

  1. 接下来会让选择频道以及网页搜索配置, 这边我先直接跳过「Skip for now」
  1. Skill 配置: 直接选择 No 先跳过
  1. Enable hooks? 不知道干嘛的, 直接空格选择 Skilp for now, 会车跳过
  1. 接下来等待完成即可
  1. 最后这边会直接运行容器, 我们可以直接通过 docker ps 来查看

在我们进行配置的时候其实镜像已经构建完成, 后面的配置其实是运行容器并执行了什么初始化命令。

二、尝试访问

在输出日志(往上翻)中可以看到 OpenClaw 的 Web 页面访问信息

但是当你真的在浏览器访问 http://127.0.0.1:18789/#token=xxxxxxxx 会发现好像并不能登录

会发现抛 pairing required 错误, 这是因为 OpenClaw Gateway 会对访问的浏览器/设备进行权限控制, 当未经授权的浏览器/设备访问时系统会抛出 disconnected (1008): pairing required 错误。

这是 OpenClaw 的安全配对机制在起作用, 有点类似于 SSH 的已知主机验证, 确保只有授权过的设备能访问你的网关。这是一种 零信任 的安全模型, 确保每个连接设备都是经过验证的。

核心原理: OpenClaw 采用基于设备的访问控制模型, 当任何客户端(浏览器、CLI、手机 App 或 Node 节点)首次连接到 Gateway 时:

  • 设备识别: Gateway 会先生成唯一的设备身份标识
  • 请求创建: 会创建待审批的配对请求(Pending Request)
  • 连接挂起: 接下来连接会被挂起, 等待管理员进行批准
  • 超时断开: 当等待批准的请求超过 30 秒未被批准, 请求则会失效, 需要客户端再次发起连接请求

那么问题也就很明显了, 下面我们来将我们的设备添加到 OpenClaw 可信名单中:

  1. 进入容器内部
sh 复制代码 
docker ps # 查看当前容器, 目前是查看容器 ID
docker exec -it def1c5e769b0 bash # 进入容器内
#            |   |              |
#            |   |              └─ 在容器内执行的命令（启动 bash shell）
#            |   └─ 容器 ID / 名称（目标运行中的容器）
#            └─ 参数组合：
#               -i：保持标准输入（可交互）
#               -t：分配伪终端（TTY），用于终端显示
  1. 在终端中执行以 openclaw devices list 来查看设备列表信息: 如下所示, Pending (1) 列表则是目前挂起的设备连接请求, 也是等待我们批准的可信设备列表。若 Pending (1) 列表为空, 则说明请求已过期, 需刷新浏览器重新触发配对
sh 复制代码 
$ openclaw devices list

🦞 OpenClaw 2026.3.14 (unknown) --- We ship features faster than Apple ships calculator updates.

Pending (1)
┌─────────────────┬───────────────┬──────────┬──────────────────────────────────────────────────────┬────────────┬──────────┬────────┐
│ Request         │ Device        │ Role     │ Scopes                                               │ IP         │ Age      │ Flags  │
├─────────────────┼───────────────┼──────────┼──────────────────────────────────────────────────────┼────────────┼──────────┼────────┤
│ e82d56fxxxxxd86 │ 5acccccccce76 │ operator │ operator.admin, operator.approvals, operator. pairing│ 172.25.0.1 │ just now │        │
└─────────────────────────────────┴──────────┴──────────────────────────────────────────────────────┴────────────┴──────────┴────────┘

Paired (1)
┌──────────────────────────┬────────────┬────────────────────────────────────────────────────────────────────────────────────────┬────────────┬────────────┐
│ Device                   │ Roles      │ Scopes                                                                                 │ Tokens     │ IP         │
├──────────────────────────┼────────────┼────────────────────────────────────────────────────────────────────────────────────────┼────────────┼────────────┤
│ b71c1232132132137330c1   │ operator   │ operator.admin, operator.read, operator.write, operator.approvals, operator.  pairing  │ operator   │            │
└──────────────────────────┴────────────┴────────────────────────────────────────────────────────────────────────────────────────┴────────────┴────────────┘
  1. 批准指定设备: 复制批准的 Request ID(上表中的第一列) 例如 4f9db1bd-a1cc-4d3f-b643-2c195262464e, 并执行 openclaw devices approve [Request ID] 来批准设备
sh 复制代码 
$ openclaw devices approve 4f9db1bd-a1cc-4d3f-b643-2c195262464e

# 成功信息:
✓ Approved device 4f9db1bd-a1cc-4d3f-b643-2c195262464e (browser)
Access granted. Device can now connect to Gateway.
  1. 最后选择重新连接, 进入 OpenClaw 开始聊天
  1. 本以为这样就行了, 但是如上图所示, 居然还要进行 CodeX 授权

三、CodeX 授权

直接根据官方文档 Config-Snippet-Codex 进行配置...

  1. 重新进入容器内部
sh 复制代码 
docker ps # 查看当前容器, 目前是查看容器 ID
docker exec -it def1c5e769b0 bash # 进入容器内
#            |   |              |
#            |   |              └─ 在容器内执行的命令（启动 bash shell）
#            |   └─ 容器 ID / 名称（目标运行中的容器）
#            └─ 参数组合：
#               -i：保持标准输入（可交互）
#               -t：分配伪终端（TTY），用于终端显示
  1. 如下官方给出两个授权登录的命令
sh 复制代码 
# Run Codex OAuth in the wizard
openclaw onboard --auth-choice openai-codex

# Or run OAuth directly
openclaw models auth login --provider openai-codex
  1. 这里我用的是第二种方式: 鉴权方式和上文构建镜像配置模型的鉴权方式是一样的, 都是通过浏览器链接来完成鉴权; 执行 openclaw models auth login --provider openai-codex 将命令返回的链接在浏览器进行打开并进行授权

登录鉴权成功后这边会, 会重定向回来, 这时直接把 URL 复制到终端中, 并回车即可

  1. 最后容器会重启
  1. 重启后重新访问 OpenClaw 能够进行正常对话, 就算大功告成咯

四、目录

OpenClaw 的 Home 目录在 ~/.openclaw 下, 下面是其目录结构、以及每个目录的大体作用

sh 复制代码 
~/.openclaw
.
|-- agents                          # 每个 Agent 的运行态数据（状态 + 配置 + 会话）
|   `-- main                        # 默认 agent（agentId = main）
|       |-- agent
|       |   |-- auth-profiles.json  # 模型/API 认证信息（API Key / OAuth 等）
|       |   `-- models.json         # 当前 agent 可用模型配置（provider / model 列表）
|       `-- sessions
|           |-- *.jsonl             # 对话历史（按 sessionId 存储，JSONL 逐条消息）
|           `-- sessions.json       # 会话索引/元数据（session 生命周期、映射关系）
|-- canvas
|   `-- index.html                 # Web UI 前端入口（本地可视化界面）
|
|-- completions                    # Shell 自动补全脚本
|   |-- openclaw.bash              # bash 补全
|   |-- openclaw.fish              # fish 补全
|   |-- openclaw.ps1               # PowerShell 补全
|   `-- openclaw.zsh               # zsh 补全
|
|-- cron
|   `-- jobs.json                  # 定时任务配置（类似 agent 的"自动执行计划"）
|
|-- devices                        # 设备配对（多端登录/控制）
|   |-- paired.json                # 已信任设备列表
|   `-- pending.json               # 待确认设备（pairing 流程中）
|
|-- identity                       # 当前节点/设备身份
|   |-- device-auth.json           # 设备认证信息（token / 密钥）
|   -- device.json                # 设备基本信息（nodeId、名称等）
|-- logs                           # 日志目录
|   -- config-audit.jsonl         # 配置变更审计日志（谁改了什么配置）
|-- openclaw.json                  # ⭐ 主配置文件（最核心：模型/网关/安全/渠道等） :contentReference[oaicite:0]{index=0}
|-- openclaw.json.bak*             # 配置文件自动备份（历史版本回滚用）
|-- update-check.json              # 更新检查缓存（版本信息、更新时间等）
`-- workspace                     # ⭐ Agent"灵魂层"（提示词 + 行为定义）
    |-- AGENTS.md                 # 多 Agent 路由/策略（如何分配任务）
    |-- BOOTSTRAP.md              # 启动提示词（初始化上下文）
    |-- HEARTBEAT.md              # 周期性检查/自检逻辑
    |-- IDENTITY.md               # Agent 身份（名字、人设、角色）
    |-- SOUL.md                   # 性格/语气/风格（核心人格定义）
    |-- TOOLS.md                  # 工具使用规范（如何调用工具/API）
    `-- USER.md                   # 用户画像（偏好、背景，让 agent 更懂你）

而我们上文配置的模型信息就存在 .openclaw/agents/main/agent/auth-profiles.json 中, 下面是具体的内容:

sh 复制代码 
$ cat .openclaw/agents/main/agent/auth-profiles.json 

{
  "version": 1,
  "profiles": {
    "openai-codex:default": {
      "type": "oauth",
      "provider": "openai-codex",
      "access": "ey*******************uYM",
      "refresh": "rt_GVwk*******ns",
      "expires": 112111112336656
    }
  },
  "usageStats": {
    "openai-codex:default": {
      "errorCount": 0,
      "lastUsed": 17712132312312386
    }
  }
}

五、参考

相关推荐
冰暮流星1 小时前
javascript之回调函数
开发语言·前端·javascript
米丘1 小时前
Rollup 打包工具
前端
We་ct1 小时前
LeetCode 74. 搜索二维矩阵：两种高效解题思路
前端·算法·leetcode·矩阵·typescript·二分查找
moneyinto1 小时前
Three.js 必背核心方法
前端
wuhen_n2 小时前
Vue3 组件中的图片懒加载与渐进式加载
前端·javascript·vue.js
叫回忆2 小时前
elpis的npm抽离与发布
前端·javascript
wuhen_n2 小时前
Vite 构建层面的图片优化：从压缩到转换
前端·javascript·vue.js
hashiqimiya2 小时前
vue项目组装-路由-文件修改地方
前端·javascript·vue.js
Mike_jia2 小时前
ChatClaw：5 分钟打造你的个人 AI 智能体
前端
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03围棋-html版本04小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）05班级宠物园部署指南06OpenClaw 使用和管理 MCP 完全指南07AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南08OpenClaw Control UI安全上下文访问配置09UV安装并设置国内源10“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）