Files
Obsidian/MyArticles/README.md · qjhniaMyOpenClaw.md
coco 8b94d76799 a
2026-07-21 13:57:15 +08:00

407 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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"
---
![logo](https://cnb.cool/images/favicon.png)
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` 官方文档为准