OpenCode Usage
This section describes common ways to use OpenCode directly in the terminal. OpenCode is the agent framework that powers Witty CLI and provides a complete CLI and headless server.
Regular users should use Witty CLI Shell direct input or the REPL, see Using Witty CLI; calling OpenCode commands directly is not required.
Common Commands
| Command | Purpose |
|---|---|
opencode | Start the interactive TUI in the current directory |
opencode serve | Start the headless opencode server (HTTP + SSE) |
opencode run [message..] | Run opencode with a single message, non-interactive |
opencode agent list | List all available agents with primary / subagent markers |
opencode agent create | Create a new agent |
opencode providers | Manage AI providers and credentials, alias opencode auth |
opencode models [provider] | List available models |
opencode mcp | Manage MCP servers |
opencode session | Session management |
opencode plugin <module> | Install a plugin and update the configuration |
opencode upgrade | Upgrade to the latest version |
Starting the Interactive TUI
opencodeThe TUI loads the agent / skill / mcp configuration from /etc/opencode/opencode.json by default. Switch agents in the TUI with commands such as /agent; see the OpenCode official documentation for the available / commands.
Headless Server
opencode serve --port 4096opencode serve exposes the following endpoints, which Witty depends on:
GET /global/health— health checkGET /session,POST /session— session managementPOST /session/{id}/message— send a messageGET /event?directory=<cwd>— SSE event stream, shared by all sessions and filtered by sessionIDGET /agent,GET /provider,GET /mcp— metadataGET /doc— OpenAPI documentation
Viewing and Using Agents
opencode agent listExample output, excerpted from a test on openEuler 24.03:
build (primary)
explore (subagent)
general (subagent)
plan (primary)
summary (primary)
title (primary)
baize (subagent)
witty-builtin-agent (primary)witty-builtin-agent is the default primary agent of Witty; build and plan are OpenCode built-in agents.
Agent Configuration
OpenCode agents are configured through /etc/opencode/opencode.json, or the user-level ~/.config/opencode/opencode.json and the project-level opencode.json. Typical fields:
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"witty-builtin-agent": {
"description": "Knowledge Q&A, command lookup, fault diagnosis, solution planning, and visual reports",
"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:primaryfor the main agent,subagentfor a subagent,allfor both;prompt: the role prompt, supporting{file:...}references to local files;permission: authorization policies for tools, files, and shell, with the behaviorsallow/ask/deny.
Field semantics follow opencode.ai/docs.
Using Skills
Skills are loaded from the directories specified by skills.paths, which Witty manages as /usr/share/witty/opencode/skills. See the OpenCode official documentation for loading details and commands.
Using MCP
MCP is configured through the mcp field and supports the local type for local commands and the remote type for SSE/HTTP. The Witty built-in openeuler_portal uses the local npx -y openeuler-portal-mcp to query openEuler official site data.
opencode mcpPermission Interaction
When an agent requests to call a tool, read a file, or run a shell command, OpenCode emits a permission.asked event according to the permission policy; the TUI shows a confirmation request. Witty handles this interaction in the terminal through its own authorization prompts.
