Witty CLI 使用介绍 ​

引言 ​

Witty CLI 是 openEuler 终端场景下的 AI 助手。它提供两种使用方式：在普通 Bash 提示符下直接输入自然语言的 Shell 直输，以及运行 witty 进入的 REPL 交互式 CLI。两种方式共享同一套会话、渲染、权限与展示核心。

快速上手 ​

Shell 直输（最简方式） ​

安装完成后，直接在 Bash 终端输入自然语言即可触发 AI 助手：

检查系统内存

Witty CLI 会自动识别这是自然语言而非 shell 命令，调用 AI 助手并流式输出回答：

systemctl 怎么看 nginx 日志

以已知命令开头但包含中文疑问词的输入，也会被正确路由到 AI 助手。

REPL 模式 ​

witty

进入交互式 REPL，提示符格式为 witty [<agent>:<model>] >（末尾含空格）。可以在其中连续对话：

witty [witty-builtin-agent] > 帮我分析一下 dmesg 里的 OOM 日志
...（流式输出回答）...
witty [witty-builtin-agent] > 那怎么优化内存配置呢
...（基于上一轮上下文继续回答）...

输入 /exit 或按 Ctrl+D 退出 REPL。

单次提问 ​

witty ask "检查系统内存"

单次请求，流式输出回答后退出。

通过管道传入 ​

echo "explain this function" | witty ask

dmesg | witty ask "分析这段内核日志中的异常"

连接 Provider 并切换模型 ​

witty provider connect deepseek
Enter API key: ****（输入不可见）
connected provider deepseek

随后进入 REPL，输入 /model 打开模型选择器：

witty [witty-builtin-agent] > /model

Select model:

❯ 1) opencode/north-mini-code-free  — North Mini Code Free
  2) opencode/ling-3.0-flash-free   — Ling-3.0-flash Free
  ...
  8) deepseek/deepseek-v4-flash     — DeepSeek V4 Flash
  9) deepseek/deepseek-v4-pro       — DeepSeek V4 Pro

  ↑/↓ navigate  ↵ select  esc cancel

命令参考 ​

全局选项 ​

以下选项可用于所有子命令：

witty（无子命令）— 启动 REPL ​

witty

启动交互式 REPL，自动恢复当前目录的最近会话；若无则新建。

witty ask ​

witty ask [prompt]

发送一条消息并流式输出回答，回答结束后退出。

选项：

--new 和 --session 不能同时使用。

witty init bash ​

eval "$(witty init bash)"

输出 Bash 集成脚本到 stdout，通常配合 eval 使用。RPM 安装后已通过 /etc/profile.d/witty.sh 自动完成集成。

witty session ​

witty session list
witty session continue <id>

列出全部会话，或切换到指定会话。也可使用顶层快捷命令 witty continue <id>。

witty provider ​

Provider 管理，详见下文「Provider 管理」。

witty server ​

Server 管理，详见下文「Server 生命周期管理」。

witty doctor ​

环境诊断，详见下文「环境诊断」。

witty version ​

打印版本号、commit 和构建日期。

Shell 集成 ​

工作原理 ​

Shell 集成通过 Bash 的 DEBUG trap（配合 extdebug 选项）实现，在每条命令即将执行前拦截，由分类器判断路由：

分类遵循「Shell 优先、Agent 兜底」原则——无法明确识别为自然语言的输入默认交给 Shell 执行。

路由示例 ​

启用与禁用 ​

• 默认状态：RPM 安装后对所有用户默认启用。
• 临时禁用（当前终端会话）：export WITTY_SHELL_ENABLE=0
• 永久禁用：在 ~/.bashrc 中添加 export WITTY_SHELL_ENABLE=0
• 调试模式：export WITTY_SHELL_DEBUG=1，在 stderr 输出分类结果

强制走 Agent ​

如果分类器误将自然语言识别为 shell 命令，可使用 /ask 逃生口强制走 Agent：

/ask docker 镜像怎么删

安装前提 ​

Shell 集成仅在以下条件满足时安装：当前 shell 为 Bash、交互式会话（$- 含 i）、stdin/stdout 为 TTY。非交互式脚本、zsh / fish 等不支持的 shell 不会安装集成。

Slash 控制命令 ​

在 REPL 和 Shell 直输模式下均可使用以下 slash 命令：

/agent — 切换 Agent ​

不带参数时，如果当前是 TTY 终端，会显示交互式 agent 选择器（列出所有非隐藏、非 subagent 型 agent）。带参数时直接切换：

/agent build

切换后会持久化到用户配置文件：

[agent] set to "build" (saved to ~/.config/witty/config.toml)

/model — 切换模型 ​

模型格式必须为 provider/model：

/model openai/gpt-4

不带参数时显示交互式模型选择器，仅列出已连接 provider 的模型。如果选中的模型支持变体（variant），会进一步显示变体选择器。选择完成后输出确认并持久化到配置文件：

[model] set to "deepseek/deepseek-v4-flash" (variant: max, saved to ~/.config/witty/config.toml)

参数校验规则 ​

配置 ​

配置文件 ​

Witty CLI 使用 TOML 格式配置文件，搜索顺序（后者覆盖前者）：

1. /etc/witty/config.toml（系统级配置）
2. ~/.config/witty/config.toml（用户级配置）

也可通过 --config <path> 或环境变量 WITTY_CONFIG 指定。

完整配置项 ​

# 顶层配置
default_agent = "witty-builtin-agent"  # 默认 agent
default_model = ""                     # 默认模型（格式 provider/model）
default_variant = ""                   # 模型变体（如推理级别）
debug = false                          # 调试日志
theme = "auto"                         # 主题（auto）
no_color = false                       # 禁用彩色输出
stream_mode = 1                        # 流式输出模式（1=分段渲染，2=逐字回显）

