如果你最近在关注 AI 编程工具，大概已经听说过 OpenCode。它是一款开源的智能编程助手，不仅能像 Copilot 那样补全代码，还能在终端里跟你对话、执行任务、甚至管理整个项目的 Agent。而所有这些能力的入口，就是它的 CLI——一个命令行工具。

这篇文章会从头到尾介绍 OpenCode CLI 的功能。

起步：最简单的用法

安装好 OpenCode 之后，在终端里直接输入 opencode 不带任何参数，就会启动它的 TUI（文本用户界面）。这是一个全终端的交互界面，有点像那些经典的编辑器（比如 Vim 或者 Nano），可以用键盘操作来完成各种任务。

opencode

不过 OpenCode 真正的灵活之处在于它接受各种命令和参数。通过这些命令，就能以编程方式调用 OpenCode，把它嵌入脚本、自动化流程或者远程服务里。

opencode run "解释一下 JavaScript 里的闭包是怎么工作的"

TUI 界面：日常工作的主战场

TUI 是大部分人平时主要使用的模式。启动时可以指定一个项目目录：

opencode [项目路径]

如果不给路径，就默认在当前目录下工作。

TUI 相关的 Flags

Flag	短选项	说明
--continue	-c	继续上一次的会话
--session	-s	指定要继续的会话 ID
--fork	无	继续会话时派生出一个新分支（配合 --continue 或 --session 使用）
--prompt	无	直接传入提示词
--model	-m	指定使用的模型，格式为 提供商/模型名
--agent	无	指定使用的 Agent
--port	无	监听的端口
--hostname	无	监听的 hostname

核心命令详解

下面把 OpenCode 提供的各种命令分成几类来介绍。每个命令都有自己的子命令和参数。

agent —— 管理 Agent

Agent 是 OpenCode 里负责执行特定任务的“智能体”。通过 agent 命令可以创建、列出和管理它们。

创建 Agent

opencode agent create

这个命令会以交互方式引导用户创建一个新的 Agent，包括自定义系统提示词和权限配置。在生成的 Agent 文件头部（frontmatter）里，凡是没明确允许的权限，都会默认被禁止。

创建 Agent 时还可以直接通过参数完成，无需交互：

Flag	说明
--path	写入 Agent 文件的目录（默认根据提示决定是全局目录还是项目里的 .opencode/agent）
--description	描述这个 Agent 应该做什么
--mode	Agent 的模式：all、primary 或 subagent
--permissions 或 --tools	允许的权限列表（逗号分隔），默认为 all。可用的权限包括：bash、read、edit、glob、grep、webfetch、task、todowrite、websearch、codesearch、lsp、skill。任何未列出的权限都会被拒绝
--model 或 -m	使用的模型，格式 提供商/模型名

列出 Agent

opencode agent list

attach —— 连接到远程后端

attach 命令用于把一个终端连接到已经在运行中的 OpenCode 后端服务器上（这个后端是通过 serve 或 web 命令启动的）。

opencode attach [URL]

这样一来就能用本地的 TUI 操作一个远程的 OpenCode 后端。举个例子：

# 在第一个终端里启动后端，开放 4096 端口，监听所有地址
opencode web --port 4096 --hostname 0.0.0.0

# 在第二个终端里，把 TUI 挂到这个后端上
opencode attach http://10.20.30.40:4096

attach 支持的 flag：

Flag	短选项	说明
--dir	无	启动 TUI 时使用的工作目录
--session	-s	指定要继续的会话 ID

auth —— 管理提供商登录

OpenCode 的模型支持来自 Models.dev 的列表，所以需要用 opencode auth 来配置各种提供商的 API Key。这些凭证默认存储在 ~/.local/share/opencode/auth.json 里。

登录

opencode auth login

OpenCode 启动时会从凭证文件加载提供商，同时也会读取环境变量或者项目里的 .env 文件中定义的 API Key。

列出已认证的提供商

opencode auth list

或者简写：

opencode auth ls

登出

opencode auth logout

这会从凭证文件中清除对应的提供商信息。

github —— GitHub 仓库自动化

这个命令用于管理 GitHub Agent，实现仓库级别的自动操作。

安装 GitHub Agent

opencode github install

该命令会在仓库中设置必要的 GitHub Actions 工作流，并通过引导流程完成配置。

运行 GitHub Agent

opencode github run

通常在 GitHub Actions 中使用。支持的 flag：

Flag	说明
--event	用于模拟的 GitHub 事件
--token	GitHub 个人访问令牌

mcp —— 管理 MCP 服务器

MCP（Model Context Protocol）是一种给 AI 模型提供额外上下文的协议。OpenCode 可以接入 MCP 服务器来扩展能力。

添加 MCP 服务器

opencode mcp add

这个命令会引导用户添加本地或远程的 MCP 服务器。

列出所有 MCP 服务器

opencode mcp list

简写：

opencode mcp ls

MCP 服务器认证

对于支持 OAuth 的 MCP 服务器，可以用以下命令认证：

opencode mcp auth [服务名]

如果不提供服务名，会提示从可选的 OAuth 服务器列表中选择。

列出支持 OAuth 的服务器及认证状态：

opencode mcp auth list

简写：

opencode mcp auth ls

清除 MCP 的 OAuth 凭证

opencode mcp logout [服务名]

调试 MCP 的 OAuth 连接问题

opencode mcp debug <服务名>

models —— 列出可用模型

