CLI

OpenCode CLI 的选项与命令。

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

opencode

但它也接受本页文档所列的命令。这让你可以通过编程方式与 OpenCode 交互。

opencode run "Explain how closures work in JavaScript"

tui

启动 OpenCode 终端用户界面。

opencode [project]

标志

标志	简写	说明
`--continue`	`-c`	继续上一个会话
`--session`	`-s`	要继续的会话 ID
`--fork`		继续时 fork 该会话（与 `--continue` 或 `--session` 一起使用）
`--prompt`		要使用的提示词
`--model`	`-m`	以 provider/model 形式指定要使用的模型
`--agent`		要使用的 agent
`--port`		监听的端口
`--hostname`		监听的主机名
`--mdns`		启用 mDNS 发现
`--mdns-domain`		自定义 mDNS 域名
`--cors`		额外允许 CORS 的浏览器源

命令

OpenCode CLI 还提供以下命令。

agent

管理 OpenCode 的 agents。

opencode agent [command]

create

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

opencode agent create

该命令会引导你创建一个带自定义系统提示词和权限配置的新 agent。任何你未允许的内容都会在生成的 agent frontmatter 中被拒绝。

标志

标志	简写	说明
`--path`		写入 agent 文件的目录（根据提示默认为全局或 `.opencode/agent`）
`--description`		该 agent 应做什么
`--mode`		Agent 模式：`all`、`primary` 或 `subagent`
`--permissions`		逗号分隔的允许权限列表（默认：全部）。可用：`bash`、`read`、`edit`、`glob`、`grep`、`webfetch`、`task`、`todowrite`、`websearch`、`lsp`、`skill`。任何省略的都会被拒绝。别名：`--tools`
`--model`	`-m`	要使用的模型，采用 `provider/model` 格式

同时传入 --path、--description、--mode 和 --permissions 会以非交互方式运行该命令。

list

列出所有可用的 agents。

opencode agent list

attach

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

opencode attach [url]

这让你可以将 TUI 与一个远程 OpenCode 后端配合使用。例如：

# Start the backend server for web/mobile access
opencode web --port 4096 --hostname 0.0.0.0
 
# In another terminal, attach the TUI to the running backend
opencode attach http://10.20.30.40:4096

标志

标志	简写	说明
`--dir`		启动 TUI 时所在的工作目录
`--continue`	`-c`	继续上一个会话
`--session`	`-s`	要继续的会话 ID
`--fork`		继续时 fork 该会话（与 `--continue` 或 `--session` 一起使用）
`--password`	`-p`	Basic auth 密码（默认为 `OPENCODE_SERVER_PASSWORD`）
`--username`	`-u`	Basic auth 用户名（默认为 `OPENCODE_SERVER_USERNAME` 或 `opencode`）

auth

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

opencode auth [command]

login

OpenCode 由 Models.dev (opens in a new tab) 上的提供商列表驱动，因此你可以使用 opencode auth login 为任何你想使用的提供商配置 API 密钥。它存储在 ~/.local/share/opencode/auth.json 中。

opencode auth login

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

标志

标志	简写	说明
`--provider`	`-p`	要登录的提供商 ID 或名称
`--method`	`-m`	要使用的登录方法标签，可跳过方法选择

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 个人访问令牌

mcp

管理 Model Context Protocol 服务器。

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 中看到它们时，这很有用。

opencode models --refresh

run

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

opencode run [message..]

这对于脚本编写、自动化，或者你想要快速得到答案而无需启动完整 TUI 时很有用。例如：

opencode run Explain the use of context in Go

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

# Start a headless server in one terminal
opencode serve
 
# In another terminal, run commands that attach to it
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

标志

标志	简写	说明
`--command`		要运行的命令，使用 message 作为参数
`--continue`	`-c`	继续上一个会话
`--session`	`-s`	要继续的会话 ID
`--fork`		继续时 fork 该会话（与 `--continue` 或 `--session` 一起使用）
`--share`		分享该会话
`--model`	`-m`	以 provider/model 形式指定要使用的模型
`--agent`		要使用的 agent
`--file`	`-f`	要附加到消息的文件
`--format`		格式：default（已格式化）或 json（原始 JSON 事件）
`--title`		会话标题（若未提供值则使用截断的提示词）
`--attach`		附加到一个正在运行的 opencode 服务器（例如 http://localhost:4096 (opens in a new tab)）
`--password`	`-p`	Basic auth 密码（默认为 `OPENCODE_SERVER_PASSWORD`）
`--username`	`-u`	Basic auth 用户名（默认为 `OPENCODE_SERVER_USERNAME` 或 `opencode`）
`--dir`		运行所在的目录，或附加时远程服务器上的路径
`--port`		本地服务器的端口（默认为随机端口）
`--variant`		模型变体（提供商专属的推理强度）
`--thinking`		显示 thinking 块
`--dangerously-skip-permissions`		自动批准未被明确拒绝的权限（危险！）

serve

启动一个用于 API 访问的无头 OpenCode 服务器。完整的 HTTP 接口请查看服务器文档。

