407 lines
22 KiB
Markdown
407 lines
22 KiB
Markdown
---
|
||
title: "README.md · main · qjhnia/MyOpenClaw"
|
||
source: "https://cnb.cool/qjhnia/MyOpenClaw/-/blob/main/README.md"
|
||
author:
|
||
- "[[Cloud Native Build]]"
|
||
published:
|
||
created: 2026-03-17
|
||
description: "基于 Docker 生态,对环境、缓存、插件进行抽象,通过声明式的语法,帮助开发者以更酷的方式构建软件。"
|
||
tags:
|
||
- "clippings"
|
||
---
|
||

|
||
|
||
0
|
||
|
||
main
|
||
|
||
[MyOpenClaw](https://cnb.cool/qjhnia/MyOpenClaw/-/tree/main) / [README.md](https://cnb.cool/qjhnia/MyOpenClaw/-/blob/main/README.md)
|
||
|
||
## 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` :项目说明
|
||
|
||
## 启动流程
|
||
|
||
1. `start.sh` 启动内部 `ttyd` 服务
|
||
2. 默认通过 `tmux new-session -A` 挂起持久终端会话,浏览器重连时尽量回到同一个 Shell
|
||
3. `web_terminal_gate.py` 对外提供登录页、会话校验和请求转发
|
||
4. 浏览器访问终端地址时,先进入登录页,验证通过后再进入终端
|
||
5. `ttyd` 就绪后,后台异步执行 `OpenClaw / Codex CLI` 安装和 `OpenClaw` 配置写入,不阻塞预览首屏
|
||
6. 用户进入 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` 。因此使用方式分成两档:
|
||
|
||
1. 一次性本地提问:直接使用 `agent --local` ,适合快速验证模型链路。
|
||
2. 持续交互或外部渠道:先启动 `gateway` ,再接 `tui` 、 `qqbot` 等入口。
|
||
|
||
示例:
|
||
|
||
```bash
|
||
hash -r
|
||
openclaw agents list
|
||
openclaw agent --agent main --local --message "用一句话告诉我当前 provider 和 primary model 是什么"
|
||
```
|
||
|
||
如果你要进入交互式 `TUI` :
|
||
|
||
```bash
|
||
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.*` 后把工具调用链配拧巴。
|
||
|
||
快速验证:
|
||
|
||
```bash
|
||
openclaw --version
|
||
openclaw agent --agent main --local --message "执行 ls,并把 stdout 原样返回,不要只给命令"
|
||
```
|
||
|
||
如果结果还是只回命令文本,先重新写一遍配置:
|
||
|
||
```bash
|
||
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` ,适合页面浏览、快照、截图、点击和输入这类操作。
|
||
|
||
最小流程:
|
||
|
||
```bash
|
||
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` :处理需要登录的网站时的安全引导,避免把凭证喂给模型
|
||
|
||
验证方式:
|
||
|
||
```bash
|
||
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
|
||
bash /usr/local/bin/setup_openclaw_qqbot.sh "<APP_ID>:<APP_SECRET>"
|
||
```
|
||
|
||
如果你想手动拆开执行,也可以继续用下面这组命令:
|
||
|
||
```bash
|
||
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` 预置好:
|
||
|
||
```bash
|
||
export XIAOYI_AGENT_ID="<智能体agentId>"
|
||
bash /usr/local/bin/setup_openclaw_xiaoyi.sh
|
||
```
|
||
|
||
脚本会在运行时提示你输入 `AK / SK` 。如果你想非交互执行,也可以直接传参:
|
||
|
||
```bash
|
||
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
|
||
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` ,因此重连后会尽量回到原来的会话。
|
||
|
||
## 安全说明
|
||
|
||
- 不要长期使用默认密码 `OpenClaw@2026`
|
||
- 多人或生产场景建议设置 `WEB_TERMINAL_SESSION_SECRET`
|
||
- 登录页路径已避开 `CNB` 自带的 `/login` 路由
|
||
- 预览环境里的 `CNB_TOKEN` 只在对应运行时里有效,离开该容器后不能指望它继续可用
|
||
|
||
## 编码说明
|
||
|
||
- 本仓库历史中有部分中文文档出现过编码损坏
|
||
- 当前 `README` 已按 `UTF-8` 重新整理
|
||
- 如果编辑器显示异常,请确认文件编码为 `UTF-8`
|
||
|
||
## CNB 保活策略
|
||
|
||
- `.cnb.yml` 当前将 `keepAliveTimeout` 设置为 `43200000` 毫秒,也就是约 `12` 小时
|
||
- 浏览器侧保活心跳当前设置为每 `60000` 毫秒请求一次 `/healthz`
|
||
- 这只能显著降低空闲回收概率,不能绝对保证永不终止
|
||
- `keepAliveTimeout` 主要影响离线后的回收时机;平台级运行时长限制和节点差异请以 `CNB` 官方文档为准 |