这个命令会显示所有已配置的提供商提供的模型，格式为 提供商/模型名。对于确定配置中要用的具体模型名称很有帮助。

opencode models [提供商]

如果指定了提供商 ID，就只列出该提供商下的模型：

opencode models anthropic

支持的 flag：

Flag	说明
--refresh	从 models.dev 刷新模型缓存。当提供商新增了模型而 OpenCode 没有同步时，用这个更新
--verbose	输出更详细的模型信息，比如费用等元数据

run —— 非交互模式运行

这个是脚本化调用 OpenCode 的主力命令。直接传入提示词，就能得到答案，不会启动 TUI。

opencode run [消息...]

例如：

opencode run "解释一下 Go 语言里 context 的用法"

还可以连接到正在运行的 opencode serve 实例，避免每次执行都重新冷启动 MCP 服务器（这样能快很多）：

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

# 另一个终端里运行命令，挂载到这个服务器上
opencode run --attach http://localhost:4096 "解释 async/await"

run 支持的所有 flag：

Flag	短选项	说明
--command	无	要执行的命令，也可以用消息传参
--continue	-c	继续上一次会话
--session	-s	指定会话 ID 继续
--fork	无	继续时派生新分支（配合 --continue 或 --session）
--share	无	共享当前会话
--model	-m	使用的模型，格式 提供商/模型名
--agent	无	使用的 Agent
--file	-f	要附加到消息的文件（可多次使用）
--format	无	输出格式：default（格式化文本）或 json（原始 JSON 事件流）
--title	无	会话标题（若不提供，会截取提示词前几个字作为标题）
--attach	无	连接到正在运行的 OpenCode 服务器，如 http://localhost:4096
--port	无	本地服务器端口（默认随机分配）
--dangerously-skip-permissions	无	自动批准所有没有被明确拒绝的权限。危险选项，仅在确实了解后果时使用

serve —— 启动 API 服务器（无头模式）

启动一个不带 Web 界面的纯 HTTP 服务，提供 OpenCode 的 API 访问能力。

opencode serve

可以设置 OPENCODE_SERVER_PASSWORD 环境变量来启用 HTTP 基础认证（默认用户名为 opencode）。

支持的 flag：

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

session —— 管理会话

会话记录了每一次与 OpenCode 互动的完整上下文。

列出会话

opencode session list

支持的 flag：

Flag	短选项	说明
--max-count	-n	只显示最近的 N 个会话
--format	无	输出格式：table（表格）或 json，默认 table

stats —— 查看用量和费用统计

展示所有 OpenCode 会话的 token 消耗和费用统计。

opencode stats

支持的 flag：

Flag	说明
--days	显示最近 N 天的统计（不指定则显示所有时间）
--tools	显示的工具数量（默认 all 即全部）
--models	显示模型使用量细分。可以传一个数字来限制显示的模型数量（默认隐藏，需主动开启）
--project	按项目过滤（默认所有项目。传空字符串只显示当前项目）

export 与 import —— 导入导出会话

导出会话为 JSON

opencode export [会话ID]

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

导入会话

可以从本地 JSON 文件或 OpenCode 分享链接导入会话：

opencode import <文件路径>
opencode import session.json
opencode import https://opncd.ai/s/abc123

web —— 启动带 Web 界面的服务器

与 serve 不同，web 命令不仅启动 API 服务器，还会打开一个网页浏览器，通过 Web 界面访问 OpenCode。

opencode web

同样支持 OPENCODE_SERVER_PASSWORD 来启用 HTTP 基础认证。flag 与 serve 完全一致：--port、--hostname、--mdns、--cors。

acp —— ACP 服务器

ACP（Agent Client Protocol）是一种通过标准输入输出通信的协议。启动后使用 nd-JSON 格式通信。

opencode acp

支持的 flag：

Flag	说明
--cwd	工作目录
--port	监听端口
--hostname	监听的 hostname

uninstall —— 卸载 OpenCode

彻底移除 OpenCode 及其相关文件。

opencode uninstall

支持的 flag：

Flag	短选项	说明
--keep-config	-c	保留配置文件
--keep-data	-d	保留会话数据和快照
--dry-run	无	只显示会删除哪些内容，并不实际删除
--force	-f	跳过确认提示

upgrade —— 升级版本

更新 OpenCode 到最新版本或指定版本。

opencode upgrade [目标版本]

升级到最新版：

opencode upgrade

升级到特定版本（比如 v0.1.48）：

opencode upgrade v0.1.48

支持的 flag：

Flag	短选项	说明
--method	-m	指定当初使用的安装方法：curl、npm、pnpm、bun、brew

全局 Flags

这些 flag 适用于所有 opencode 命令：

Flag	短选项	说明
--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_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 目录（包括 prompt 和 skills）
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 启用基础认证的密码
OPENCODE_SERVER_USERNAME	string	覆盖基础认证的用户名（默认 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_MARKDOWN	boolean	启用实验性 Markdown 功能
OPENCODE_EXPERIMENTAL_PLAN_MODE	boolean	启用计划模式

---

以上就是 OpenCode CLI 的完整功能介绍。从日常交互的 TUI，到远程开发、自动化脚本、模型管理、会话统计乃至 GitHub 集成，这个工具几乎覆盖了开发者能想到的所有使用场景。想要真正把 OpenCode 用顺手，花点时间熟悉这些命令和参数会很有帮助。如果有哪个功能没有讲清楚，可以参考 OpenCode 官方文档或者在终端里直接敲 opencode --help，每个命令下也都有相应的帮助信息。