前言：从 0 开始在 Ubuntu 22.04 安装 OpenClaw（2026.3.2），接入试用模型（ModelScope），允许其他内网电脑可访问。

1. 适用环境

  • 系统：Ubuntu 22.04（Desktop/Server 均可）
  • OpenClaw：2026.2.26（后自动升级为2026.3.2）（本文按该版本写）
  • 网络：可联网安装依赖

2. 最低配置建议（硬件）

  • CPU：2 核以上（建议 4 核）
  • 内存：4 GB 起步（建议 8 GB+）
  • 磁盘：至少 5 GB 可用空间
  • 网络：稳定外网（安装依赖）+ 内网（供其他设备访问）

3. 安装前准备（必须做）

3.1 更新系统与基础工具

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git python3 build-essential libssl-dev ufw

3.2 安装 Node.js 22+

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version
npm --version

要求：node --version 至少 v22.x.x。

3.3（可选）国内 npm 加速

npm config set registry https://registry.npmmirror.com
npm config get registry

4. 安装 OpenClaw

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

勾选yes，一路默认能跳过的跳过，配错了也没关系后面都可以改

5. 首次初始化配置

5.1检查环境，默认是错误的

检查 openclaw 是否在 PATH 中

which openclaw

如果找不到，查看 npm 全局安装目录

npm prefix -g

查看当前 shell

echo $SHELL

将 npm 全局 bin 目录添加到 PATH

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc

重新加载配置文件

source ~/.bashrc

验证添加是否成功

echo $PATH | grep npm

5.2 检查网关

openclaw dashboard --no-open
可以得到网关的token，用于浏览器访问
在这里插入图片描述

5.3 运行向导：

openclaw configure

建议：

  • Gateway 运行位置：Local (this machine)
  • Gateway 端口：18789
  • Gateway bind：先用 loopback（先本机跑通），后面再改内网

6. 接入国产模型（ModelScope）

6.1 准备 token

在开源社区 ModelScope 生成 token：
https://modelscope.cn/my/access/token

每天有免费额度，可选多个模型，如果正式大量使用请到模型官网购买

6.2 向导里配置模型（推荐）

在 openclaw configure --section model 中：
在这里插入图片描述

  • Model/auth provider 选 Custom Provider

    在这里插入图片描述

  • API Base URL 填：
    https://api-inference.modelscope.cn/v1

  • API Key：填 ModelScope token

  • Endpoint compatibility：OpenAI-compatible

  • Model ID：填可用模型（例如 ZhipuAI/GLM-5）

  • 在这里插入图片描述

    然后随便起配置的名字即可

    在这里插入图片描述

7. 关键坑：聊天功能障碍

7.1 安装时随便填的模型导致缓存

首先要去掉安装过程中随便选的模型
在这里插入图片描述

参考步骤6重新配置后，新建会话即可

7.2 contextWindow 被写成 4096

现象描述

如果聊天报错：

  • Model context window too small (4096 tokens). Minimum is 16000

    提示上下文大小不符合要求，但是实际查到GLM5的上下文远超过16K在这里插入图片描述

原理分析

说明模型配置里上下文被写小了。

推测走的是 Custom Provider + OpenAI-compatible。

所以很多兼容端点（含部分 ModelScope 路由）不会在 OpenClaw可识别的位置返回 context window 元数据。

导致OpenClaw拿不到元数据时按 4096 处理，于是触发「小于 16000」拦截。

cat ~/.openclaw/openclaw.json很明显看到新加的模型都被限制了大小

解决办法：

编辑文件：

vi ~/.openclaw/openclaw.json

把你使用的模型项改为（示例）：

"contextWindow": 131072,
"maxTokens": 16384

在这里插入图片描述

说明：

  • contextWindow：建议 131072（128K，稳定）
  • maxTokens：建议 8192 或 16384（越大越慢）

注意：某些版本里 openclaw config set 对带 - 的 provider 名可能路径解析异常，手改 openclaw.json 更稳。

8. 启动/重启网关

本版本没有 openclaw restart，正确命令：

openclaw gateway --force

健康检查：

openclaw health

看监听端口：

sudo ss -ltnp | grep 18789

在这里插入图片描述

本地即可正常运行了，可以告一段落
在这里插入图片描述

本地运行完毕

9. 让其他内网电脑访问（不走 SSH）

通过ssh可以搭建本地隧道，让远程电脑也通过120.0.0.1:18789的形式访问

ssh -N -L 18789:127.0.0.1:18789 mustocs@10.0.0.82

为了团队使用或者自己多设备使用方便

9.1 先改 bind 为 LAN

运行：

openclaw configure --section gateway

