OpenClaw 入门：从安装配置到接入自定义模型
OpenClaw 入门：从安装配置到接入自定义模型
如果你第一次听说 OpenClaw，可以先把它理解成：
一个可以帮你“动手干活”的 AI 工作者。
普通聊天机器人主要是回答问题；OpenClaw 更像一个受控的执行环境。你可以让它写草稿、整理文件、检查日志、运行命令、改代码、生成报告。它不只是“说”，还可以在你允许的范围内“做”。
这篇文章会用尽量简单的方式，带你了解：
- OpenClaw 适合做什么
- 为什么建议把它当作 worker 使用
- Linux / macOS / Windows WSL2 的准备方式
- 如何用 Docker Compose 思路部署
- 如何接入 OpenAI-compatible 自定义模型
- 如何验证配置是否成功
- 如何升级、改模型、卸载
- 常见错误怎么判断
- 新手必须注意的安全边界
本文不会包含任何真实 API Key、私有 token、生产密钥或私人信息。命令里的密钥都用占位符表示，你照着替换成自己的即可。
1. OpenClaw 适合做什么？
OpenClaw 可以把大语言模型接到一个真实的工作目录里，让 AI 帮你完成一些具体任务。
比如：
- 帮你写 Markdown 草稿
- 帮你检查项目文件
- 帮你运行测试命令
- 帮你查看日志并总结问题
- 帮你生成部署说明
- 帮你做简单的自动化任务
- 帮你整理代码变更报告
- 帮你检查某个服务是否正常运行
你可以把它想象成一个“AI 工程助手”。
不过，刚开始使用时，不建议一上来就给它全部权限。更安全的方式是：
先让 OpenClaw 做 worker，也就是执行具体任务的工人，而不是整个服务器的主人。
也就是说，它可以帮你干活，但重要操作仍然应该由你确认。
例如，适合让它做：
- 在工作目录里写草稿
- 生成配置模板
- 查看非敏感日志
- 跑测试
- 输出报告
- 检查某个目录下的文件结构
- 对代码提出修改建议
不建议一开始就让它做：
- 直接修改生产网站
- 删除数据库
- 修改 DNS
- 改防火墙
- 管理所有 Docker 容器
- 拿到服务器所有权限
- 读取你的所有私人目录
- 接触真实生产密钥
这样做的好处是：既能享受 AI 自动化带来的效率，又不会让风险失控。
2. 先理解几个基本概念
在开始安装之前，先弄清楚几个词。
OpenClaw Gateway
Gateway 可以理解成 OpenClaw 的入口服务。
它负责接收请求、管理会话、调度 agent、连接模型等。
新手要记住一点：
Gateway 不应该随便暴露到公网。
如果 Gateway 被外部随便访问，可能会带来安全风险。
所以本文示例里会优先使用：
127.0.0.1
也就是只允许本机访问。
Worker
Worker 是“干活的人”。
你可以让 OpenClaw 在一个固定目录里工作，例如：
/opt/openclaw-worker/workspace
让它先在这个目录里写文件、改草稿、生成报告。这样即使它做错了，也比较容易控制影响范围。
API Key
API Key 可以理解成“访问模型服务的密码”。
如果别人拿到你的 API Key，就可能消耗你的额度，甚至访问你不希望别人访问的服务。
所以永远不要把真实 API Key：
- 发到群里
- 写进公开博客
- 提交到 GitHub
- 放进截图
- 发给不可信的人
- 写进可以被别人看到的日志
本文里出现的：
YOUR_API_KEY_HERE
都只是占位符，不是真实密钥。
OpenAI-compatible
OpenAI-compatible 的意思是：
这个模型服务不一定是 OpenAI 官方的，但它模仿 OpenAI 的接口格式。
常见情况包括：
- 第三方模型平台
- 自建模型网关
- 公司内部模型服务
- 本地或私有部署的模型代理
如果你的模型服务文档里写着：
OpenAI-compatible API
或者提供类似：
/v1/chat/completions
这样的接口，一般就可以尝试按本文方式接入。
3. 适合新手的整体流程
如果你是第一次部署，建议按这个顺序来：
- 准备 Docker 环境
- 准备一个独立目录
- 写
docker-compose.yml - 启动 OpenClaw Gateway
- 确认 Gateway 只绑定本机地址
- 使用
openclaw onboard添加自定义模型 - 使用
openclaw models status检查模型状态 - 使用
openclaw infer model run测试模型 - 使用
openclaw agent --thinking off测试 agent - 先让 OpenClaw 在工作区里写草稿、查日志、生成报告
- 熟悉之后，再逐步扩大权限
不要一开始就追求“全自动控制整个服务器”。新手最稳妥的方式是：
小权限、小目录、小任务，先跑通，再扩大。
4. 系统准备：Linux
如果你使用的是 Linux 服务器，例如 Ubuntu、Debian、CentOS、Rocky Linux 等，推荐使用 Docker Compose 部署。
下面以 Ubuntu / Debian 系为例。
4.1 更新软件包
sudo apt update
4.2 安装常用工具
sudo apt install -y curl ca-certificates gnupg
4.3 安装 Docker
如果你的系统还没有 Docker，可以参考 Docker 官方文档安装。
安装完成后，检查 Docker 是否可用：
docker --version
再检查 Docker Compose 是否可用：
docker compose version
如果能看到版本号，说明 Docker 和 Docker Compose 基本可用。
4.4 普通用户是否需要加入 docker 组？
有些系统上，直接运行 Docker 命令可能会提示权限不足。
你可以临时使用：
sudo docker ps
如果你希望当前用户可以直接运行 Docker，可以执行：
sudo usermod -aG docker "$USER"
然后重新登录一次终端。
注意：加入 docker 组意味着这个用户拥有很高的 Docker 控制权限。个人服务器通常可以接受，但多人服务器要谨慎。
5. 系统准备：macOS
macOS 上建议使用 Docker Desktop。
5.1 安装 Docker Desktop
去 Docker 官网下载安装 Docker Desktop for Mac。
安装完成后，打开 Docker Desktop，等待它启动完成。
5.2 检查 Docker 是否可用
打开终端，运行：
docker --version
再运行：
docker compose version
如果能看到版本号，说明 Docker 可用。
5.3 macOS 上推荐的工作目录
Linux 服务器通常用：
/opt/openclaw-worker
但 macOS 上 /opt 可能需要额外权限。新手可以使用用户目录下的路径，例如：
~/openclaw-worker
创建目录：
mkdir -p ~/openclaw-worker/{state,workspace,auth-profile-secrets,reports,backups}
进入目录：
cd ~/openclaw-worker
后文如果出现：
/opt/openclaw-worker
macOS 用户可以替换成：
~/openclaw-worker
6. 系统准备：Windows / WSL2
Windows 上推荐使用 WSL2，也就是 Windows Subsystem for Linux。
简单理解：
WSL2 可以让你在 Windows 里运行一个 Linux 环境。
OpenClaw 这类工具放在 WSL2 里跑，会比直接在 Windows 命令行里折腾更顺。
6.1 安装 WSL2
在 Windows PowerShell 里运行：
wsl --install
安装完成后，按提示重启电脑。
然后打开 Ubuntu 终端。
如果你已经安装过 WSL，可以查看发行版：
wsl -l -v
建议使用 WSL2，而不是 WSL1。
6.2 安装 Docker Desktop
Windows 上也推荐安装 Docker Desktop。
安装时注意启用 WSL2 integration。
打开 Docker Desktop 后，可以在设置里找到类似：
Resources → WSL Integration
把你使用的 Ubuntu 发行版打开。
6.3 在 WSL2 里检查 Docker
进入 Ubuntu 终端，运行：
docker --version
再运行：
docker compose version
如果能看到版本号，说明 WSL2 里的 Docker 可以用了。
6.4 WSL2 上推荐的工作目录
不要把工作目录放在 Windows 盘的路径里，例如：
/mnt/c/Users/你的名字/...
虽然能用，但有时性能和权限体验不太好。
建议放在 WSL2 的 Linux 文件系统里，例如：
~/openclaw-worker
创建目录：
mkdir -p ~/openclaw-worker/{state,workspace,auth-profile-secrets,reports,backups}
进入目录：
cd ~/openclaw-worker
后文如果出现：
/opt/openclaw-worker
Windows / WSL2 用户可以替换成：
~/openclaw-worker
7. 准备一个独立目录
这一步做什么：
我们先给 OpenClaw 准备一个单独的目录，把配置、工作区、状态文件分开放好。这样以后排查和备份都会简单很多。
Linux 服务器示例目录使用：
/opt/openclaw-worker
macOS / WSL2 新手也可以使用：
~/openclaw-worker
本文后续主要用 Linux 路径举例：
/opt/openclaw-worker
你可以按下面的结构准备：
/opt/openclaw-worker
├── docker-compose.yml
├── state/
├── workspace/
├── auth-profile-secrets/
├── reports/
└── backups/
这些目录大概是什么意思：
state/
保存 OpenClaw 的运行状态，比如会话、任务、内部数据等。
workspace/
这是 OpenClaw worker 的工作区。
你让它写文件、改草稿、生成报告，通常都应该先放在这里。
auth-profile-secrets/
保存模型 API Key 等认证信息。
这个目录很敏感，不要公开，不要提交到 Git，也不要截图发群里。
reports/
可以用来放 OpenClaw 生成的检查报告、任务结果等。
backups/
可以用来放配置备份。注意，备份里也可能有敏感信息，也要保护好。
如果你是在 Linux 服务器上操作，可以创建目录：
sudo mkdir -p /opt/openclaw-worker/{state,workspace,auth-profile-secrets,reports,backups}
然后进入目录：
cd /opt/openclaw-worker
如果你是在 macOS 或 WSL2 上操作，可以创建：
mkdir -p ~/openclaw-worker/{state,workspace,auth-profile-secrets,reports,backups}
然后进入目录：
cd ~/openclaw-worker
8. 用 Docker Compose 部署 OpenClaw
这一步做什么：
Docker 可以把 OpenClaw 放在一个相对独立的容器里运行。Docker Compose 是 Docker 的一个常用工具，可以用一个配置文件管理容器启动方式。
你不需要一开始理解 Docker 的所有细节，只要先记住：
Docker Compose 就是用一个
docker-compose.yml文件描述“这个服务怎么跑”。
8.1 新手最重要的安全原则
新手最重要的一点是：
不要把 Gateway 直接暴露到公网。
Gateway 可以理解为 OpenClaw 的控制入口。如果它被公网随便访问，别人可能会尝试触发你的 agent 或读取信息。
推荐只绑定到本机地址：
127.0.0.1
这叫“本地回环地址”，意思是只有这台机器自己能访问。
不要一开始就绑定到：
0.0.0.0
0.0.0.0 通常表示外部也可能访问到，风险更高。
8.2 docker-compose.yml 示例
在 OpenClaw 工作目录里创建文件：
nano docker-compose.yml
写入类似下面的内容。
注意：不同版本的 OpenClaw 镜像名、环境变量、挂载路径和端口可能会变化。请以你正在使用的官方文档为准。下面只是“新手理解用”的 Compose 思路模板，不建议在没核对官方文档的情况下原样复制。
services:
openclaw-gateway:
image: OPENCLAW_IMAGE_HERE
restart: unless-stopped
ports:
- "127.0.0.1:18789:18789"
- "127.0.0.1:18790:18790"
volumes:
- ./state:/app/state
- ./workspace:/app/workspace
- ./auth-profile-secrets:/app/auth-profile-secrets
- ./reports:/app/reports
你需要把：
OPENCLAW_IMAGE_HERE
替换成你实际使用的 OpenClaw 镜像名。
如果官方文档给了完整的 docker-compose.yml，优先使用官方文档里的版本。你只需要特别检查两点：
ports是否绑定到了127.0.0.1- 敏感目录是否单独挂载并妥善保护
8.3 启动服务
在 docker-compose.yml 所在目录运行：
docker compose up -d
如果你是在 Linux 上并且没有把当前用户加入 docker 组，可能需要：
sudo docker compose up -d
查看容器状态：
docker compose ps
如果看到容器处于运行状态，说明服务已经启动。
8.4 查看日志
如果启动失败，可以看日志：
docker compose logs --tail=100
如果只想看某个服务，可以运行：
docker compose logs --tail=100 openclaw-gateway
8.5 检查 Gateway 是否活着
启动后，你可以用下面命令检查 Gateway 是否活着：
curl http://127.0.0.1:18789/healthz
如果它返回正常，只能说明：
Gateway 进程启动了。
它不代表模型已经配置成功，也不代表 agent 已经能正常工作。模型和 agent 还需要后面的步骤验证。
9. 安装或使用 OpenClaw CLI
后续命令会写成 openclaw ...，这是为了让教程更容易读。
如果你是用 Docker Compose 部署，并且项目里提供 openclaw-cli 服务，也可以把命令写成这种形式：
docker compose run --rm openclaw-cli openclaw --help
有些封装镜像会把入口命令直接设成 openclaw，这时实际命令可能是：
docker compose run --rm openclaw-cli --help
简单说：如果直接运行 openclaw 提示命令不存在，就按你的部署方式改成 docker compose run --rm openclaw-cli ...。
后续会用到类似下面的命令：
openclaw models status
这需要你的环境里可以执行 openclaw CLI。
有些部署方式会在宿主机安装 CLI，有些方式会让你进入容器里执行命令，还有些方式会提供一条封装脚本。
你可以先检查本机是否有 openclaw 命令：
openclaw --help
如果提示命令不存在，你需要根据你的安装方式选择一种：
方式 A：按官方文档安装 CLI
这是最推荐的方式。安装完成后，再运行：
openclaw --help
能看到帮助信息即可。
方式 B：进入容器里执行
如果你的 openclaw 命令只在容器里可用，可以先查看服务名：
docker compose ps
然后进入容器：
docker compose exec openclaw-gateway sh
进入后再运行：
openclaw --help
如果容器里没有 sh，可以尝试：
docker compose exec openclaw-gateway bash
方式 C：使用项目提供的脚本
有些部署包会提供类似：
./scripts/status.sh
或者：
./openclaw
这样的封装脚本。
如果官方文档或项目 README 提供了脚本，优先按它来。
10. 什么是 API Key 和自定义模型？
这一步做什么：
在接入模型之前，先理解几个基本概念。
API Key 可以理解成“访问模型服务的密码”。
如果你要调用某个模型供应商的接口，一般需要提供 API Key。别人拿到你的 API Key，就可能消耗你的额度，所以一定不要公开。
自定义模型 在这里通常指：
不是 OpenClaw 默认内置的模型，而是你自己提供的模型服务。
OpenAI-compatible 的意思是：
这个模型服务虽然不一定是 OpenAI 官方的，但它的接口格式模仿 OpenAI，所以很多工具可以用类似方式调用它。
常见情况包括：
- 第三方模型平台
- 自建模型网关
- 公司内部模型服务
- 本地或私有部署的模型代理
如果你的模型服务说明里写着“OpenAI-compatible API”，一般就可以尝试用本文的方式接入。
11. 使用 onboard 接入自定义模型
这一步做什么：
我们要告诉 OpenClaw：你的模型服务在哪里、模型叫什么、API Key 是什么、按哪种兼容格式调用。
可以使用类似下面的命令模板：
openclaw onboard \
--auth-choice custom-api-key \
--custom-provider-id my-custom-provider \
--custom-base-url https://api.example.com/v1 \
--custom-model-id my-model-id \
--custom-api-key YOUR_API_KEY_HERE \
--custom-compatibility openai
你需要把里面的示例值换成自己的。
例如：
openclaw onboard \
--auth-choice custom-api-key \
--custom-provider-id openai-compatible-demo \
--custom-base-url https://api.example.com/v1 \
--custom-model-id demo-chat-model \
--custom-api-key YOUR_API_KEY_HERE \
--custom-compatibility openai
注意：
上面的：
YOUR_API_KEY_HERE
只是占位符，不是真实 key。
写博客、截图、发群、提交 Git 时都不要放真实 API Key。
12. 参数逐个解释
这一步做什么：
我们把上面的参数一个个说清楚，避免你不知道该填什么。
12.1 --auth-choice custom-api-key
--auth-choice custom-api-key
意思是：使用自定义 API Key 登录模型服务。
12.2 --custom-provider-id
--custom-provider-id openai-compatible-demo
意思是：给这个模型服务起一个名字。
这个名字以后会在 OpenClaw 里用到。
建议用简单英文、小写、无空格，例如：
my-openai-compatible
deepseek-proxy
local-model
company-gateway
不要使用：
我的模型
my model
test/abc
新手建议只用：
- 小写字母
- 数字
- 中横线
12.3 --custom-base-url
--custom-base-url https://api.example.com/v1
意思是：模型服务的接口地址。
很多 OpenAI-compatible 服务地址会以 /v1 结尾，比如：
https://api.example.com/v1
你需要看你的模型供应商文档，填它提供的 base URL。
常见错误是多写或少写 /v1。
例如，供应商文档写的是：
https://api.example.com/v1
你就不要只填：
https://api.example.com
也不要乱加成：
https://api.example.com/v1/chat/completions
一般这里填的是 base URL，不是完整的 chat completions 地址。
12.4 --custom-model-id
--custom-model-id demo-chat-model
意思是：你要调用的模型名称。
这个值必须和模型服务支持的名称一致。
如果供应商文档里说模型 ID 是：
gpt-example
那你这里就应该填：
--custom-model-id gpt-example
不要自己随便改名。
12.5 --custom-api-key
--custom-api-key YOUR_API_KEY_HERE
意思是：你的 API Key。
请只在自己的服务器终端里填写真实 key。不要把真实 key：
- 发到群里
- 写进公开博客
- 提交到 GitHub
- 放进截图
- 发给不可信的人
如果你要写教程，可以写：
YOUR_API_KEY_HERE
或者：
sk-xxx…xxxx
但不要写真实内容。
12.6 --custom-compatibility openai
--custom-compatibility openai
意思是：按 OpenAI-compatible 的接口格式调用这个模型。
如果你的模型服务文档写的是 OpenAI-compatible，通常就填：
openai
13. 第一次验证：查看模型状态
这一步做什么：
先确认 OpenClaw 是否已经识别到你配置的模型。
运行：
openclaw models status
你需要看几个点：
- 能不能看到刚才设置的 provider
- model id 有没有写对
- 有没有提示找不到 API Key
- 有没有明显的配置错误
如果这一步都看不到你的模型，先不要继续跑 agent。
应该先回头检查 onboard 命令有没有填错。
14. 第二次验证：直接测试模型推理
这一步做什么：
确认模型服务本身能不能被调用。
运行：
openclaw infer model run \
--model openai-compatible-demo/demo-chat-model \
--prompt "Reply with exactly: MODEL_OK"
这里的：
openai-compatible-demo/demo-chat-model
要换成你的：
provider-id/model-id
如果配置正常，模型应该回复类似：
MODEL_OK
如果这里失败，通常说明问题在模型连接本身，比如：
- API Key 不对
- base URL 不对
- model id 不对
- 网络不通
- 模型服务不兼容
- 账户额度不足
- 模型服务限制了当前地区或 IP
先把这一步跑通，再继续下一步。
15. 第三次验证：运行 agent smoke test
这一步做什么：
确认 OpenClaw agent 能不能真正使用这个模型。
“Smoke test” 可以理解成“冒烟测试”，就是最小可用测试。
它不是完整测试，只是确认基本链路能跑起来。
运行：
openclaw agent \
--model openai-compatible-demo/demo-chat-model \
--thinking off \
--message "Reply with exactly: OPENCLAW_AGENT_OK"
这里特别加了：
--thinking off
这是因为有些自定义模型不支持 thinking / reasoning 参数。
thinking 可以理解成模型的“推理强度”设置，但不是所有模型都支持。新手第一次测试时，建议先关掉，减少兼容问题。
如果成功，应该看到类似：
OPENCLAW_AGENT_OK
这说明：
- 模型可以调用
- agent 可以启动
- OpenClaw 能把消息交给模型
- 基础配置已经打通
16. 给新手的第一个安全任务
模型跑通后，不要马上让它改生产服务。
建议先让它做一个完全安全的小任务。
例如，在工作区里创建一份测试报告：
openclaw agent \
--model openai-compatible-demo/demo-chat-model \
--thinking off \
--message "在 workspace 里写一份 hello-openclaw.md，内容包括：当前任务目标、你能做什么、你不能做什么。不要读取敏感文件。"
如果 agent 能完成，并且结果在你的工作目录里，就说明你已经完成了基础入门。
17. 如何修改默认模型
有时你已经接入了多个模型，想换一个默认使用的模型。
思路通常是：
- 先确认模型存在
- 再修改默认模型配置
- 最后跑一次 smoke test
先查看模型：
openclaw models status
假设你想使用的模型是：
new-provider/new-model
可以在运行 agent 时临时指定：
openclaw agent \
--model new-provider/new-model \
--thinking off \
--message "Reply with exactly: NEW_MODEL_OK"
如果你使用的 OpenClaw 版本支持设置默认模型，可以按官方文档修改配置或使用对应命令。
新手建议先用 --model 临时指定，确认能跑通后，再考虑改默认配置。
18. 如何增加一个新模型
如果你想再接入一个模型，不要直接覆盖原来的配置。可以新增一个 provider id。
例如原来有：
openai-compatible-demo/demo-chat-model
现在想新增：
fast-provider/fast-model
可以再次运行：
openclaw onboard \
--auth-choice custom-api-key \
--custom-provider-id fast-provider \
--custom-base-url https://api.example.com/v1 \
--custom-model-id fast-model \
--custom-api-key YOUR_API_KEY_HERE \
--custom-compatibility openai
然后验证：
openclaw models status
再测试：
openclaw infer model run \
--model fast-provider/fast-model \
--prompt "Reply with exactly: FAST_MODEL_OK"
最后测试 agent：
openclaw agent \
--model fast-provider/fast-model \
--thinking off \
--message "Reply with exactly: FAST_AGENT_OK"
19. 如何更换 API Key
如果你的 API Key 泄露、过期、额度用完，或者你换了供应商账号，就需要更换 API Key。
推荐做法：
- 先去模型服务商后台创建新的 API Key
- 不要把新 key 发给别人
- 在 OpenClaw 中重新 onboard 或更新认证信息
- 测试新 key 是否可用
- 去供应商后台删除旧 key
如果你使用 openclaw onboard 更新同一个 provider，可以类似这样：
openclaw onboard \
--auth-choice custom-api-key \
--custom-provider-id openai-compatible-demo \
--custom-base-url https://api.example.com/v1 \
--custom-model-id demo-chat-model \
--custom-api-key NEW_API_KEY_HERE \
--custom-compatibility openai
然后测试：
openclaw infer model run \
--model openai-compatible-demo/demo-chat-model \
--prompt "Reply with exactly: KEY_UPDATED_OK"
如果成功，再考虑去供应商后台禁用旧 key。
不要只在本地改完就以为完成了。真正安全的做法是：
新 key 测试通过后，旧 key 要在供应商后台撤销。
20. 如何升级 OpenClaw
升级前，先做三件事：
- 备份配置
- 备份状态目录
- 看一眼当前版本和日志
20.1 查看当前容器状态
进入 OpenClaw 目录：
cd /opt/openclaw-worker
macOS / WSL2 用户如果使用的是用户目录：
cd ~/openclaw-worker
查看容器：
docker compose ps
查看日志：
docker compose logs --tail=100
20.2 备份重要目录
建议备份这些内容：
docker-compose.yml
state/
auth-profile-secrets/
可以创建一个本地备份目录：
mkdir -p backups
然后复制配置文件：
cp docker-compose.yml backups/docker-compose.yml.bak
备份状态和认证目录时要注意：里面可能包含敏感信息，不要上传公开仓库。
可以用压缩包备份：
tar -czf backups/openclaw-backup.tar.gz docker-compose.yml state auth-profile-secrets
如果你的目录很大，备份可能需要一些时间。
20.3 拉取新镜像
如果你的 Compose 文件使用的是镜像部署，可以运行：
docker compose pull
20.4 重启服务
docker compose up -d
20.5 检查升级后状态
检查容器：
docker compose ps
检查 Gateway：
curl http://127.0.0.1:18789/healthz
检查模型：
openclaw models status
测试模型：
openclaw infer model run \
--model openai-compatible-demo/demo-chat-model \
--prompt "Reply with exactly: UPGRADE_MODEL_OK"
测试 agent：
openclaw agent \
--model openai-compatible-demo/demo-chat-model \
--thinking off \
--message "Reply with exactly: UPGRADE_AGENT_OK"
如果这几步都通过，说明升级后的基础链路基本正常。
21. 如何回滚
如果升级后出问题，不要慌。
先看日志：
docker compose logs --tail=200
如果你知道旧版本镜像，可以把 docker-compose.yml 里的镜像标签改回旧版本。
例如从：
image: OPENCLAW_IMAGE:latest
改成：
image: OPENCLAW_IMAGE:旧版本号
然后运行：
docker compose up -d
再验证：
curl http://127.0.0.1:18789/healthz
如果你不确定旧版本号，不要乱删目录。先保留现场，查看日志和备份。
尤其不要随便删除：
state/
auth-profile-secrets/
这些目录里可能有重要状态和认证信息。
22. 如何停止 OpenClaw
如果只是临时停止服务，可以进入 OpenClaw 目录后运行：
docker compose stop
再次启动：
docker compose start
或者：
docker compose up -d
23. 如何卸载 OpenClaw
卸载分两种：保留数据和彻底删除。
先记住一句：删除本地 OpenClaw 不等于撤销模型服务商后台的 API Key。如果你以后不再使用这个 key，还要去模型服务商后台手动禁用或删除它。
新手建议先做“保留数据”的卸载。
23.1 停止并移除容器，但保留数据
进入 OpenClaw 目录：
cd /opt/openclaw-worker
macOS / WSL2 用户：
cd ~/openclaw-worker
停止并移除容器：
docker compose down
这通常会移除容器和网络，但保留你目录里的文件，例如：
state/
workspace/
auth-profile-secrets/
reports/
backups/
以后你还可以重新启动。
23.2 删除镜像
如果你想删除本地镜像，可以先查看镜像：
docker images
找到 OpenClaw 相关镜像后删除：
docker rmi IMAGE_NAME_OR_ID
注意把：
IMAGE_NAME_OR_ID
换成真实镜像名或镜像 ID。
如果你不确定哪个镜像是 OpenClaw，不要乱删。
23.3 彻底删除本地文件
如果你确定不要这些数据了，可以删除工作目录。
Linux 示例：
sudo rm -rf /opt/openclaw-worker
macOS / WSL2 示例：
rm -rf ~/openclaw-worker
注意：这一步会删除：
- 配置
- 工作区文件
- 状态
- API Key 保存目录
- 报告
- 备份
执行前请确认你真的不需要了。
更稳妥的方式是先改名保留一段时间：
Linux：
sudo mv /opt/openclaw-worker /opt/openclaw-worker.old
macOS / WSL2：
mv ~/openclaw-worker ~/openclaw-worker.old
确认一段时间后不再需要，再删除 .old 目录。
24. 常见错误 1：No API key found
如果你看到：
No API key found
意思是：OpenClaw 没找到可用的 API Key。
常见原因：
- onboard 时 API Key 没保存成功
- provider id 写错了
- 当前容器没有挂载认证目录
- 你在另一个用户或另一个环境里运行命令
- API Key 放错位置了
- 宿主机和容器里的配置目录不是同一个
建议先运行：
openclaw models status
看看模型状态里是否提示认证缺失。
然后检查你是否正确使用了：
--custom-api-key
也要确认部署时有保留类似目录：
/opt/openclaw-worker/auth-profile-secrets
这个目录用于保存认证信息，但不要把里面内容公开。
25. 常见错误 2：thinking low unsupported
如果你看到类似：
thinking low unsupported
意思是：当前模型不支持这个 thinking 设置。
这不是说模型一定坏了，而是它可能不认识这个参数。
解决方式很简单：
测试时加上：
--thinking off
例如：
openclaw agent \
--model openai-compatible-demo/demo-chat-model \
--thinking off \
--message "Reply with exactly: OPENCLAW_AGENT_OK"
如果关闭 thinking 后成功，说明模型本身可以用，只是不支持 thinking 参数。
26. 常见错误 3：healthz 正常，但模型没通
有时你运行：
curl http://127.0.0.1:18789/healthz
结果正常，但模型测试失败。
这很常见，因为：
healthz 只说明 Gateway 活着，不说明模型配置正确。
你应该继续用这三条命令完整验证：
openclaw models status
openclaw infer model run \
--model openai-compatible-demo/demo-chat-model \
--prompt "Reply with exactly: MODEL_OK"
openclaw agent \
--model openai-compatible-demo/demo-chat-model \
--thinking off \
--message "Reply with exactly: OPENCLAW_AGENT_OK"
只有这几步都通过，才说明模型和 agent 的基础链路比较可靠。
27. 常见错误 4：gateway pairing / scope pending
如果你看到类似：
pairing pending
或者：
scope pending
可以先简单理解为：
Gateway 还没有完成某些连接、配对或授权。
这通常和外部客户端、消息通道、节点连接有关，不一定是模型本身的问题。
可能原因包括：
- 客户端还没有完成配对
- 当前会话权限不够
- 某个消息通道还没授权
- Gateway 启动了，但入口还没完全连好
这时你可以分开判断：
healthz正常：Gateway 活着infer model run正常：模型能调用agent run正常：agent 能使用模型- pairing / scope pending：外部接入或授权还需要继续处理
不要把这些问题混在一起排查。
28. 常见错误 5：Connection refused
如果你看到类似：
Connection refused
通常表示连接不上服务。
可能原因：
- Gateway 没启动
- 端口写错了
- 容器启动失败
- 你在错误的机器上访问
- Docker Desktop 没运行
- WSL2 和 Windows 环境没连上
排查顺序：
docker compose ps
看容器是否运行。
再看日志：
docker compose logs --tail=100
再检查端口：
curl http://127.0.0.1:18789/healthz
如果是在 WSL2 里运行 OpenClaw，就尽量也在 WSL2 里执行这些命令，不要在 Windows PowerShell 和 WSL2 之间来回混用。
29. 常见错误 6：model not found
如果你看到类似：
model not found
常见原因：
--custom-model-id写错了- 模型供应商没有开放这个模型
- 你的账号没有权限使用这个模型
provider-id/model-id拼错了- 模型服务实际要求另一个模型名称
先检查：
openclaw models status
再检查你运行命令里的模型名：
provider-id/model-id
例如你 onboard 时写的是：
openai-compatible-demo
模型是：
demo-chat-model
那运行时应该写：
openai-compatible-demo/demo-chat-model
不要写成：
demo-chat-model
也不要写成：
openai-compatible-demo
30. 常见错误 7：401 / 403
如果你看到：
401 Unauthorized
或者：
403 Forbidden
通常和认证或权限有关。
常见原因：
- API Key 错了
- API Key 已过期
- API Key 被禁用
- 当前账号没有权限使用这个模型
- 模型服务限制了 IP 或地区
- base URL 填到了错误的平台
建议：
- 去模型服务商后台确认 API Key 是否有效
- 确认账号是否还有额度
- 确认模型 ID 是否对当前账号开放
- 重新 onboard 一次
- 再运行
infer model run测试
31. 常见错误 8：429 / rate limit
如果你看到：
429 Too Many Requests
或者提示：
rate limit
通常表示请求太频繁或额度限制。
解决方式：
- 等一会儿再试
- 降低并发
- 换更高额度的模型服务
- 检查是否有程序在循环调用模型
- 查看供应商后台的用量统计
新手不要写循环脚本疯狂测试模型。每次测试用一条简单 prompt 就够了。
32. 常见错误 9：context length exceeded
如果你看到类似：
context length exceeded
意思是输入内容太长，超过了模型上下文限制。
解决方式：
- 缩短 prompt
- 少贴一点日志
- 分批处理文件
- 换上下文更长的模型
- 让 agent 先总结，再继续下一步
新手常见错误是一次性把几万行日志全部塞给模型。更好的方式是：
- 先让它看最后 100 行
- 再根据错误关键词扩大范围
- 必要时分段分析
33. 常见错误 10：Docker permission denied
如果你看到类似：
permission denied
并且和 Docker 有关，可能是当前用户没有权限使用 Docker。
可以临时用：
sudo docker compose ps
如果这样能成功，说明是 Docker 权限问题。
你可以选择：
方式 A：继续使用 sudo
sudo docker compose up -d
方式 B：把当前用户加入 docker 组
sudo usermod -aG docker "$USER"
然后重新登录终端。
注意：加入 docker 组会提升用户权限。多人服务器上要谨慎。
34. FAQ
Q1：OpenClaw 是聊天机器人吗？
不完全是。
聊天机器人主要是回答问题。OpenClaw 更像一个受控执行环境，可以在你允许的范围内读文件、写文件、运行命令、生成报告、执行任务。
Q2：我一定要用 Docker 吗？
不一定，但新手推荐 Docker Compose。
Docker Compose 的好处是：
- 部署结构清楚
- 配置集中
- 容器容易启动和停止
- 数据目录可以单独挂载
- 出问题时比较容易回滚
如果你非常熟悉裸机部署，也可以按官方文档使用其他方式。
Q3：为什么不建议直接暴露到公网？
因为 Gateway 是控制入口。
如果你把它直接暴露到公网，就要考虑认证、访问控制、防火墙、反向代理、TLS、日志审计等问题。
新手阶段建议只绑定：
127.0.0.1
如果以后确实需要公网访问，请先理解安全配置，再做暴露。
Q4：127.0.0.1 和 0.0.0.0 有什么区别？
简单理解：
127.0.0.1
只允许本机访问。
0.0.0.0
通常表示监听所有网卡，外部机器也可能访问到。
新手优先用：
127.0.0.1
Q5：我可以把 API Key 写进 docker-compose.yml 吗？
不推荐。
docker-compose.yml 经常会被复制、备份、发给别人排查，甚至提交到 Git。把 API Key 写进去很容易泄露。
更推荐使用 OpenClaw 自己的 onboard / secrets 机制，或者使用受保护的环境变量和密钥管理方式。
Q6：我可以截图给别人看配置吗？
可以，但要先打码。
重点遮住：
- API Key
- token
- cookie
- 服务器公网 IP
- 内网敏感地址
- 用户名
- 私有仓库地址
- 生产数据库连接信息
如果不确定，就不要发原图。
Q7：healthz 正常是不是说明全部成功？
不是。
healthz 只说明 Gateway 活着。
你还需要测试：
openclaw models status
openclaw infer model run \
--model openai-compatible-demo/demo-chat-model \
--prompt "Reply with exactly: MODEL_OK"
openclaw agent \
--model openai-compatible-demo/demo-chat-model \
--thinking off \
--message "Reply with exactly: OPENCLAW_AGENT_OK"
Q8：为什么要加 --thinking off？
因为有些 OpenAI-compatible 模型不支持 thinking / reasoning 参数。
第一次测试时加上：
--thinking off
可以减少兼容问题。
等基础链路跑通后，再根据模型能力尝试开启其他参数。
Q9：我能让 OpenClaw 管理 Docker 吗？
可以，但新手不建议一开始就这样做。
尤其不要随便挂载：
/var/run/docker.sock
这会让容器拥有很高的 Docker 控制权限。不了解风险前，不要随便给。
Q10：我能让 OpenClaw 直接改生产网站吗？
不建议新手这样做。
更安全的流程是：
- 让 OpenClaw 生成草稿或 patch
- 你自己 review
- 在测试环境验证
- 再发布到生产
生产系统不要直接交给刚配置好的 agent。
Q11：可以同时接多个模型吗？
可以。
建议每个模型使用不同的 provider id，例如：
fast-model
cheap-model
coding-model
company-gateway
使用时通过：
provider-id/model-id
来指定。
Q12：换模型后原来的模型会消失吗？
不一定。
如果你使用新的 provider id，通常是新增模型。
如果你复用同一个 provider id，可能会更新原配置。
新手建议新增模型时使用新的 provider id，避免混淆。
Q13：我应该选什么模型？
新手可以按用途分：
- 写作、总结：便宜、速度快的模型
- 代码、复杂任务：能力更强的模型
- 长日志分析：上下文更长的模型
- 私有数据：优先考虑可信服务或私有部署
不建议只看价格，也不建议只看参数规模。实际能不能稳定调用、是否兼容 OpenAI API、错误信息是否清楚，也很重要。
Q14：OpenClaw 会不会自动把我的文件发出去？
只要模型调用发生，发送给模型的 prompt 和上下文就可能离开本机，进入模型服务商的 API。
所以新手要注意：
- 不要让它读取敏感目录
- 不要把密钥贴进 prompt
- 不要让它总结包含隐私的日志
- 不要把生产数据库内容交给外部模型
如果你处理高度敏感数据，应该使用可信的私有模型服务，并严格限制工作目录。
Q15：我可以把 auth-profile-secrets/ 提交到 Git 吗？
不可以。
这个目录可能包含认证信息。应该加入 .gitignore，不要提交到任何公开或不可信仓库。
Q16：升级前一定要备份吗？
强烈建议。
至少备份：
docker-compose.yml
state/
auth-profile-secrets/
如果升级失败，备份能帮你回滚。
Q17：卸载时可以直接删目录吗？
可以，但不推荐一上来就删。
更稳妥的方式是先：
docker compose down
然后把目录改名保留：
mv ~/openclaw-worker ~/openclaw-worker.old
确认不再需要后，再删除。
Q18：为什么建议用独立目录？
因为独立目录更容易：
- 备份
- 排查
- 卸载
- 控制权限
- 避免误伤其他项目
不要一开始就把 OpenClaw 放进你的主项目、生产目录或私人文件夹里。
35. 安全提醒：新手一定要记住
OpenClaw 能做很多事，所以更要注意边界。
不要在群里贴 API Key
API Key 就像密码，泄露后可能被别人使用你的额度。
不要裸露 Gateway
新手优先绑定：
127.0.0.1
不要直接开放到公网。
不要随便挂 docker.sock
docker.sock 会给容器很高的 Docker 控制权限。不了解风险前，不要随便挂载。
生产站点先写草稿
如果你要让 OpenClaw 帮你写博客、改页面、生成配置，先让它输出草稿或报告。确认没问题后，再手动发布或由可靠流程发布。
不要一开始给全部权限
先让它在类似下面的目录里工作：
/opt/openclaw-worker/workspace
或者：
~/openclaw-worker/workspace
等你确认它稳定可靠，再逐步增加能力。
不要让它读取敏感目录
新手不要让 OpenClaw 随便读取：
~/.ssh
~/.config
/etc
数据库备份目录
生产密钥目录
浏览器配置目录
如果需要分析配置，先复制一份脱敏后的样本到 workspace。
不要让模型看到真实密钥
即使你信任 OpenClaw，也不代表你应该把密钥发给外部模型。
排查问题时，可以把真实值替换成：
REDACTED_API_KEY
REDACTED_PASSWORD
REDACTED_TOKEN
36. 推荐的新手流程
如果你是第一次部署，可以按这个顺序来：
- 准备 Docker
- 准备
/opt/openclaw-worker或~/openclaw-worker - 创建
state、workspace、auth-profile-secrets - 用 Docker Compose 启动 OpenClaw
- 确认 Gateway 只绑定本机地址
- 用 onboard 添加自定义模型
- 用
models status检查模型状态 - 用
infer model run测试模型 - 用
agent --thinking off测试 agent - 先让 OpenClaw 写草稿、查日志、生成报告
- 不要马上给生产系统写权限
- 确认稳定后，再考虑升级权限和接入更多工具
这样一步一步来，成功率更高，也更安全。
37. 完成检查清单
部署完成后，可以对照下面检查：
- [ ] 已安装 Docker
- [ ] 已安装 Docker Compose
- [ ] Linux 用户知道自己的部署目录
- [ ] macOS 用户已启动 Docker Desktop
- [ ] Windows 用户已使用 WSL2
- [ ] 已创建独立目录，例如
/opt/openclaw-worker或~/openclaw-worker - [ ] 已准备
state/ - [ ] 已准备
workspace/ - [ ] 已准备
auth-profile-secrets/ - [ ] 已准备
reports/ - [ ] 已准备
backups/ - [ ] 已创建
docker-compose.yml - [ ] Gateway 没有直接暴露到公网
- [ ] 端口优先绑定到
127.0.0.1 - [ ]
docker compose ps能看到服务运行 - [ ]
curl http://127.0.0.1:18789/healthz返回正常 - [ ] 已使用
openclaw onboard添加自定义模型 - [ ] onboard 命令包含
--auth-choice custom-api-key - [ ] onboard 命令包含
--custom-provider-id - [ ] onboard 命令包含
--custom-base-url - [ ] onboard 命令包含
--custom-model-id - [ ] onboard 命令包含
--custom-api-key - [ ] onboard 命令包含
--custom-compatibility openai - [ ]
openclaw models status能看到模型 - [ ]
openclaw infer model run能返回预期内容 - [ ]
openclaw agent --thinking off能返回OPENCLAW_AGENT_OK - [ ] 没有在公开地方泄露 API Key
- [ ] 没有随便挂载
docker.sock - [ ] 没有直接给生产站点写权限
- [ ] 已理解
healthz只代表 Gateway 活着，不代表模型一定配置成功 - [ ] 已知道如何停止服务：
docker compose stop - [ ] 已知道如何卸载容器：
docker compose down - [ ] 已知道升级前要备份
state/和auth-profile-secrets/
38. 最后建议
OpenClaw 最适合的起步方式，不是“一次给它所有权限”，而是先把它当成一个可靠 worker：
让它在清楚的边界里帮你执行任务、生成草稿、检查问题。
等你熟悉之后，再逐步扩大它能做的事情。
新手最稳的路线是：
先跑通模型 → 再跑通 agent → 再限制目录做小任务 → 再逐步增加能力
不要急着把生产系统交给它。
先让它在安全的工作区里，把一件小事做好。
39. 本文发布前的审核重点
这篇文章适合小白照着做，但仍然有几件事要自己核对：
- OpenClaw 版本可能变化，命令参数以你当前版本的
--help为准。 - Docker Compose 的镜像名和挂载路径以官方文档或你的实际部署文件为准。
- 自定义模型的
base_url和model_id必须看供应商文档，不要猜。 - API Key 不要贴进聊天、文章、截图、Git 仓库。
- 如果教程里的
openclaw ...命令不可用，先确认你的 CLI 是宿主机安装，还是通过docker compose run --rm openclaw-cli ...执行。 - 发布到生产网站、修改主题、改服务器配置之前，先做草稿和备份。
