Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

CNB Ubuntu Web Terminal

这是一个部署在 CNB 预览环境中的 Ubuntu Web Terminal 项目。

项目使用 ttyd 提供浏览器终端，再由 web_terminal_gate.py 在前面加一层密码登录页和 Cookie 会话校验，用来快速搭建受密码保护的在线终端。当前版本在保证 Preview 首屏稳定的前提下，额外补上了 OpenClaw / Codex CLI 的后台安装、OpenClaw 的 CNB provider 自动配置，以及登录终端后的 AI CLI Status 欢迎卡片。

功能特性

基于 Ubuntu 24.04
通过 ttyd 提供浏览器终端
支持 HTTP 和 WebSocket 请求转发
使用密码页 + Cookie 会话保护入口
适配 CNB 预览环境的启动流程
终端页面自动发送保活心跳，降低空闲回收概率
终端右下角显示保活状态面板，便于观察最近成功时间和连续失败次数
预览页就绪后后台自动安装 OpenClaw / Codex CLI
根据 CNB_API_ENDPOINT、CNB_REPO_SLUG、CNB_TOKEN 后台生成 OpenClaw 的 CNB provider 配置
登录 Shell 时显示 AI CLI Status 欢迎卡片，汇总版本、配置、默认通道和工作目录状态
浏览器终端默认通过 tmux 维持持久会话，断线重连后会尽量回到原来的 Shell
可选在 OpenClaw CLI 就绪后后台自动安装 openclaw-mcp-adapter
自动把 cnbcool 与 bing 两个默认 MCP server 写入 openclaw-mcp-adapter 配置，并补上 plugins.allow 白名单
默认写入 OpenClaw browser 配置，并在镜像里预装 Chromium-based browser 运行时
支持手动启动 OpenClaw Gateway，进一步接入 TUI、QQ Bot、小艺、浏览器自动化等外部会话入口

默认配置

推送到 main 并触发 CNB 预览后，默认配置如下：

监听端口：8686
工作目录：/workspace
Shell：/bin/bash -l
默认密码：OpenClaw@2026
登录页路径：/_terminal_login
登出路径：/_terminal_logout
OpenClaw 自动安装：开启
Codex CLI 自动安装：开启
AI CLI Status 欢迎卡片：开启

使用边界

当前方案更适合验证、调试、演示和短周期协作
keepAliveTimeout 主要用于降低空闲回收概率，不等于无限保活
如果你要运行长期在线的 Gateway、QQ Bot 或其他后台服务，建议迁移到常驻平台

主要文件

.cnb.yml：CNB 构建与预览配置
Dockerfile：镜像构建定义
start.sh：启动 ttyd、等待预览就绪并后台拉起自动安装任务
install_ai_clis.sh：手动一键重装 OpenClaw / Codex CLI
install_openclaw_cli.sh：单独安装 OpenClaw CLI
install_codex_cli.sh：单独安装 Codex CLI
configure_openclaw_cnb.py：根据 CNB 环境变量写入 OpenClaw 配置
ai_cli_welcome.sh：登录 Shell 时输出 AI CLI Status 欢迎卡片
ai_cli_path_profile.sh：为 login shell 自动补上 AI CLI NPM prefix，避免 openclaw / codex 命令丢失
setup_openclaw_qqbot.sh：只输入 AppID:AppSecret 就能一键配置 QQ Bot 渠道与 Gateway
setup_openclaw_xiaoyi.sh：运行时只输入 AK / SK，脚本会从环境变量或现有配置兜底 agentId，并一键配置 小艺 渠道与 Gateway
shell_history_persist.sh：为 bash 开启历史实时落盘，降低断线后历史丢失概率
skills/：项目内置的本地 OpenClaw skills，会随工作区自动被发现
web_terminal_gate.py：登录页、Cookie 会话与反向代理逻辑
README.md：项目说明

启动流程

start.sh 启动内部 ttyd 服务
默认通过 tmux new-session -A 挂起持久终端会话，浏览器重连时尽量回到同一个 Shell
web_terminal_gate.py 对外提供登录页、会话校验和请求转发
浏览器访问终端地址时，先进入登录页，验证通过后再进入终端
ttyd 就绪后，后台异步执行 OpenClaw / Codex CLI 安装和 OpenClaw 配置写入，不阻塞预览首屏
用户进入 Shell 后，由 /etc/profile.d/zz-ai-cli-welcome.sh 输出 AI CLI Status，由 /etc/profile.d/zz-ai-cli-path.sh 补上 AI CLI 的 PATH，并由 /etc/profile.d/zz-shell-history-persist.sh 启用历史实时落盘

