OpenCode 使用说明 ​

本节介绍在终端中直接使用 OpenCode 的常用方式。OpenCode 是驱动 Witty CLI 的智能体框架，提供了完整的 CLI 与无头 Server 能力。

一般用户请使用 Witty CLI 的 Shell 直输或 REPL（见使用智能助手 CLI），无需直接调用 OpenCode 命令。

常用命令 ​

启动交互式 TUI ​

opencode

TUI 默认加载 /etc/opencode/opencode.json 中的 agent / skill / mcp 配置。在 TUI 中可通过 /agent 等命令切换 agent；具体可用的 / 命令以 OpenCode 官方文档为准。

无头 Server ​

opencode serve --port 4096

opencode serve 运行后提供以下端点（Witty 即依赖这些端点）：

• GET /global/health — 健康检查
• GET /session、POST /session — 会话管理
• POST /session/{id}/message — 发送消息
• GET /event?directory=<cwd> — SSE 事件流（所有会话共享，需按 sessionID 过滤）
• GET /agent、GET /provider、GET /mcp — 元信息
• GET /doc — OpenAPI 文档（唯一事实来源）

查看与使用 Agent ​

opencode agent list

输出示例（节选，openEuler 24.03 实测）：

build (primary)
explore (subagent)
general (subagent)
plan (primary)
summary (primary)
title (primary)
baize (subagent)
witty-builtin-agent (primary)

其中 witty-builtin-agent 为 Witty 内置的默认 primary agent；build / plan 等为 OpenCode 内置 agent。

Agent 配置 ​

OpenCode 的 agent 通过 /etc/opencode/opencode.json（或用户级 ~/.config/opencode/opencode.json、项目级 opencode.json）配置。典型字段：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "witty-builtin-agent": {
      "description": "Witty Assistant",
      "mode": "primary",
      "prompt": "{file:/usr/share/witty/opencode/agents/witty-builtin-agent/witty-builtin-agent.md}",
      "color": "#5F87FF",
      "permission": {
        "*": "ask",
        "read": { "*": "allow" },
        "bash": "allow"
      }
    }
  }
}

• mode：primary（默认主 agent）、subagent（子 agent）、all（主 agent + 子 agent）；
• prompt：角色提示词，支持 {file:...} 引用本地文件；
• permission：工具 / 文件 / shell 授权策略，行为 allow / ask / deny。

详细字段语义以 opencode.ai/docs 为准。修改 mode、permission 等字段前务必查阅官方文档，避免凭猜测修改外部配置。

Skill 使用 ​

Skill 通过 skills.paths 指定搜索目录。Witty 托管时固定为 /usr/share/witty/opencode/skills。具体加载方式与命令以 OpenCode 官方文档为准。

MCP 使用 ​

MCP 通过 mcp 字段配置，支持 local（本地命令）与 remote（SSE/HTTP）两种类型。Witty 内置的 openeuler_portal 即通过本地 npx -y openeuler-portal-mcp 提供 openEuler 官网数据查询。

opencode mcp

权限交互 ​

当 Agent 请求调用工具、读取文件或执行 shell 命令时，OpenCode 会根据 permission 策略发起 permission.asked 事件；在 TUI 中会弹出确认请求。Witty 在终端中接管这一交互，通过 witty 的授权提示完成回复。

相关文档 ​

• OpenCode 部署
• OpenCode Agent 介绍