OpenClaw 保姆级安装教程（2026.2.26）与自定义模型配置详解

概述

OpenClaw 是一个自托管的个人 AI 助手网关（Gateway），它作为统一的控制平面，将你常用的聊天应用（WhatsApp、Telegram、Discord、Slack 等）连接到 AI 编程代理。你可以在自己的设备上运行 OpenClaw，保持对数据的完全控制。

参考来源：

• OpenClaw 官方文档
• OpenClaw GitHub 仓库
• OpenClaw 安装页面

---

系统要求

项目	要求
Node.js	≥ 22（通过 node --version 检查）
操作系统	macOS、Linux (Window超级不稳定，建议在WSL2上安装)
AI 提供商密钥	Anthropic API Key（推荐）、OpenAI 或自定义提供商
预计耗时	约 15 分钟

---

安装

3.1 安装 Homebrew（MacOS 如未安装）

PS: 非MacOS直接忽略此步骤，直接进行3.2

macOS 系统需要先确认是否已安装 Homebrew在终端中执行 brew --version，如果提示未找到命令，则需先安装：

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

3.2 安装 OpenClaw

安装脚本会自动处理 Node.js 检测、安装和初始化引导（Onboarding），是官方推荐的安装方式：

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

这一步主要是在提醒你，使用 OpenClaw 可能会有一些安全风险，请务必阅读并理解。选择 Yes 继续安装。

如果你和我的显示不一样，可以按 ctrl+c 退出，然后重新执行命令。

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

继续选择 Yes，用于创建网关以及生成网关的 token。

继续选择 Yes，给 ~/.openclaw 目录赋予 700 权限。

继续选择 Yes，创建 Session 存储目录。

继续选择 Yes，为 openclaw 启用 bash shell 补全功能。

继续选择 Yes，创建网关服务。

只有 Node 一个选项，直接回车即可。

出现上面的界面，带有 http://127.0.0.1:18789，就是安装完成了。

到这里，我们还没有给 openClaw 配置相应的模型。手动执行下方引导命令，我们去完成模型配置。

openclaw onboard

选择 yes，我知晓是个人使用的，不做其他限制。

选择 QuickStart 快速开始。

选择 Use existing values 选择使用存在的配置。

这里我们选择 Custom Provider 自定义提供商。

输入自定义提供商的 Base URL，我这里输入的是朋友的公益站点的，如果你没有其他可选择的，也可以使用这个。

输入 API key，这个是在自定义提供商里面创建的，对应的是密钥。

选择端点兼容性，我这里选择的是 OpenAI-compatible，适配 openai 格式的。

输入模型ID，我这里输入的是 gpt-5.3-codex。

输入端点ID，这里是他根据模型提供商的域名自动生成的，一般无需改动，但这里要记一下（例如 custom-claude-chiddns-com），后面我们设置上下文大小以及最大tokens时，要用到。

模型别名，可选，直接回车即可，不用设置。

选择channel，这里我们先跳过，选择 Skip for now。

是否配置技能，这里还是选择先不配置，选择 No。

是否配置hooks，选择 Skip for now。

重启网关，选择 Restart。

这里选择 Do this later。

截止到这里，OpenClaw在配置自定义模型提供商时，默认的上下文窗口和最大Tokens参数会过于小，导致无法成功调用，我们需要在终端执行以下命令。

PS：注意需要调整上面要大家记住的端点ID，我的是 custom-claude-chiddns-com，按实际的进行替换。

# 设置上下文窗口、设置最大tokens
openclaw config set 'models.providers.custom-claude-chiddns-com.models[0].contextWindow' 400000
openclaw config set 'models.providers.custom-claude-chiddns-com.models[0].maxTokens' 128000

# 查询配置
openclaw config get 'models.providers.custom-claude-chiddns-com.models[0]'

到这里我们就完成全部安装以及自定义模型配置。整个配置流程和详细的参数设置，都可以在 云栈社区的技术文档 板块找到更多相关的实践讨论。

---

验证安装

4.1 检查服务状态

# 查看网关运行状态
openclaw gateway status

# 全面诊断检查（配置、连接、权限等）
openclaw doctor

# 查看整体状态
openclaw status

4.2 访问控制界面

终端环境（无桌面 / 服务器，推荐）：

# 通过 TUI 在终端中直接管理
openclaw tui

桌面环境：

# 启动 Web 控制台
openclaw dashboard

或在浏览器中访问：http://127.0.0.1:18789/

4.3 前台调试运行

如需调试，可在前台启动网关查看实时日志：

openclaw gateway --port 18789

---

核心文件与目录

路径	说明
~/.openclaw/openclaw.json	主配置文件（JSON5 格式）
~/.openclaw/workspace	代理工作空间
~/.openclaw/.env	环境变量文件（存放 API Key 等敏感信息）

环境变量

可通过环境变量覆盖默认路径：

变量	说明
OPENCLAW_HOME	OpenClaw 主目录
OPENCLAW_STATE_DIR	状态数据存储目录
OPENCLAW_CONFIG_PATH	配置文件路径

---

基础配置说明

配置文件 ~/.openclaw/openclaw.json 采用 JSON5 格式，缺失时使用安全默认值。可通过以下方式管理配置：

# 通过向导修改配置
openclaw configure

# 查看当前配置
openclaw config get

最小配置示例

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  }
}

配置热更新

OpenClaw 支持混合重载模式：

• 安全变更（如渠道设置）— 即时热更新，无需重启
• 基础设施变更（如端口、认证）— 需要重启网关

---

常用命令速查

命令	说明
openclaw onboard	运行引导向导
openclaw gateway	启动网关
openclaw gateway status	查看网关状态
openclaw dashboard	打开 Web 控制台
openclaw doctor	诊断检查
openclaw status	查看整体状态
openclaw logs --follow	实时查看日志
openclaw channels login	登录聊天渠道
openclaw configure	修改配置
openclaw config get	查看当前配置
openclaw agents add	添加额外代理实例

---

常见问题

Q1: 启动时报 EADDRINUSE 错误？

已有另一个网关实例占用了端口。检查并关闭已有进程，或更换端口：

openclaw gateway --port 18790

Q2: 控制台无法访问？

• 确认网关正在运行：openclaw gateway status
• 如果提示 "device identity required"，说明需要完成设备认证流程
• 非本地回环地址绑定时需先配置认证

Q3: 升级后功能异常？

升级可能导致默认值变更。检查配置并强制重新安装元数据：

openclaw config get
openclaw gateway install --force

Q4: 如何更新 OpenClaw？

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

---

参考资料

1. OpenClaw 官方文档 — https://docs.openclaw.ai
2. OpenClaw GitHub 仓库 — https://github.com/openclaw/openclaw
3. 快速开始指南 — https://docs.openclaw.ai/start/quickstart
4. 引导向导说明 — https://docs.openclaw.ai/start/wizard
5. 配置文档 — https://docs.openclaw.ai/gateway/configuration
6. 故障排查 — https://docs.openclaw.ai/gateway/troubleshooting