CLI

OpenCode CLI 选项和命令。

默认情况下，在不带任何参数运行时，OpenCode CLI 会启动 TUI。

opencode

但它也支持本页文档中的各种命令，这样你就可以以编程方式与 OpenCode 交互。

opencode run "Explain how closures work in JavaScript"

tui

启动 OpenCode 终端界面（TUI）。

opencode [project]

参数

参数	简写	说明
`--continue`	`-c`	继续上一次的会话
`--session`	`-s`	要继续的会话 ID
`--prompt`		要使用的提示词
`--model`	`-m`	要使用的模型，格式为 `provider/model`
`--agent`		要使用的 Agent
`--port`		监听的端口
`--hostname`		监听的主机名

命令

OpenCode CLI 还提供了以下命令。

agent

管理 OpenCode 的 Agents。

opencode agent [command]

attach

将终端附加到已通过 serve 或 web 命令启动的 OpenCode 后端服务器。

opencode attach [url]

这样可以在远程运行的 OpenCode 后端上使用本地 TUI。例如：

# 启动用于 Web/移动端访问的后端服务
opencode web --port 4096 --hostname 0.0.0.0

# 在另一终端中，将 TUI 附加到正在运行的后端
opencode attach http://10.20.30.40:4096

参数

参数	简写	说明
`--dir`		启动 TUI 时使用的工作目录
`--session`	`-s`	要继续的会话 ID

create

创建一个带有自定义配置的新 Agent。

opencode agent create

该命令会引导你创建一个带有自定义系统提示词和工具配置的新 Agent。

list

列出所有可用的 Agents。

opencode agent list

auth

管理提供商的凭证和登录的命令。

opencode auth [command]

OpenCode 使用 Models.dev 上的提供商列表，你可以通过 opencode auth login 为任意提供商配置 API Key。这些信息会保存在 ~/.local/share/opencode/auth.json 中。

opencode auth login

OpenCode 启动时会从凭证文件中加载提供商配置；如果环境变量或项目中的 .env 文件中也定义了 Key，同样会被加载。

list

列出凭证文件中所有已认证的提供商。

opencode auth list

或使用简写：

opencode auth ls

logout

将某个提供商从凭证文件中移除，实现登出。

opencode auth logout

github

管理用于仓库自动化的 GitHub Agent。

opencode github [command]

install

在你的仓库中安装 GitHub Agent。

opencode github install

这会为你配置必要的 GitHub Actions 工作流，并引导你完成相关配置。了解更多。

run

运行 GitHub Agent。通常在 GitHub Actions 中使用。

opencode github run

参数

参数	说明
`--event`	要为其运行 Agent 的 GitHub 模拟事件
`--token`	GitHub Personal Access Token

mcp

管理 Model Context Protocol（MCP）服务器。

opencode mcp [command]

add

向配置中添加一个 MCP 服务器。

opencode mcp add

该命令会引导你添加本地或远程的 MCP 服务器。

list

列出所有已配置的 MCP 服务器及其连接状态。

opencode mcp list

或使用简写：

opencode mcp ls

auth

为支持 OAuth 的 MCP 服务器进行认证。

opencode mcp auth [name]

如果不提供服务器名称，你会被提示从支持 OAuth 的服务器中进行选择。

你也可以列出支持 OAuth 的服务器及其认证状态：

opencode mcp auth list

或使用简写：

opencode mcp auth ls

logout

移除某个 MCP 服务器的 OAuth 凭证。

opencode mcp logout [name]

debug

调试 MCP 服务器的 OAuth 连接问题。

opencode mcp debug <name>

models

列出所有已配置提供商中可用的模型。

opencode models [provider]

该命令会以 provider/model 格式展示所有可用模型。

这对于在配置文件中确定要使用的具体模型名称非常有用。

你也可以传入一个提供商 ID 以仅查看该提供商的模型：

opencode models anthropic

参数

参数	说明
`--refresh`	从 models.dev 刷新模型缓存
`--verbose`	使用更详细的输出（包含价格等元数据）

使用 --refresh 参数可以刷新模型列表缓存，这在提供商新增模型后非常有用：

opencode models --refresh

run

以非交互方式运行 opencode，直接传入一条消息。

opencode run [message..]

适合脚本、自动化，或只想快速得到一个回答而不启动完整 TUI 的场景。例如：

opencode run Explain the use of context in Go

你也可以附加到正在运行的 opencode serve 实例上，以避免每次运行都重新启动 MCP 服务器：

# 在一个终端中启动无头服务器
opencode serve

# 在另一个终端中，附加到该服务器运行命令
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

参数

参数	简写	说明
`--command`		要运行的命令，消息将作为参数传入
`--continue`	`-c`	继续上一次会话
`--session`	`-s`	要继续的会话 ID
`--share`		结束后分享当前会话
`--model`	`-m`	要使用的模型，格式为 `provider/model`
`--agent`		要使用的 Agent
`--file`	`-f`	要附加到消息的文件
`--format`		输出格式：`default`（格式化）或 `json`（原始 JSON 事件）
`--title`		会话标题（若未提供，则使用截断后的提示词）
`--attach`		附加到正在运行的 opencode 服务器（如 `http://localhost:4096`）
`--port`		本地服务器端口（默认随机端口）

serve

启动无头 OpenCode 服务器以提供 API 访问。完整 HTTP 接口见 server 文档。

opencode serve

该命令会启动一个 HTTP 服务器，在不需要 TUI 的情况下提供 opencode 功能。

参数