建议：

  • Gateway bind mode：LAN (All interfaces)

  • Gateway auth：Password（建议强密码）

    在这里插入图片描述

9.2 处理 2026.3.2 的 Control UI 安全校验

在 2026.3.2，若直接 HTTP 内网访问，常见报错为：

  • requires device identity (use HTTPS or localhost secure context)

需要新增两个字段 当前内网IP

"controlUi": {

  "allowedOrigins": [

  "http://10.0.0.82:18789",  

  ]

 }

和安全策略

"allowInsecureAuth": true,

"dangerouslyDisableDeviceAuth": true,

要实现“内网 HTTP 直连”，配置必须写在 gateway.controlUi 下（不是 gateway 顶层）：

"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "lan",
  "auth": {
    "mode": "password",
    "password": "请改成强密码"
  },
  "controlUi": {
    "allowInsecureAuth": true,
    "dangerouslyDisableDeviceAuth": true,
    "allowedOrigins": [
      "http://10.0.0.82:18789"
    ]
  }
}

然后重启：

openclaw gateway --force

10. 防火墙放行

sudo ufw allow 18789/tcp
sudo ufw reload
sudo ufw status

11. 其他内网电脑访问方式

在同一内网（或同一 WireGuard 网段）设备访问：

http://10.0.0.82:18789/chat?session=main

如果打不开，按顺序排查：

  1. sudo ss -ltnp | grep 18789（是否监听 0.0.0.0/LAN）
  2. sudo ufw status（是否放行 18789）
  3. 对端是否能 ping 通 10.0.0.82

12. WireGuard（可选其他，用于跨网段内网访问）

以分配好了内网网段拥有配置文件hanxin_pc2.conf为例

启动

sudo install -m 600 ~/hanxin_pc2.conf /etc/wireguard/hanxin_pc2.conf
sudo apt install -y openresolv
sudo wg-quick up hanxin_pc2

关闭

sudo wg-quick down hanxin_pc2

状态

sudo wg show
ip a | grep hanxin_pc2

在这里插入图片描述

访问http://10.0.0.82:18789/

在概览/overview里面输入密码1024，点击连接/connect
在这里插入图片描述

检查模型正确
在这里插入图片描述

恭喜，已经可以开始简单的对话了
在这里插入图片描述

13. 常见报错与处理

13.1 No API key found for provider "z.ai"

原因：当前会话/agent 仍在走旧 provider。
处理：在 Agents -> main 把主模型切到你新配置的 custom 模型，清空 fallbacks，保存后 New session。

13.2 Model context window too small (4096)

原因：openclaw.json 里的模型元数据是 4096。
处理：手改该模型的 contextWindow（>=16000）并重启网关。

13.3 gateway.bind: Invalid input

原因：手填了 schema 不支持的值（例如直接写 0.0.0.0）。
处理：用 openclaw configure --section gateway 选择 LAN，不要随便猜枚举值。

13.4 Unrecognized keys: allowInsecureAuth...

原因：键放错层级。
正确位置：gateway.controlUi.allowInsecureAuth、gateway.controlUi.dangerouslyDisableDeviceAuth。

14. 推荐日常操作命令（速查）

# 启动/重启网关
openclaw gateway --force

# 健康检查
openclaw health

# 查看日志
openclaw logs --follow

# 查看当前监听
sudo ss -ltnp | grep 18789

# 重新进配置向导
openclaw configure
openclaw configure --section model
openclaw configure --section gateway

15. 最后建议

  • 先本机跑通，再做内网访问。

  • 模型能连通后，先发 只回复OK 做最小验证。

  • 每次改配置后都执行一次 openclaw gateway --force。

  • 遇到报错先看 openclaw logs --follow，不要盲改。

# 语言模型
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

OpenClaw+GLM-4.7-Flash语音交互：对接Whisper实现语音控制

本文介绍了如何在星图GPU平台上自动化部署【ollama】GLM-4.7-Flash镜像，构建语音交互系统。该系统结合Whisper语音识别与GLM-4.7-Flash的指令理解能力，实现智能家居控制等场景的语音操作，提升日常任务执行效率。

avatar 龙虾开发者社区

学生党福音：OpenClaw+nanobot搭建学习监督助手

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，构建智能学习监督助手。该方案利用轻量级模型实现网课进度跟踪、自动生成练习题和错题整理功能，特别适合学生群体通过QQ机器人实现移动端学习管理，显著提升学习效率。

avatar 龙虾开发者社区

OpenClaw创意工坊：用nanobot镜像生成技术海报文案

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，快速生成技术海报文案。该镜像基于Qwen3-4B模型，能将复杂技术术语转化为通俗表达，适用于技术活动宣传、社交媒体推广等场景，显著提升内容创作效率。

avatar 龙虾开发者社区