环境变量

WEB_TERMINAL_PORT：对外端口，默认 8686
WEB_TERMINAL_INTERFACE：对外监听地址，默认 0.0.0.0
WEB_TERMINAL_INTERNAL_HOST：内部 ttyd 地址，默认 127.0.0.1
WEB_TERMINAL_INTERNAL_PORT：内部 ttyd 端口，默认 7681
WEB_TERMINAL_WORKDIR：工作目录，默认 /workspace
WEB_TERMINAL_SHELL：Shell 路径，默认 /bin/bash
WEB_TERMINAL_LOGIN：是否使用 login shell，默认 1
WEB_TERMINAL_PERSIST_SESSION：是否通过 tmux 维持持久终端会话，默认 1
WEB_TERMINAL_TMUX_SESSION_NAME：持久终端使用的 tmux session 名称，默认 openclaw
WEB_TERMINAL_PASSWORD：登录密码
WEB_TERMINAL_LOGIN_PATH：登录页路径，默认 /_terminal_login
WEB_TERMINAL_LOGOUT_PATH：登出路径，默认 /_terminal_logout
WEB_TERMINAL_SESSION_TTL：会话有效期，默认 43200 秒
WEB_TERMINAL_TITLE：页面标题
WEB_TERMINAL_SESSION_SECRET：可选，自定义会话签名密钥
WEB_TERMINAL_KEEPALIVE_PATH：浏览器保活请求路径，默认 /healthz
WEB_TERMINAL_KEEPALIVE_INTERVAL_MS：浏览器保活间隔，默认 240000 毫秒；当前 .cnb.yml 已设置为 60000 毫秒
AI_CLI_NPM_PREFIX：npm -g 安装前缀，默认 /workspace/.npm-global
OPENCLAW_AUTO_INSTALL：是否后台自动安装 OpenClaw CLI
OPENCLAW_NPM_PACKAGE：OpenClaw 安装包版本，默认 openclaw@latest（实际安装时会使用镜像源当前可用最新版）
OPENCLAW_NPM_REGISTRY：OpenClaw 安装源，默认项目里预设的镜像源
OPENCLAW_INSTALL_MCP_ADAPTER：是否在 OpenClaw CLI 就绪后后台自动安装 openclaw-mcp-adapter
OPENCLAW_MCP_ADAPTER_PACKAGE：openclaw-mcp-adapter 的包版本，默认 openclaw-mcp-adapter@0.1.1
OPENCLAW_CONFIGURE_MCP_SERVERS：是否自动把默认 MCP server 写入 openclaw-mcp-adapter 配置
OPENCLAW_MCP_ENABLE_CNBCOOL：是否启用默认的 cnbcool MCP server
OPENCLAW_MCP_ENABLE_BING：是否启用默认的 bing MCP server
OPENCLAW_INSTALL_LOG：OpenClaw 后台安装日志，默认 /workspace/.openclaw-install.log
OPENCLAW_AUTO_CONFIG：是否后台自动写入 OpenClaw 的 CNB provider 配置
OPENCLAW_CNB_SET_PRIMARY：是否把 CNB provider 设为默认主模型
OPENCLAW_CNB_SET_WORKSPACE：是否在自动配置时把 OpenClaw 默认 workspace 指向当前工作区，默认 1
OPENCLAW_AGENT_WORKSPACE：自定义 OpenClaw 默认 workspace，默认跟随 WEB_TERMINAL_WORKDIR 或 /workspace
OPENCLAW_BROWSER_ENABLED：是否自动写入 OpenClaw browser 配置，默认 1
OPENCLAW_BROWSER_HEADLESS：浏览器是否默认使用 headless 模式，默认 1
OPENCLAW_BROWSER_NO_SANDBOX：浏览器是否默认启用 --no-sandbox，容器场景默认 1
OPENCLAW_BROWSER_ATTACH_ONLY：是否只连接已有 CDP browser 而不主动拉起，默认 0
OPENCLAW_BROWSER_DEFAULT_PROFILE：默认浏览器 profile 名称，默认 openclaw
OPENCLAW_BROWSER_CDP_PORT：默认浏览器 profile 的 CDP 端口，默认 18800
OPENCLAW_BROWSER_EXECUTABLE：可选，强制指定 Chromium-based browser 可执行文件路径
OPENCLAW_TOOLS_RELAX_DENY：是否在自动配置时清理掉旧配置里残留的 tools.deny / tools.allow / tools.profile，默认 1
OPENCLAW_TOOLS_ELEVATED_ENABLED：是否开启 tools.elevated.enabled；其余 tools 结构默认对齐参考项目，自动启用 web.search、web.fetch、agentToAgent、exec.applyPatch
OPENCLAW_APPROVALS_WRITE：是否自动写入 ~/.openclaw/exec-approvals.json，默认 1
OPENCLAW_APPROVALS_SECURITY：审批 defaults 的 security，默认 deny
OPENCLAW_APPROVALS_ASK：审批 defaults 的 ask，默认 off
OPENCLAW_APPROVALS_ASK_FALLBACK：审批 defaults 的 askFallback，默认 deny
OPENCLAW_APPROVALS_AUTO_ALLOW_SKILLS：审批 defaults 是否开启 autoAllowSkills，默认 0
OPENCLAW_APPROVALS_AGENT：写入审批配置时使用的 agent id，默认 main
OPENCLAW_APPROVALS_AGENT_SECURITY：指定 agent 覆盖后的 security，默认 full
OPENCLAW_APPROVALS_AGENT_ASK：指定 agent 覆盖后的 ask，默认 off
OPENCLAW_APPROVALS_AGENT_ASK_FALLBACK：指定 agent 覆盖后的 askFallback，默认 full
OPENCLAW_APPROVALS_AGENT_AUTO_ALLOW_SKILLS：指定 agent 覆盖后是否开启 autoAllowSkills，默认 1
OPENCLAW_CONFIG_LOG：OpenClaw 自动配置日志，默认 /workspace/.openclaw-config.log
CODEX_AUTO_INSTALL：是否后台自动安装 Codex CLI
CODEX_NPM_PACKAGE：Codex CLI 安装包版本，默认 @openai/codex@0.111.0
CODEX_INSTALL_LOG：Codex CLI 后台安装日志，默认 /workspace/.codex-install.log
AI_CLI_WELCOME_ENABLED：是否启用登录欢迎卡片，默认 1
AI_CLI_PATH_PROFILE_ENABLED：是否为 login shell 自动补上 AI CLI 可执行目录，默认 1
AI_CLI_HISTORY_PERSIST_ENABLED：是否启用 bash history 实时落盘，默认 1

