Witty CLI Installation Guide ​

This guide covers the full process of installation, configuration, startup, core feature usage, and troubleshooting. Follow the steps below, or watch the video for a quick overview.

Witty CLI is provided as the RPM package witty. On openEuler 24.03 LTS SP3 or later, configure the update-EPOL repository as described below, then install it directly with DNF.

Environment Requirements ​

• Operating System: openEuler 24.03 LTS SP3 or later (x86_64 / aarch64)
• Memory: At least 8GB RAM
• Storage: At least 20GB free disk space
• Network: Stable internet connection, used to install packages and pull weak dependencies; for offline deployment, prepare the required resources in advance
• LLM Service:
  • Online: Requires access to an LLM API that supports tool calls (Tool Calls / Function Calling)
  • Local: Supports local LLM services with an OpenAI-compatible interface, such as llama-server, ollama, vLLM, and LM Studio; the model in use must also support tool calls
  • Available providers can be listed with witty provider list; the models available depend on the current model list of the selected provider, see /model in the REPL
• System Permissions: sudo privileges are required to install the required packages and dependencies

Dependency Repositories ​

The full capabilities of witty depend on packages provided by the update / everything / EPOL / EPOL update repositories. Some of them are weak dependencies (Recommends) and are installed together with witty by default. The following package sources were resolved on openEuler 24.03 LTS, excluding test repositories:

Configuring the update-EPOL Repository ​

EPOL (main) is already included in the default repository configuration (/etc/yum.repos.d/openEuler.repo) and usually requires no extra configuration. Confirm that it is enabled:

dnf repolist | grep -i epol

update-EPOL must be added separately. The script below reads the current system version and generates the corresponding repository configuration, so no version number needs to be specified manually. It applies to SP3, SP4, and later versions:

VER=$(sed -nE 's/^VERSION="([0-9.]+) \(([^)]+)\)"/\1-\2/p' /etc/os-release)   # for example 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

If you use a regional mirror, such as Huawei Cloud or Tsinghua mirror, replace repo.openeuler.org above with the mirror address, and confirm that the OS / update / everything repositories are available.

Installing Witty CLI ​

Update the package cache and system packages first:

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

Install Witty CLI:

sudo dnf install witty

The following components are installed together with witty:

• witty (main CLI binary), wittyd (daemon), and the systemd service wittyd.service
• witty-builtin-agent: built-in agent, 5 core Skills, and the openEuler Portal MCP configuration
• witty-agent-loader: managed configuration loader that aggregates the opencode configuration in /etc/opencode/opencode.json

Verifying the Installation ​

witty version

Example output:

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

Run environment diagnostics to check the configuration, server, Shell integration, and terminal environment:

witty doctor

Start the interactive CLI, or type natural language directly in a regular Bash terminal. Shell integration is enabled by default with the RPM:

witty

check system memory

Configuring the LLM and Switching Models ​

Connect a model provider:

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

List available providers with witty provider list. Switch models in the REPL:

witty
/model

See the Provider management and model switching sections in the usage guide for details.

Configuration Parameters ​

To adjust the configuration, edit /etc/witty/config.toml (system level) or ~/.config/witty/config.toml (user level). See the configuration section of the usage guide for all available items.

Reload the configuration after changing agent / skill / MCP settings:

witty server restart

Uninstalling ​

sudo dnf remove witty

Uninstallation removes /etc/profile.d/witty.sh and the Shell integration, leaving no residual files.

FAQ and Troubleshooting ​

Shell direct input does not work after installation ​

Run witty doctor and check the shell integration item. If it reports not loaded, enable it manually:

eval "$(witty init bash)"

Also confirm that WITTY_SHELL_ENABLE=0 is not set.

opencode not found or server unreachable ​

opencode is a weak dependency of witty. Check whether it is installed:

which opencode

If it is missing, run sudo dnf install opencode nodejs, then witty doctor for diagnostics, or witty server restart.

Dependency resolution failure / update-EPOL unavailable ​

Confirm that update-EPOL is configured as described above, then run sudo dnf makecache to refresh the cache. If you use an intranet or regional mirror, check the mirror address and network connectivity.

Configuration not effective after installing or updating agent / skill / MCP ​

Reload the configuration:

witty server restart

Appendix ​

Using Witty CLI in other environments ​

To install manually on systems other than openEuler or outside the official repositories, build from source or use the RPM package produced by the openEuler build system. The source is at https://atomgit.com/openeuler/euler-copilot-shell/tree/feat/witty-cli; see the repository README and packaging/ for build and packaging instructions.

Intranet LLM API service ​

If the intranet LLM service is provided over HTTPS, make sure its certificate is trusted by the system, for example by importing the enterprise intranet CA certificate, so that certificate verification does not cause call failures.

Local LLM service ​

If no LLM service is available, deploy a local LLM service that supports tool calls. If the local device has no GPU, use a MoE model with fewer activated parameters. Local deployment requires substantial computing resources; at least 32GB of memory and a multi-core CPU are recommended.