古法编程

OpenCode CLI 不只是一个启动终端界面的命令，它还支持非交互式运行、会话管理、模型列表查询、MCP 服务器管理等丰富功能。本文整理了所有子命令与标志，帮助你在脚本和自动化场景中灵活调用 OpenCode。

opencode 命令默认启动 TUI 终端界面。但它也支持大量子命令，可以以编程方式与 OpenCode 交互。

opencode run "用一句话解释 JavaScript 中的闭包"

tui（默认）

直接运行 opencode 启动 TUI 界面：

opencode [project]
标志 简写 说明
--continue -c 继续上一个会话
--session -s 指定要继续的 Session ID
--fork 继续会话时 fork 一个分支（与 --continue 或 --session 配合使用）
--prompt 指定使用的 Prompt
--model -m 指定模型，格式为 provider/model
--agent 指定使用的 Agent
--port 监听端口
--hostname 监听主机名

子命令

agent

管理 OpenCode Agents：

opencode agent [command]

agent create

创建自定义 Agent（带引导式交互）：

opencode agent create

agent list

列出所有可用 Agent：

opencode agent list

attach

将终端 TUI 连接到已在运行的 OpenCode 后端服务器（由 serve 或 web 命令启动）：

opencode attach [url]

典型场景：

# 在服务器或另一终端启动后端
opencode web --port 4096 --hostname 0.0.0.0

# 在本地用 TUI 连接到远程后端
opencode attach http://10.20.30.40:4096
标志 说明
--dir TUI 的工作目录
--session -s 要继续的 Session ID

auth

管理 Provider 凭证：

opencode auth [command]

auth login

交互式配置 API 密钥，支持 Models.dev 上的所有 Provider，凭证存储在 ~/.local/share/opencode/auth.json：

opencode auth login

auth list / ls

列出所有已认证的 Provider：

opencode auth list
opencode auth ls

auth logout

清除某个 Provider 的认证信息：

opencode auth logout

github

管理 GitHub Agent（用于仓库自动化）：

opencode github [command]

github install

在仓库中安装 GitHub Actions 工作流：

opencode github install

github run

运行 GitHub Agent（通常在 GitHub Actions 中调用）：

opencode github run
标志 说明
--event 模拟的 GitHub 事件
--token GitHub Personal Access Token

mcp

管理 MCP 服务器：

opencode mcp [command]

mcp add

交互式添加 MCP 服务器（本地或远程）：

opencode mcp add

mcp list / ls

列出已配置的 MCP 服务器及连接状态：

opencode mcp list
opencode mcp ls

mcp auth

对支持 OAuth 的 MCP 服务器进行认证：

opencode mcp auth [name]
opencode mcp auth list  # 查看 OAuth 认证状态

mcp logout

移除 MCP 服务器的 OAuth 凭证：

opencode mcp logout [name]

mcp debug

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

opencode mcp debug <name>

models

列出所有可用模型：

opencode models [provider]

输出格式为 provider/model，可用于 config 中的 model 字段。

opencode models anthropic       # 只看 Anthropic 的模型
opencode models --refresh       # 刷新模型缓存
opencode models --verbose       # 显示成本等详细信息

run

非交互式运行 OpenCode，直接传入 Prompt：

opencode run [message..]

适合脚本、CI/CD 等自动化场景：

opencode run "解释 Go 中 context 的用法"

与 serve 配合使用，避免 MCP 服务器每次冷启动：

# 先启动无头服务器
opencode serve

# 在另一终端直接发送请求
opencode run --attach http://localhost:4096 "解释 async/await"
标志 简写 说明
--continue -c 继续上一个会话
--session -s 指定 Session ID
--fork Fork 会话
--share 分享本次会话
--model -m 指定模型
--agent 指定 Agent
--file -f 附加文件
--format 输出格式：default 或 json
--title 会话标题
--attach 连接到运行中的 opencode 服务器
--port 本地服务端口
--dangerously-skip-permissions 自动批准所有未显式拒绝的权限请求（危险！）

serve

启动无头 HTTP 服务器（无 TUI），可通过 API 访问 OpenCode 功能：

opencode serve

设置 OPENCODE_SERVER_PASSWORD 可启用 HTTP Basic Auth（默认用户名为 opencode）。

标志 说明
--port 监听端口
--hostname 监听主机名
--mdns 启用 mDNS 发现
--cors 允许的额外浏览器 origin

session

管理会话：

opencode session list
标志 说明
--max-count -n 只显示最近 N 条
--format 输出格式：table 或 json

stats

查看 Token 使用量和费用统计：

opencode stats
标志 说明
--days 最近 N 天（不填则显示全部）
--tools 显示 Tool 使用量（前 N 个）
--models 显示模型使用分布
--project 按项目筛选

export / import

会话数据的导入导出：

opencode export [sessionID]          # 导出为 JSON
opencode import session.json         # 从本地文件导入
opencode import https://opncd.ai/s/abc123   # 从分享 URL 导入

web

启动带 Web 界面的服务器并自动打开浏览器：

opencode web

参数与 serve 相同。

acp

启动 ACP 服务器（通过 stdin/stdout 的 nd-JSON 协议通信）：

opencode acp

uninstall

卸载 OpenCode 并清理相关文件：

opencode uninstall
标志 说明
--keep-config -c 保留配置文件
--keep-data -d 保留会话数据和快照
--dry-run 预览要删除的内容
--force -f 跳过确认提示

upgrade

升级到最新版本或指定版本：

opencode upgrade
opencode upgrade v0.1.48
标志 说明
--method -m 安装方式：curl、npm、pnpm、bun、brew

全局标志

标志 简写 说明
--help -h 显示帮助
--version -v 显示版本号
--print-logs 将日志打印到 stderr
--log-level 日志级别（DEBUG / INFO / WARN / ERROR）

环境变量

变量 类型 说明
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 禁用自动 Context 压缩
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_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_PLAN_MODE boolean 启用 Plan Mode
OPENCODE_EXPERIMENTAL_LSP_TOOL boolean 启用实验性 LSP 工具
OPENCODE_EXPERIMENTAL_FILEWATCHER boolean 启用整目录文件监听
OPENCODE_EXPERIMENTAL_OXFMT boolean 启用 oxfmt 格式化器
OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS number Bash 命令默认超时（毫秒）
OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX number LLM 响应最大输出 Token 数

常见问题

Q: 如何在 CI/CD 中批量处理代码审查？

A: 用 opencode run 命令，配合 --format json 获取结构化输出，方便脚本解析。也可以先用 opencode serve 在后台跑一个服务，多个 run 命令共享 MCP 服务器，避免每次冷启动。

Q: 如何查看某个 Provider 都有哪些模型可用？

A: opencode models <provider_id> 列出该 Provider 的所有模型，例如 opencode models anthropic。如果列表不完整，加 --refresh 刷新缓存。

Q: OPENCODE_DISABLE_CLAUDE_CODE 这个变量是什么意思？

A: OpenCode 默认会读取项目中的 .claude/ 目录（兼容 Claude Code 的 Prompt 和 Skills 格式）。如果你不想要这个行为，设置该变量为 true 即可。