CLI

OpenCode CLI 选项和命令。

OpenCode CLI 默认在不带任何参数运行时启动 TUI。

bash
opencode

但它也接受本页记录的命令。这允许你以编程方式与 OpenCode 交互。

bash
opencode run "解释 JavaScript 中闭包是如何工作的"

## tui#

启动 OpenCode 终端用户界面。

bash
opencode [project]

标志

标志	简写	描述
`--continue`	`-c`	继续上一个会话
`--session`	`-s`	要继续的会话 ID
`--prompt`		要使用的提示
`--model`	`-m`	要使用的模型，格式为 provider/model
`--agent`		要使用的代理
`--port`		监听端口
`--hostname`		监听主机名

# 命令#

OpenCode CLI 还有以下命令。

## agent#

管理 OpenCode 的代理。

bash
opencode agent [command]

create

使用自定义配置创建新代理。

bash
opencode agent create

此命令将指导你使用自定义系统提示和工具配置创建新代理。

list

列出所有可用代理。

bash
opencode agent list

## attach#

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

bash
opencode attach [url]

这允许将 TUI 与远程 OpenCode 后端一起使用。例如：

bash
1# 为 web/移动端访问启动后端服务器
2opencode web --port 4096 --hostname 0.0.0.0
3
4# 在另一个终端中，将 TUI 附加到运行的后端
5opencode attach http://10.20.30.40:4096

标志

标志	简写	描述
`--dir`		启动 TUI 的工作目录
`--session`	`-s`	要继续的会话 ID

## auth#

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

bash
opencode auth [command]

OpenCode 由 Models.dev↗ 的提供商列表驱动，所以你可以使用 opencode auth login 为任何你想使用的提供商配置 API 密钥。这存储在 ~/.local/share/opencode/auth.json。

bash
opencode auth login

当 OpenCode 启动时，它会从凭据文件加载提供商。以及环境变量中定义的任何密钥或项目中的 .env 文件。

list

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

bash
opencode auth list

或简短版本。

bash
opencode auth ls

logout

通过从凭据文件中清除提供商来注销。

bash
opencode auth logout

## github#

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

bash
opencode github [command]

install

在你的仓库中安装 GitHub 代理。

bash
opencode github install

这会设置必要的 GitHub Actions 工作流并指导你完成配置过程。了解更多。

run

运行 GitHub 代理。这通常在 GitHub Actions 中使用。

bash
opencode github run

标志

标志	描述
`--event`	要为代理运行的 GitHub 模拟事件
`--token`	GitHub 个人访问令牌

## mcp#

管理模型上下文协议服务器。

bash
opencode mcp [command]

add

向配置添加 MCP 服务器。

bash
opencode mcp add

此命令将指导你添加本地或远程 MCP 服务器。

list

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

bash
opencode mcp list

或使用简短版本。

bash
opencode mcp ls

auth

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

bash
opencode mcp auth [name]

如果你不提供服务器名称，你将被提示从可用的支持 OAuth 的服务器中选择。

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

bash
opencode mcp auth list

或使用简短版本。

bash
opencode mcp auth ls

logout

删除 MCP 服务器的 OAuth 凭据。

bash
opencode mcp logout [name]

debug

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

bash
opencode mcp debug <name>

## models#

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

bash
opencode models [provider]

此命令以 provider/model 格式显示你配置的提供商的所有可用模型。

这对于确定要在配置中使用的确切模型名称很有用。

你可以选择传递提供商 ID 以按该提供商过滤模型。

bash
opencode models anthropic

标志

标志	描述
`--refresh`	从 models.dev 刷新模型缓存
`--verbose`	使用更详细的模型输出（包括成本等元数据）

使用 --refresh 标志更新缓存的模型列表。当新模型已添加到提供商且你想在 OpenCode 中看到它们时，这很有用。

bash
opencode models --refresh

## run#

通过直接传递提示以非交互模式运行 opencode。

bash
opencode run [message..]

这对于脚本编写、自动化或当你想快速获得答案而不启动完整 TUI 时很有用。例如。

bash
opencode run 解释 Go 中 context 的用法

你也可以附加到运行的 opencode serve 实例，以避免每次运行时 MCP 服务器冷启动时间：

bash
1# 在一个终端中启动无头服务器
2opencode serve
3
4# 在另一个终端中，运行附加到它的命令
5opencode run --attach http://localhost:4096 "解释 JavaScript 中的 async/await"

标志

标志	简写	描述
`--command`		要运行的命令，使用 message 作为参数
`--continue`	`-c`	继续上一个会话
`--session`	`-s`	要继续的会话 ID
`--share`		分享会话
`--model`	`-m`	要使用的模型，格式为 provider/model
`--agent`		要使用的代理
`--file`	`-f`	附加到消息的文件
`--format`		格式：default（格式化）或 json（原始 JSON 事件）
`--title`		会话标题（如果未提供值则使用截断的提示）
`--attach`		附加到运行的 opencode 服务器（例如 http://localhost:4096）↗
`--port`		本地服务器端口（默认为随机端口）

