Witty CLI 安装指南 ​

本手册适用于 Witty CLI 3.x。当前最新版本已发布至 openEuler 24.03 LTS SP3 与 SP4，RPM 包名为 witty。

环境要求 ​

• 操作系统：openEuler 24.03 LTS SP3 或更高版本（x86_64 / aarch64）
• 内存：建议至少 8GB RAM
• 存储：建议至少 20GB 可用磁盘空间
• 网络：稳定的互联网连接（用于安装与拉取弱依赖；如需离线部署请提前准备）
• 大模型服务：
  • 线上：需具备支持工具调用的线上大模型 API 访问权限，例如百炼、DeepSeek Chat、智谱、MiniMax、硅基流动等
  • 本地：支持部署在本地的 LLM 服务，如 llama-server、ollama、vLLM、LM Studio 等，需使用支持工具调用的大模型，例如 Qwen3、DeepSeek 3.2、GLM-4.7、MiniMax M2.1、Kimi K2 等
• 系统权限：需具备 sudo 权限，以便安装必要的软件包与依赖项

依赖仓库与弱依赖说明 ​

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

因此，除了默认已启用的 OS / update / everything 仓库外，还需要配置 EPOL（main） 与 EPOL update 仓库，才能解析完整依赖。

配置 repo 源 ​

openEuler 24.03 LTS SP3 ​

在 /etc/yum.repos.d/ 下创建仓库配置文件（例如 witty.repo），加入以下内容：

[EPOL]
name=EPOL
baseurl=https://repo.openeuler.org/openEuler-24.03-LTS-SP3/EPOL/main/$basearch/
metadata_expire=1h
enabled=1
gpgcheck=1
gpgkey=http://repo.openeuler.org/openEuler-24.03-LTS-SP3/OS/$basearch/RPM-GPG-KEY-openEuler

[update-EPOL]
name=update-EPOL
baseurl=https://repo.openeuler.org/openEuler-24.03-LTS-SP3/EPOL/update/main/$basearch/
metadata_expire=1h
enabled=1
gpgcheck=1
gpgkey=http://repo.openeuler.org/openEuler-24.03-LTS-SP3/OS/$basearch/RPM-GPG-KEY-openEuler

openEuler 24.03 LTS SP4 ​

同理，SP4 将上述路径中的 openEuler-24.03-LTS-SP3 替换为 openEuler-24.03-LTS-SP4：

[EPOL]
name=EPOL
baseurl=https://repo.openeuler.org/openEuler-24.03-LTS-SP4/EPOL/main/$basearch/
metadata_expire=1h
enabled=1
gpgcheck=1
gpgkey=http://repo.openeuler.org/openEuler-24.03-LTS-SP4/OS/$basearch/RPM-GPG-KEY-openEuler

[update-EPOL]
name=update-EPOL
baseurl=https://repo.openeuler.org/openEuler-24.03-LTS-SP4/EPOL/update/main/$basearch/
metadata_expire=1h
enabled=1
gpgcheck=1
gpgkey=http://repo.openeuler.org/openEuler-24.03-LTS-SP4/OS/$basearch/RPM-GPG-KEY-openEuler

若您使用了国内镜像源（如华为云、清华镜像），请以实际镜像路径为准。为正确解析完整依赖，请确保以下仓库均已启用：OS、update、everything、EPOL、EPOL/update。

说明：opencode 来自 update 仓库、nodejs 来自 everything 仓库、euler-copilot-rag/witty-lite-rag/witty-log-detection 来自 EPOL 仓库；witty 主包在 SP3 位于 update、在 SP4 位于 EPOL/update。

安装 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：

witty

在普通 Bash 终端直接输入自然语言即可触发 AI 助手（Shell 集成随 RPM 默认启用）：

检查系统内存

配置大模型与模型切换 ​

连接模型服务商：

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

进入 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 集成，零残留。

附录 ​

其他环境使用 Witty CLI ​

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

内网大模型 API 服务 ​

若内网大模型服务需通过 HTTPS 访问，请确保证书已在系统中正确配置，以避免证书验证失败。如无法配置有效证书，可在环境变量中添加以下内容以跳过证书验证：

export OI_SKIP_SSL_VERIFY=true

本地部署大模型服务 ​

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

FAQ ​

Q1：安装后 Shell 直输不生效怎么办？ ​

A1：运行 witty doctor 检查 shell integration；若未加载，执行 eval "$(witty init bash)"；并确认未设置 WITTY_SHELL_ENABLE=0。

Q2：提示找不到 opencode 或 server 不可达？ ​

A2：opencode 是 witty 的弱依赖，确认已安装：which opencode。若未安装，执行 sudo dnf install opencode nodejs；随后运行 witty doctor 诊断，或执行 witty server restart。

Q3：EPOL / EPOL update 源无法访问怎么办？ ​

A3：确认已正确配置 EPOL 与 EPOL update 仓库，并检查网络与镜像源是否可用。可改用国内镜像源（如华为云镜像的 mirrors.huaweicloud.com/openeuler/... 路径）。