常用命令

一键重装全部 CLI：bash /usr/local/bin/install_ai_clis.sh
单独重装 OpenClaw：bash /usr/local/bin/install_openclaw_cli.sh（会顺手检查并补装 openclaw-mcp-adapter）
单独重装 Codex CLI：bash /usr/local/bin/install_codex_cli.sh
重新写入 OpenClaw 的 CNB 配置与默认 MCP server：python3 /usr/local/bin/configure_openclaw_cnb.py
启动本地 OpenClaw Gateway：nohup openclaw gateway >/workspace/.openclaw-gateway.log 2>&1 &
查看 OpenClaw 渠道状态：openclaw channels status --probe
打开 OpenClaw TUI：openclaw tui
查看 Browser 状态：openclaw browser --browser-profile openclaw status
启动 Browser：openclaw browser --browser-profile openclaw start
打开页面：openclaw browser --browser-profile openclaw open https://example.com
获取页面快照：openclaw browser --browser-profile openclaw snapshot
截图：openclaw browser --browser-profile openclaw screenshot
查看 OpenClaw 安装日志：cat /workspace/.openclaw-install.log
查看 Codex CLI 安装日志：cat /workspace/.codex-install.log
查看 OpenClaw 配置日志：cat /workspace/.openclaw-config.log
一键配置 QQ Bot：bash /usr/local/bin/setup_openclaw_qqbot.sh "<APP_ID>:<APP_SECRET>"
一键配置 小艺：export XIAOYI_AGENT_ID="<AGENT_ID>" && bash /usr/local/bin/setup_openclaw_xiaoyi.sh
查看 Gateway 日志：tail -n 80 /workspace/.openclaw-gateway.log

使用 OpenClaw

项目默认只负责把 OpenClaw CLI、Codex CLI 和 CNB provider 配置准备好，不会自动常驻启动 OpenClaw Gateway。因此使用方式分成两档：

一次性本地提问：直接使用 agent --local，适合快速验证模型链路。
持续交互或外部渠道：先启动 gateway，再接 tui、qqbot 等入口。

示例：


hash -r
openclaw agents list
openclaw agent --agent main --local --message "用一句话告诉我当前 provider 和 primary model 是什么"

如果你要进入交互式 TUI：


openclaw config set gateway.mode local
nohup openclaw gateway >/workspace/.openclaw-gateway.log 2>&1 &
openclaw tui

工具调用排障

如果你在 agent --local、TUI、QQ Bot 或 小艺 里遇到下面这种邪门现象：

