CLI 命令与参数参考

命令行没有子命令时进入 TUI。opencode --help 与具体子命令帮助用于核对本机版本；此页按任务整理官方 CLI 页已列出的入口。

启动与连接

入口	使用场景
opencode [project]	在项目目录启动 TUI
opencode run [message..]	非交互提交任务
opencode serve	无界面 HTTP 服务
opencode web	启动后端并打开浏览器界面
opencode attach [url]	TUI 连接已有后端
opencode acp	向编辑器提供 ACP 子进程
opencode pr <number>	获取并检出 GitHub PR 分支，再运行 OpenCode

TUI 启动支持 --continue / -c、--session / -s、--fork、--prompt、--model / -m、--agent、--auto。其中 --fork 与继续选项一起使用，模型采用 provider/model。

服务监听选项为 --port、--hostname、--mdns、--mdns-domain、--cors；这些也在 TUI、serve、web 和 ACP 的官方参数表中列出。ACP 仍通过标准输入输出与编辑器通信，不要因看到监听参数就把 ACP 当成 HTTP API。

attach 支持 --dir、--continue / -c、--session / -s、--fork，以及 Basic Auth 的 --password / -p、--username / -u。用户名依次取显式选项、OPENCODE_SERVER_USERNAME、opencode；密码可取 OPENCODE_SERVER_PASSWORD。

run 的完整任务选项见非交互运行。

认证与模型

命令	作用
opencode auth login	配置提供商登录；--provider / -p 选 ID 或名称，--method / -m 指定登录方法标签
opencode auth list 或 auth ls	列出凭据文件中的提供商
opencode auth logout	清除所选提供商的保存凭据
opencode models [provider]	列出已配置提供商的模型；可按提供商过滤
opencode models --refresh	从 models.dev 刷新模型缓存
opencode models --verbose	展示成本等额外模型元数据

凭据文件是 ~/.local/share/opencode/auth.json。启动还会读取环境变量或项目 .env 中的 Key，因此 auth list 不等同于枚举所有可能的认证来源。

智能体与插件

opencode agent create 提供交互式创建流程；opencode agent list 列出可用智能体。创建选项如下：

选项	说明
--path	写入目录
--description	智能体的职责
--mode	all、primary 或 subagent
--permissions	逗号分隔的允许权限，别名 --tools；该选项默认 all，省略的权限会被拒绝
--model / -m	provider/model

同时提供 --path、--description、--mode、--permissions 可以非交互执行。允许项列为 bash、read、edit、glob、grep、webfetch、task、todowrite、websearch、lsp、skill。

CLI 页描述默认输出路径时仍使用 .opencode/agent，而 Agents 专门页使用 .opencode/agents/。Config 页明确支持单数目录以兼容旧用法，新内容推荐复数目录；可显式传入目标目录，并按智能体配置核对加载位置。

opencode plugin <module> 将插件加入配置，别名 opencode plug <module>；--global / -g 写全局配置，--force / -f 替换已有插件版本。加载与依赖处理见插件。

MCP 与 GitHub

命令	用途
opencode mcp add	交互添加本地或远程服务器
opencode mcp list / mcp ls	列出配置和连接状态
opencode mcp auth [name]	OAuth 登录；不传名称时选择服务器
opencode mcp auth list / mcp auth ls	查看 OAuth 状态
opencode mcp logout [name]	移除 OAuth 凭据
opencode mcp debug <name>	调试 OAuth 连接
opencode github install	配置仓库 GitHub Actions 集成
opencode github run	在工作流中运行 Agent；--event 指定模拟事件，--token 传 GitHub PAT

会话与维护

session list、session delete <sessionID>、stats、export [sessionID]、import <file> 的细节见会话管理。

命令	参数及行为
opencode db [query]	数据库工具；--format 可选 json 或 tsv
opencode db path	输出数据库路径
opencode debug [command]	调试工具入口；具体子命令以本机帮助为准
opencode upgrade [target]	更新到最新版或指定版本；--method / -m 为 curl、npm、pnpm、bun、brew
opencode uninstall	卸载及删除相关文件；先用 --dry-run 查看范围

卸载可用 --keep-config / -c 保留配置、--keep-data / -d 保留会话与快照，--force / -f 跳过确认。

全局参数

参数	含义
--help / -h	帮助
--version / -v	版本
--print-logs	将日志写到 stderr
--log-level	DEBUG、INFO、WARN、ERROR
--pure	不加载外部插件

环境配置另见环境变量参考。