## serve#

启动无头 OpenCode 服务器以进行 API 访问。查看服务器文档了解完整的 HTTP 接口。

bash
opencode serve

这启动一个 HTTP 服务器，提供对 opencode 功能的 API 访问，而无需 TUI 界面。

标志

标志	描述
`--port`	监听端口
`--hostname`	监听主机名
`--mdns`	启用 mDNS 发现
`--cors`	允许 CORS 的额外浏览器来源

## session#

管理 OpenCode 会话。

bash
opencode session [command]

list

列出所有 OpenCode 会话。

bash
opencode session list

标志

标志	简写	描述
`--max-count`	`-n`	限制为 N 个最近会话
`--format`		输出格式：table 或 json（table）

## stats#

显示 OpenCode 会话的令牌使用和成本统计。

bash
opencode stats

标志

标志	描述
`--days`	显示最近 N 天的统计（所有时间）
`--tools`	显示的工具数量（全部）
`--models`	显示模型使用细分（默认隐藏）。传递数字以显示前 N 个
`--project`	按项目过滤（所有项目，空字符串：当前项目）

## export#

将会话数据导出为 JSON。

bash
opencode export [sessionID]

如果你不提供会话 ID，你将被提示从可用会话中选择。

## import#

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

bash
opencode import <file>

你可以从本地文件或 OpenCode 分享 URL 导入。

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

## web#

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

bash
opencode web

这启动一个 HTTP 服务器并打开 Web 浏览器，通过 Web 界面访问 OpenCode。

标志

标志	描述
`--port`	监听端口
`--hostname`	监听主机名
`--mdns`	启用 mDNS 发现
`--cors`	允许 CORS 的额外浏览器来源

## acp#

启动 ACP（代理客户端协议）服务器。

bash
opencode acp

此命令启动一个 ACP 服务器，通过 stdin/stdout 使用 nd-JSON 进行通信。

标志

标志	描述
`--cwd`	工作目录
`--port`	监听端口
`--hostname`	监听主机名

## uninstall#

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

bash
opencode uninstall

标志

标志	简写	描述
`--keep-config`	`-c`	保留配置文件
`--keep-data`	`-d`	保留会话数据和快照
`--dry-run`		显示将被删除的内容而不删除
`--force`	`-f`	跳过确认提示

## upgrade#

手动安装 OpenCode 更新。

版本说明（核验：2026-10-12）： 本节按 v1.19.0（2026-10-11）发布说明↗ 和该版本源码核验；参数与升级路径不保证适用于较早版本或 OpenCode 2。

bash
opencode upgrade [target]

在 v1.19.0 中，不指定目标时按现有安装渠道获取更新；此路径与跨到 OpenCode 2 的 --major 操作分开。具体可获取的版本由安装渠道决定。

bash
opencode upgrade

指定目标版本时，填写该渠道支持的版本号，例如：

bash
opencode upgrade v1.19.0

明确决定迁移到 OpenCode 2 时使用：

bash
opencode upgrade --major

--major 会安装 OpenCode 2，并按安装方式替换 OpenCode 1。它不是普通补丁更新；先阅读 OpenCode 2 官方文档↗。安装渠道不支持自动迁移时，命令会提示手动安装路径。

标志

标志	简写	描述
`--method`	`-m`	使用的安装方法；curl、npm、pnpm、bun、brew、choco、scoop
`--major`		v1.19.0 提供的 OpenCode 2 迁移入口

v1.19.0 不再自动安装更新；检查通知由 autoupdate 控制，也可在 TUI 中使用 /update。以上是命令源码↗ 的文档核验，未在本机执行升级。

# 全局标志#

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_CLIENT`	string	客户端标识符（默认为 `cli`）
`OPENCODE_ENABLE_EXA`	boolean	启用 Exa 网页搜索工具

## 实验性#

这些环境变量启用可能更改或删除的实验性功能。

变量	类型	描述
`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 响应的最大输出令牌
`OPENCODE_EXPERIMENTAL_FILEWATCHER`	boolean	为整个目录启用文件监视器
`OPENCODE_EXPERIMENTAL_OXFMT`	boolean	启用 oxfmt 格式化器
`OPENCODE_EXPERIMENTAL_LSP_TOOL`	boolean	启用实验性 LSP 工具

CLI

标志

create

list

标志

login

list

logout

install

run

标志

add

list

auth

logout

debug

标志

标志

标志

list

标志

标志

标志

标志

标志

标志

相关文档