# Server 生命周期管理
[server]
auto_start = true              # 自动启动 opencode serve
port = 0                       # 0 = 自动选择端口，正整数 = 固定端口
hostname = "127.0.0.1"         # 绑定地址
startup_timeout_seconds = 10   # 等待 server 启动的最大时间（秒）
idle_timeout_minutes = 30      # 闲置超时自动停止（0 = 禁用）

# REPL 配置
[repl]
auto_resume = true             # 自动恢复当前目录最近会话

# Shell 集成配置
[shell]
enabled = true                 # 启用 Shell 集成
debug = false                  # Shell 集成调试模式

# 诊断配置
[doctor]
timeout_seconds = 5            # 诊断超时时间（秒）

# 显示配置
[display]
show_reasoning = "show"        # 推理过程展示：show / minimal / hide
tool_mode = "compact"          # 工具调用展示：compact / verbose
group_context_tools = true     # 合并连续的读取类工具调用展示
step_style = "line"            # 步骤展示风格：line / minimal / none

配置覆盖类环境变量 ​

环境变量优先于配置文件，CLI 选项优先于环境变量。

Provider 管理 ​

列出 Provider ​

witty provider list

列出所有支持 API Key 认证的 provider，标注连接状态：

STATUS     ID        NAME          DEFAULT_MODEL
-          openai    OpenAI        gpt-4
connected  deepseek  DeepSeek      deepseek-chat

仅列出已连接的 provider：

witty provider list --connected

连接 Provider ​

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

<provider> 可以是 provider 的 ID 或名称（支持不区分大小写匹配）。

API Key 的传入方式（按优先级）：

1. --key 参数
2. 交互式终端提示（如果 stdin 是 TTY，会提示 Enter API key:，输入不可见）
3. stdin 管道读取
4. 环境变量（如 OPENAI_API_KEY、DEEPSEEK_API_KEY）

连接成功后输出 connected provider deepseek。如果 provider 仍不可用，witty 会自动重启 server 以重新加载凭据。

Server 生命周期管理 ​

Witty CLI 自动管理 opencode serve 进程的完整生命周期，通常无需用户干预。

自动启动 ​

当 server.auto_start = true（默认）时，witty 首次使用时自动启动 opencode serve 子进程。启动后：

• server 作为守护进程运行，witty 退出后继续运行
• 状态持久化到 ~/.local/state/witty/server-state.json（权限 0600）
• 下次启动 witty 时通过状态文件无缝复用

查看状态 ​

witty server status

Running:    yes
Port:       4096
PID:        12345
Managed:    no
StartedAt:  2026-08-19T10:30:00+08:00

• Running：server 是否正在运行——判断 server 状态以此字段为准
• Managed：表示「是否由当前进程启动」；由于 witty server status 是只读命令，该命令下 Managed 恒为 no，属预期行为，请以 Running 为准

停止 / 重启 ​

witty server stop
witty server restart

witty server restart 在安装或修改 agent / skill / MCP 配置文件后使用，让 server 重新加载配置：

sudo dnf install witty-diagnosis-agent
witty server restart

关闭自动启动 ​

[server]
auto_start = false

关闭后需手动启动 opencode serve，witty 将探测该地址寻找已有 server。若需连接其他地址的 server，请使用 --server-url CLI 标志。

闲置超时 ​

默认 30 分钟无活动后自动停止 server（server.idle_timeout_minutes = 30）。设为 0 禁用此功能。

多用户安全隔离 ​

同一台服务器上，不同用户的 server 实例互相隔离：

• 每个用户有独立的随机密码（HTTP Basic Auth）
• 状态文件权限 0600，其他用户无法读取
• 密码仅通过环境变量传递给子进程，不出现在命令行参数中

环境诊断 ​

witty doctor

检查以下项目，每项状态为 OK、WARN、FAIL 或 SKIP：

witty doctor 不会启动 server（无副作用），适合用于排查问题。

常见问题 ​

Shell 直输不生效 ​

1. 运行 witty doctor，检查 shell integration 项
2. 如果显示 not loaded，手动执行 eval "$(witty init bash)"
3. 检查是否设置了 WITTY_SHELL_ENABLE=0

自然语言被当成 shell 命令执行 ​

分类器采用「Shell 优先」策略，部分边界场景可能误判。可使用 /ask 强制走 Agent：

/ask docker 镜像怎么删

提示 server 不可达 ​

• 检查 opencode 是否已安装：which opencode
• 运行 witty doctor 查看详细诊断
• 尝试 witty server restart
• 若关闭了自动启动：报错提示需手动启动 opencode serve --port 4096，或通过 --server-url 指定地址

Provider 连接后仍不可用 ​

witty server restart
witty provider list --connected  # 确认连接状态

会话上下文丢失 ​

Witty CLI 按当前目录管理会话：

• 同一目录下执行 witty 或 Shell 直输会自动恢复最近会话
• 切换目录后会话不共享
• 使用 /new 或 witty ask --new 可强制新建会话
• 使用 /session list 查看可用会话，/session continue <id> 切换

如何完全禁用 Witty CLI ​

export WITTY_SHELL_ENABLE=0   # 禁用 Shell 集成
witty server stop             # 停止后台 server
sudo dnf remove witty         # 卸载

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

REPL 中如何取消当前请求 ​

按 Ctrl+C 可取消正在进行的 AI 请求（输出 [cancelled]），不会退出 REPL。