让它 查看当前目录结构，结果只回一个 ls
让它查天气，结果只回一个 read .../SKILL.md
模型看起来理解了任务，但就是不真正执行工具

优先怀疑 tools 配置，而不是先怀疑 cnb/auto。这个仓库已经把默认 tools 结构对齐到参考项目，只显式启用 web.search、web.fetch、agentToAgent、elevated、exec.applyPatch，避免旧版那种过度注入 tools.profile、tools.allow、tools.exec.* 后把工具调用链配拧巴。

快速验证：


openclaw --version
openclaw agent --agent main --local --message "执行 ls，并把 stdout 原样返回，不要只给命令"

如果结果还是只回命令文本，先重新写一遍配置：


python3 /usr/local/bin/configure_openclaw_cnb.py
openclaw agent --agent main --local --message "执行 ls，并把 stdout 原样返回，不要只给命令"

如果你是从旧镜像或旧配置升级上来的，建议再顺手检查：

~/.openclaw/openclaw.json 里的 tools 下是否还残留 profile、allow、deny、exec.security、exec.ask、exec.timeoutSec 这些旧字段
/workspace/.openclaw-config.log 是否显示 tools aligned with reference profile
QQ Bot、小艺 等外部渠道的问题，先用 agent --local 复现一遍；如果本地也只回命令文本，那锅大概率就在公共调用链，不在渠道插件

浏览页面 / Browser

当前镜像会尽量预装一个 Chromium-based browser，并自动把 OpenClaw browser 配置写进 openclaw.json。在容器里默认使用 headless + noSandbox，适合页面浏览、快照、截图、点击和输入这类操作。

最小流程：


openclaw config set gateway.mode local
nohup openclaw gateway >/workspace/.openclaw-gateway.log 2>&1 &
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

如果 status 提示 Browser disabled 或 unavailable，先检查：

python3 /usr/local/bin/configure_openclaw_cnb.py 是否重新写入过配置
openclaw config get browser.executablePath
/workspace/.openclaw-gateway.log 中是否有 browser 启动错误

需要登录的网站请优先走安全路径：不要把密码、OTP、Cookie、Token 直接发给模型；这类流程优先使用 browser-login-helper 做步骤引导和登录后的续跑。

预装 Skills

项目当前内置了一组贴合这个仓库场景的本地 skills。只要 OpenClaw 的默认 workspace 指到 /workspace，这些 skills 就会随工作区自动被发现，不需要额外联网安装。

当前预装的 skills：

repo-quick-map：快速梳理仓库结构、启动链路、关键文件和改动风险
preview-doctor：排查 CNB Preview、登录页、ttyd、终端重连和构建未生效问题
ai-cli-doctor：排查 OpenClaw CLI、Codex CLI、CNB provider 和自动安装链路问题
qqbot-doctor：排查 QQ Bot 插件、Gateway、手机 QQ 对话和沙箱配置问题
git-change-review：按代码审查视角检查当前 diff、回归风险和缺失测试
release-readiness：检查发布前配置、文档、脚本和运行验证缺口
log-triage：分析一份或多份日志，定位首个有效异常和下一步动作
runtime-snapshot：采集当前容器、Gateway、渠道和工作区状态快照
browser-operator：安全地启动浏览器、打开页面、获取快照、截图并执行页面操作
browser-login-helper：处理需要登录的网站时的安全引导，避免把凭证喂给模型

验证方式：


openclaw skills list --eligible
openclaw skills info repo-quick-map
openclaw skills info qqbot-doctor
openclaw skills info git-change-review
openclaw skills info runtime-snapshot
openclaw skills info browser-operator

使用时可以直接在需求里点名，例如：

请用 repo-quick-map 先梳理这个仓库
请用 preview-doctor 看下为什么预览页又断开了
请用 ai-cli-doctor 排查 openclaw 为什么没走到 cnb/auto
请用 qqbot-doctor 看下 QQ 机器人为什么不回消息
请用 git-change-review 审查一下当前改动
请用 release-readiness 看看现在适不适合推 main 或重新构建
请用 log-triage 帮我看下这几份日志里最早的有效报错
请用 runtime-snapshot 先采集一下当前环境状态
请用 browser-operator 帮我打开这个页面并抓一份快照
请用 browser-login-helper 设计一个安全的登录后续跑流程

对接 QQ 机器人

当前推荐通过 @sliverp/qqbot 插件把 QQ Bot 接到 OpenClaw Gateway。这条链路适合用手机 QQ 私聊机器人和 OpenClaw 对话；如果你需要长期在线运行，建议迁移到常驻平台。