参数	说明
`--port`	监听端口
`--hostname`	监听主机名
`--mdns`	启用 mDNS 服务发现
`--cors`	允许的额外浏览器来源（CORS）

session

管理 OpenCode 会话。

opencode session [command]

list

列出所有 OpenCode 会话。

opencode session list

参数

参数	简写	说明
`--max-count`	`-n`	仅显示最近 N 条会话
`--format`		输出格式：`table` 或 `json`（默认 table）

stats

展示 OpenCode 会话的 Token 使用情况和费用统计。

opencode stats

参数

参数	说明
`--days`	查看最近 N 天的统计（默认：全部）
`--tools`	显示的工具数量（默认：全部）
`--models`	是否展示模型使用情况（默认隐藏；可传数字限制展示前 N 个）
`--project`	按项目过滤（默认：所有项目；空字符串表示当前项目）

export

以 JSON 格式导出会话数据。

opencode export [sessionID]

如果不指定会话 ID，会提示你从可用会话中选择。

import

从 JSON 文件或 OpenCode 分享链接导入会话数据。

opencode import <file>

既可以从本地文件，也可以从 OpenCode 分享 URL 导入：

opencode import session.json
opencode import https://opncd.ai/s/abc123

web

启动带 Web 界面的无头 OpenCode 服务器。

opencode web

该命令会启动 HTTP 服务器并打开浏览器，通过 Web 界面访问 OpenCode。

参数

参数	说明
`--port`	监听端口
`--hostname`	监听主机名
`--mdns`	启用 mDNS 服务发现
`--cors`	允许的额外浏览器来源（CORS）

acp

启动 ACP（Agent Client Protocol）服务器。

opencode acp

该命令会通过 stdin/stdout 以 nd-JSON 形式通信，启动一个 ACP 服务器。

参数

参数	说明
`--cwd`	工作目录
`--port`	监听端口
`--hostname`	监听主机名

uninstall

卸载 OpenCode 并移除所有相关文件。

opencode uninstall

参数

参数	简写	说明
`--keep-config`	`-c`	保留配置文件
`--keep-data`	`-d`	保留会话数据和快照
`--dry-run`		仅展示将要删除的内容而不实际删除
`--force`	`-f`	跳过确认提示

upgrade

将 opencode 升级到最新版本或指定版本。

opencode upgrade [target]

升级到最新版本：

opencode upgrade

升级到指定版本：

opencode upgrade v0.1.48

参数

参数	简写	说明
`--method`	`-m`	使用的安装方式；`curl`、`npm`、`pnpm`、`bun`、`brew` 等

全局参数

opencode CLI 支持以下全局参数：

参数	简写	说明
`--help`	`-h`	显示帮助信息
`--version`	`-v`	输出版本号
`--print-logs`		将日志打印到 stderr
`--log-level`		日志级别（`DEBUG`、`INFO`、`WARN`、`ERROR`）

环境变量

可以通过环境变量配置 OpenCode：

变量	类型	说明
`OPENCODE_AUTO_SHARE`	boolean	是否自动分享会话
`OPENCODE_GIT_BASH_PATH`	string	Windows 上 Git Bash 可执行文件路径
`OPENCODE_CONFIG`	string	配置文件路径
`OPENCODE_CONFIG_DIR`	string	配置目录路径
`OPENCODE_CONFIG_CONTENT`	string	内联 JSON 配置内容
`OPENCODE_DISABLE_AUTOUPDATE`	boolean	禁用自动检查更新
`OPENCODE_DISABLE_PRUNE`	boolean	禁用旧数据清理
`OPENCODE_DISABLE_TERMINAL_TITLE`	boolean	禁用自动更新终端标题
`OPENCODE_PERMISSION`	string	内联 JSON 权限配置
`OPENCODE_DISABLE_DEFAULT_PLUGINS`	boolean	禁用默认插件
`OPENCODE_DISABLE_LSP_DOWNLOAD`	boolean	禁用自动下载 LSP 服务器
`OPENCODE_ENABLE_EXPERIMENTAL_MODELS`	boolean	启用实验性模型
`OPENCODE_DISABLE_AUTOCOMPACT`	boolean	禁用自动上下文压缩
`OPENCODE_DISABLE_CLAUDE_CODE`	boolean	禁用读取 `.claude`（提示 + skills）
`OPENCODE_DISABLE_CLAUDE_CODE_PROMPT`	boolean	禁用读取 `~/.claude/CLAUDE.md`
`OPENCODE_DISABLE_CLAUDE_CODE_SKILLS`	boolean	禁用加载 `.claude/skills`
`OPENCODE_CLIENT`	string	客户端标识（默认 `cli`）
`OPENCODE_ENABLE_EXA`	boolean	启用 Exa Web 搜索工具

实验性

以下环境变量会启用仍在开发中的实验性功能，可能随时变更或移除：

变量	类型	说明
`OPENCODE_EXPERIMENTAL`	boolean	启用所有实验性功能
`OPENCODE_EXPERIMENTAL_ICON_DISCOVERY`	boolean	启用图标自动发现
`OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT`	boolean	禁用 TUI 中的“选中即复制”行为
`OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH`	number	Bash 命令输出的最大长度
`OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS`	number	Bash 命令默认超时时间（毫秒）
`OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX`	number	LLM 响应的最大输出 Token 数
`OPENCODE_EXPERIMENTAL_FILEWATCHER`	boolean	启用整目录文件监听
`OPENCODE_EXPERIMENTAL_OXFMT`	boolean	启用 oxfmt 格式化器
`OPENCODE_EXPERIMENTAL_LSP_TOOL`	boolean	启用实验性的 LSP 工具