Witty CLI 安装指南 ​

Witty CLI 以 RPM 包 witty 的形式提供。在 openEuler 24.03 LTS SP3 或更高版本的系统上，按下方说明配置好 update-EPOL 仓库后，即可直接通过 DNF 安装使用。

环境要求 ​

• 操作系统：openEuler 24.03 LTS SP3 或更高版本（x86_64 / aarch64）
• 内存：建议至少 8GB RAM
• 存储：建议至少 20GB 可用磁盘空间
• 网络：稳定的互联网连接（用于安装与拉取弱依赖；如需离线部署请提前准备）
• 大模型服务：
  • 线上：需具备支持工具调用（Tool Calls / Function Calling）的大模型 API 访问权限
  • 本地：支持 llama-server、ollama、vLLM、LM Studio 等本地 LLM 服务（OpenAI 兼容接口），所用模型同样需支持工具调用
  • 可连接的 provider 可通过 witty provider list 查看，具体可用模型以所选 provider 当前提供的模型列表为准（REPL 中执行 /model 查看）
• 系统权限：需具备 sudo 权限，以便安装必要的软件包与依赖项

依赖仓库说明 ​

witty 的完整能力依赖若干由 update / everything / EPOL / EPOL update 仓库提供的软件包。其中部分为 弱依赖（Recommends），默认会随 witty 一起安装。以下为在 openEuler 24.03 LTS 上实际解析到的包来源（已排除测试仓库）：

配置 update-EPOL 仓库 ​

EPOL（main） 已包含在系统默认的仓库配置（/etc/yum.repos.d/openEuler.repo）中，通常无需额外配置。可用以下命令确认其已启用：

dnf repolist | grep -i epol

update-EPOL 需要单独添加。下面的脚本会自动读取当前系统版本并生成对应的仓库配置，无需手动指定版本号，适用于 SP3、SP4 及后续版本：

VER=$(sed -nE 's/^VERSION="([0-9.]+) \(([^)]+)\)"/\1-\2/p' /etc/os-release)   # 例如 24.03-LTS-SP4

sudo tee /etc/yum.repos.d/update-EPOL.repo >/dev/null <<EOF
[update-EPOL]
name=update-EPOL
baseurl=https://repo.openeuler.org/openEuler-${VER}/EPOL/update/main/\$basearch/
metadata_expire=1h
enabled=1
gpgcheck=1
gpgkey=http://repo.openeuler.org/openEuler-${VER}/OS/\$basearch/RPM-GPG-KEY-openEuler
EOF

sudo dnf makecache

若使用国内镜像源（如华为云、清华镜像），请将上述 repo.openeuler.org 替换为对应镜像地址，并确认 OS / update / everything 等基础仓库可用。

安装 Witty CLI ​

开始使用前，建议先更新软件包缓存与系统软件包：

sudo dnf clean all
sudo dnf makecache
sudo dnf update -y

安装 Witty CLI：

sudo dnf install witty

安装后 witty 会一并安装以下组件：

• witty（CLI 主二进制）与 wittyd（守护进程），以及 systemd 服务 wittyd.service
• witty-builtin-agent：内置智能体、5 个核心 Skill 与 openEuler Portal MCP 配置
• witty-agent-loader：托管配置 loader，负责在 /etc/opencode/opencode.json 中聚合生成 opencode 配置

验证安装 ​

witty version

输出示例：

version: 3.1.5
commit: c859a1e
date: 2026-08-19T08:47:19Z

运行环境诊断，检查配置、server、Shell 集成与终端环境：

witty doctor

启动交互式 CLI，或在普通 Bash 终端直接输入自然语言（Shell 集成随 RPM 默认启用）：

witty

检查系统内存

配置大模型与模型切换 ​

连接模型服务商：

witty provider connect <provider> --key <api-key>

可用 provider 列表通过 witty provider list 查看。进入 REPL 后切换模型：

witty
/model

详细说明参见「使用说明」中的 Provider 管理与模型切换章节。

配置参数 ​

若需调整配置，请编辑 /etc/witty/config.toml（系统级）或 ~/.config/witty/config.toml（用户级）。完整配置项参见「使用说明」配置章节。

修改 agent / skill / MCP 相关配置后，使 server 重新加载配置：

witty server restart

卸载 ​

sudo dnf remove witty

卸载后自动移除 /etc/profile.d/witty.sh 与 Shell 集成，零残留。

常见问题和故障排查 ​

安装后 Shell 直输不生效 ​

运行 witty doctor 检查 shell integration 项；若显示未加载，手动启用：

eval "$(witty init bash)"

同时确认未设置 WITTY_SHELL_ENABLE=0。

提示找不到 opencode 或 server 不可达 ​

opencode 是 witty 的弱依赖，先确认是否已安装：

which opencode

若未安装，执行 sudo dnf install opencode nodejs；随后运行 witty doctor 查看诊断，或执行 witty server restart。

依赖解析失败 / update-EPOL 不可用 ​

确认 update-EPOL 已按上文配置，并执行 sudo dnf makecache 刷新缓存；若使用内网或国内镜像，请检查镜像地址与网络连通性。

安装或更新 agent / skill / MCP 后配置未生效 ​

执行以下命令让 server 重新加载配置：

witty server restart

附录 ​

其他环境使用 Witty CLI ​

若需在非 openEuler 或非官方仓库环境手动安装，可通过源码构建或使用 openEuler 构建系统产出的 RPM 包。源码位于 https://atomgit.com/openeuler/euler-copilot-shell/tree/feat/witty-cli，构建与打包参见仓库 README 与 packaging/。

内网大模型 API 服务 ​

若内网大模型服务通过 HTTPS 提供，请确保其证书可被系统正确信任（例如导入企业内网 CA 证书），避免因证书校验失败导致调用异常。

本地部署大模型服务 ​

若无可用大模型服务，可在本地部署一个支持工具调用能力的大模型服务。若本地设备无 GPU，建议使用激活参数较少的 MoE 模型；本地部署需要较大计算资源，建议至少 32GB 内存和多核 CPU。