opencode serve

这会启动一个 HTTP 服务器，在没有 TUI 界面的情况下提供对 opencode 功能的 API 访问。设置 OPENCODE_SERVER_PASSWORD 可启用 HTTP basic auth（用户名默认为 opencode）。

标志

标志	说明
`--port`	监听的端口
`--hostname`	监听的主机名
`--mdns`	启用 mDNS 发现
`--mdns-domain`	自定义 mDNS 域名
`--cors`	额外允许 CORS 的浏览器源

session

管理 OpenCode 会话。

opencode session [command]

list

列出所有 OpenCode 会话。

opencode session list

标志

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

delete

删除一个 OpenCode 会话。

opencode session delete <sessionID>

stats

显示你的 OpenCode 会话的 token 用量和成本统计。

opencode stats

标志

标志	说明
`--days`	显示最近 N 天的统计（默认全部时间）
`--tools`	要显示的工具数量（默认全部）
`--models`	显示模型用量明细（默认隐藏）。传入一个数字以显示前 N 个
`--project`	按项目筛选（默认所有项目，空字符串：当前项目）

export

以 JSON 形式导出会话数据。

opencode export [sessionID]

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

标志

标志	说明
`--sanitize`	脱敏处理敏感的转录/文件数据

import

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

opencode import <file>

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

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

web

启动一个带 web 界面的无头 OpenCode 服务器。

opencode web

这会启动一个 HTTP 服务器并打开一个网页浏览器，让你通过 web 界面访问 OpenCode。设置 OPENCODE_SERVER_PASSWORD 可启用 HTTP basic auth（用户名默认为 opencode）。

标志

标志	说明
`--port`	监听的端口
`--hostname`	监听的主机名
`--mdns`	启用 mDNS 发现
`--mdns-domain`	自定义 mDNS 域名
`--cors`	额外允许 CORS 的浏览器源

acp

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

opencode acp

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

标志

标志	说明
`--cwd`	工作目录
`--port`	监听的端口
`--hostname`	监听的主机名
`--mdns`	启用 mDNS 发现
`--mdns-domain`	自定义 mDNS 域名
`--cors`	额外允许 CORS 的浏览器源

plugin

安装一个插件并更新你的配置。

opencode plugin <module>

或使用别名。

opencode plug <module>

标志

标志	简写	说明
`--global`	`-g`	安装到全局配置
`--force`	`-f`	替换现有的插件版本

pr

获取并检出一个 GitHub PR 分支，然后运行 OpenCode。

opencode pr <number>

db

数据库工具。

opencode db [query]

标志

标志	说明
`--format`	输出格式：`json` 或 `tsv`

path

打印数据库路径。

opencode db path

debug

调试与故障排除工具。

opencode debug [command]

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）
`--pure`		不加载外部插件运行

环境变量

OpenCode 可以通过环境变量进行配置。

变量	类型	说明
`OPENCODE_AUTO_SHARE`	boolean	自动分享会话
`OPENCODE_GIT_BASH_PATH`	string	Windows 上 Git Bash 可执行文件的路径
`OPENCODE_CONFIG`	string	配置文件路径
`OPENCODE_TUI_CONFIG`	string	TUI 配置文件路径
`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` 读取（提示词 + 技能）
`OPENCODE_DISABLE_CLAUDE_CODE_PROMPT`	boolean	禁用读取 `~/.claude/CLAUDE.md`
`OPENCODE_DISABLE_CLAUDE_CODE_SKILLS`	boolean	禁用加载 `.claude/skills`
`OPENCODE_DISABLE_MODELS_FETCH`	boolean	禁用从远程源获取模型
`OPENCODE_DISABLE_MOUSE`	boolean	禁用 TUI 中的鼠标捕获
`OPENCODE_FAKE_VCS`	string	用于测试目的的伪 VCS 提供商
`OPENCODE_CLIENT`	string	客户端标识符（默认为 `cli`）
`OPENCODE_ENABLE_EXA`	boolean	启用 Exa 网络搜索工具
`OPENCODE_SERVER_PASSWORD`	string	为 `serve`/`web` 启用 basic auth
`OPENCODE_SERVER_USERNAME`	string	覆盖 basic auth 用户名（默认 `opencode`）
`OPENCODE_MODELS_URL`	string	用于获取模型配置的自定义 URL

实验性

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

变量	类型	说明
`OPENCODE_EXPERIMENTAL`	boolean	启用所有实验性功能
`OPENCODE_EXPERIMENTAL_ICON_DISCOVERY`	boolean	启用图标发现
`OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT`	boolean	禁用 TUI 中的选中即复制
`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 工具
`OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER`	boolean	禁用文件监视器
`OPENCODE_EXPERIMENTAL_EXA`	boolean	启用实验性 Exa 功能
`OPENCODE_EXPERIMENTAL_LSP_TY`	boolean	为 python 文件启用 TY LSP
`OPENCODE_EXPERIMENTAL_PLAN_MODE`	boolean	启用 plan 模式

TUI 终端界面 Web 网页版