前置条件：

已在 QQ 开放平台 创建机器人并拿到 AppID / AppSecret
手机 QQ 已加入该机器人的测试或沙箱范围
当前容器内 OpenClaw 已能正常调用 CNB provider

接入步骤：

最快方式：


bash /usr/local/bin/setup_openclaw_qqbot.sh "<APP_ID>:<APP_SECRET>"

如果你想手动拆开执行，也可以继续用下面这组命令：


openclaw config set agents.defaults.workspace "/workspace"
openclaw config set gateway.mode local
openclaw plugins install @sliverp/qqbot@latest
openclaw channels remove --channel qqbot --account default --delete || true
openclaw channels add --channel qqbot --account default --token "<APP_ID>:<APP_SECRET>"
nohup openclaw gateway >/workspace/.openclaw-gateway.log 2>&1 &
sleep 3
openclaw channels list
openclaw channels status --probe
tail -n 80 /workspace/.openclaw-gateway.log

成功标志：

openclaw channels status --probe 中看到 Gateway reachable
QQ Bot default 状态为 enabled, configured, running, connected
Gateway 日志中出现 Access token obtained successfully、WebSocket connected、Gateway ready

注意事项：

CNB Preview 适合验证和轻量使用，不适合作为长期稳定在线宿主
ffmpeg 未安装不会影响文字聊天，只影响语音/视频转换等扩展能力
openclaw gateway restart 适合 systemd 场景；容器内请直接运行 openclaw gateway 或配合 nohup 后台启动
如果你已经接了 QQ Bot，而且入口不是严格只给你本人使用，别把它直接挂到 main；当前默认审批只对 main 放开，更稳的做法是单独建一个 messaging profile 的低权限 agent，并收紧 tools.elevated.allowFrom / agents.list[].tools.elevated

对接小艺

当前推荐通过 @ynhcj/xiaoyi 插件把 小艺 接到 OpenClaw Gateway。结合华为开发者文档 OpenClaw 接入（更新时间 2026-02-13 09:14）和插件 README，xiaoyi 渠道当前至少需要 ak、sk、agentId 这 3 个关键字段；这个仓库新增的一键脚本会在运行时只让你输入 AK / SK，agentId 则优先从 XIAOYI_AGENT_ID 环境变量或现有 openclaw.json 中读取。

前置条件：

已在 小艺开放平台 创建 OpenClaw 智能体，并拿到对应 agentId
已拿到 小艺开放平台 的 AK / SK
当前容器内 OpenClaw 已能正常调用 CNB provider

接入步骤：

首次使用，推荐先把 agentId 预置好：


export XIAOYI_AGENT_ID="<智能体agentId>"
bash /usr/local/bin/setup_openclaw_xiaoyi.sh

脚本会在运行时提示你输入 AK / SK。如果你想非交互执行，也可以直接传参：


XIAOYI_AGENT_ID="<智能体agentId>" bash /usr/local/bin/setup_openclaw_xiaoyi.sh "<AK>:<SK>"

如果你之前已经把 channels.xiaoyi.agentId 或 channels.xiaoyi.accounts.default.agentId 写进 openclaw.json，后续直接执行下面这条就行，脚本还是只会问你 AK / SK：


bash /usr/local/bin/setup_openclaw_xiaoyi.sh

脚本会自动完成这些动作：

安装或升级 @ynhcj/xiaoyi 插件
把 agents.defaults.workspace 设为 /workspace
把 gateway.mode 设为 local
同时写入 channels.xiaoyi 的顶层字段和 accounts.default 字段，兼容两套配置结构
重启 OpenClaw Gateway 并输出最近日志

成功标志：

Gateway 日志中出现 info sent claw_bot_init message
openclaw channels status --probe 里能看到 Gateway reachable

注意事项：

agentId 是当前 小艺 接入要求，不是脚本能靠 AK / SK 现算出来的；所以第一次要么提前 export XIAOYI_AGENT_ID，要么先把它写进现有配置
如果你的环境需要显式指定 websocket 地址，先执行 export XIAOYI_WS_URL="wss://..." 再运行脚本
仓库里的脚本会同时写入扁平结构和 accounts.default 结构，主要是为了兼容文档与插件 README 当前的配置差异

终端会话说明

如果你发现预览页终端偶尔重新打印 AI CLI Status，但后台 QQ Bot 或 Gateway 还活着，通常不是容器被重置，而是浏览器终端连接断开后重新建立。当前版本默认用 tmux 承接 ttyd 后端 Shell，并通过 shell_history_persist.sh 实时落盘 bash history，因此重连后会尽量回到原来的会话。