OpenCode CLI 参考手册

版本：1.3.15 | 安装路径：/opt/homebrew/bin/opencode

官方地址：https://opencode.ai/ | 安装命令：curl -fsSL https://opencode.ai/install.sh | bash

概述

OpenCode 是一个交互式 CLI 工具，提供 TUI（终端用户界面）和 headless 模式，用于与 AI 模型交互、管理会话、操作代码等。它支持多种 AI 提供商、MCP/ACP 协议、GitHub 集成和插件扩展。

快速开始

在当前目录启动 TUI 交互界面

opencode
在指定项目目录启动

opencode /path/to/project
直接运行一条命令（非交互模式）

opencode run "帮我写一个 hello world"
继续上一次的会话

opencode -c
查看版本

opencode -v

全局选项

以下选项可用于所有命令：

选项	说明	默认值
`-h, --help`	显示帮助信息	-
`-v, --version`	显示版本号	-
`--print-logs`	将日志输出到 stderr	`false`
`--log-level`	日志级别：`DEBUG` / `INFO` / `WARN` / `ERROR`	-
`--pure`	不加载外部插件运行	`false`

网络选项（serve/web/attach 等共享）

选项	说明	默认值
`--port`	监听端口	`0`（随机）
`--hostname`	监听主机名	`127.0.0.1`
`--mdns`	启用 mDNS 服务发现	`false`
`--mdns-domain`	自定义 mDNS 域名	`opencode.local`
`--cors`	额外允许的 CORS 域名	`[]`

核心命令

`opencode`（启动 TUI）

启动 OpenCode 的终端交互界面（默认命令）。

opencode [project]

参数：

参数	说明
`project`	项目路径（可选）

选项：

选项	说明
`-m, --model`	指定使用的模型
`-c, --continue`	继续上一次会话
`-s, --session`	继续指定会话
`--fork`	以 fork 模式继续会话（与 `-c` 或 `-s` 配合使用）
`--prompt`	指定系统提示词
`--agent`	指定使用的 Agent

示例：

使用特定模型启动

opencode -m anthropic/claude-sonnet-4-20250514
继续上次会话

opencode -c
Fork 上次会话继续

opencode -c --fork
在指定目录启动

opencode ~/projects/my-app

`opencode run [message..]`

以非交互模式运行 OpenCode，发送消息并获取结果。

opencode run [message..]

参数：

参数	说明
`message`	要发送的消息（可多个单词）

选项：

选项	说明
`--command`	运行命令，用 message 作为参数
`-c, --continue`	继续上次会话
`-s, --session`	继续指定会话
`--fork`	Fork 模式继续（需要 `-c` 或 `-s`）
`--share`	分享会话
`-m, --model`	指定模型
`--agent`	指定 Agent
`--format`	json>	输出格式：`default`（格式化）或 `json`（原始 JSON）
`-f, --file`	附加文件到消息
`--title`	会话标题（默认截取 prompt）
`--attach`	附加到运行中的服务器
`-p, --password`	基础认证密码
`--dir`	运行目录
`--port`	本地服务器端口
`--variant`	模型变体（推理强度，如 `high`、`max`、`minimal`）
`--thinking`	显示思考过程

示例：

简单执行

opencode run "解释这段代码的作用"
附加文件

opencode run "审查这个文件" -f src/main.ts
JSON 输出（适合管道处理）

opencode run "列出所有 TODO" --format json
使用特定模型和推理强度

opencode run "重构这段代码" -m anthropic/claude-sonnet-4-20250514 --variant high
附加文件并设置标题

opencode run "优化性能" -f src/index.ts -f src/utils.ts --title "性能优化"
附加到远程服务器执行

opencode run "检查日志" --attach http://localhost:4096 --dir /app/logs

`opencode serve`

启动无头（headless）OpenCode 服务器，不打开 TUI 界面。

opencode serve

选项： 同网络选项

示例：

启动服务，监听 8080 端口

opencode serve --port 8080
允许局域网访问

opencode serve --hostname 0.0.0.0 --port 4096
启用 mDNS 发现

opencode serve --mdns

`opencode web`

启动服务器并自动打开 Web 界面。

opencode web

选项： 同网络选项

示例：

启动 Web 界面

opencode web --port 3000
局域网访问 Web 界面

opencode web --hostname 0.0.0.0 --port 3000 --cors http://myapp.local

`opencode attach`

连接到一个运行中的 OpenCode 服务器。

opencode attach

参数：

参数	说明	默认值
`url`	服务器 URL	`http://localhost:4096`

选项：

选项	说明
`--dir`	运行目录
`-c, --continue`	继续上次会话
`-s, --session`	继续指定会话
`--fork`	Fork 模式继续
`-p, --password`	基础认证密码

示例：

连接本地服务器

opencode attach http://localhost:4096
带密码连接远程服务器

opencode attach http://remote:4096 -p mypassword

会话管理

`opencode session`

管理会话。

opencode session

#### 子命令

##### session list

列出所有会话。

opencode session list

选项	说明
`-n, --max-count`	限制显示最近 N 个会话
`--format`	json>	输出格式，默认 `table`

示例：

列出最近 10 个会话

opencode session list -n 10
JSON 格式输出

opencode session list --format json

##### session delete

删除指定会话。

opencode session delete

`opencode export [sessionID]`

将会话数据导出为 JSON。

opencode export [sessionID]

参数：

参数	说明
`sessionID`	要导出的会话 ID（可选，不指定则导出当前会话）

`opencode import`

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

opencode import

参数：

参数	说明
`file`	JSON 文件路径或分享 URL

`opencode stats`

显示 Token 使用和费用统计。

opencode stats

选项	说明
`--days`	显示最近 N 天的统计（默认全部）
`--tools`	显示前 N 个工具使用情况（默认全部）
`--models [N]`	显示模型统计（可指定数量）
`--project`	按项目过滤（空字符串表示当前项目）

输出示例：

OVERVIEW:
  Sessions: 230 | Messages: 9,633 | Days: 79
COST & TOKENS:
  Total Cost: $1.35 | Avg Cost/Day: $0.02
  Input: 53.1M | Output: 2.9M | Cache Read: 585.3M
TOOL USAGE (Top 5):
  bash     3426 (31.5%)
  read     2988 (27.4%)
  edit      915 ( 8.4%)
  glob      736 ( 6.8%)
  apply_patch 666 ( 6.1%)

示例：

最近 7 天统计

opencode stats --days 7
按项目过滤

opencode stats --project "my-app"
显示模型统计

opencode stats --models
只显示前 5 个工具

opencode stats --tools 5

模型与提供商

`opencode models [provider]`

列出所有可用模型。

opencode models [provider]

参数	说明
`provider`	按提供商 ID 过滤（可选）

选项	说明
`--verbose`	详细输出（包含费用等元数据）
`--refresh`	从 models.dev 刷新模型缓存

示例：

列出所有模型

opencode models
列出 anthropic 的模型

opencode models anthropic
详细模式

opencode models --verbose
刷新缓存

opencode models --refresh

`opencode providers`（别名：`auth`）

管理 AI 提供商和凭证。

opencode providers

#### 子命令

##### providers list（别名：ls）

列出所有已配置的提供商和凭证。

opencode providers list

##### providers login [url]

登录提供商。

opencode providers login [url]

选项	说明
`-p, --provider`	提供商 ID 或名称（跳过选择步骤）
`-m, --method`	登录方式标签（跳过选择步骤）

示例：

交互式登录

opencode providers login
直接登录指定提供商

opencode providers login -p anthropic
指定登录方式

opencode providers login -p anthropic -m "API Key"

##### providers logout

登出已配置的提供商。

opencode providers logout

Agent 管理

`opencode agent`

管理 Agent。

opencode agent

#### 子命令

##### agent list

列出所有可用 Agent。

opencode agent list

##### agent create

创建新的 Agent。

opencode agent create

选项	说明
`--path`	生成 Agent 文件的目录路径
`--description`	Agent 功能描述
`--mode`	primary\	subagent>	Agent 模式
`--tools`	启用的工具列表（逗号分隔）
`-m, --model`	使用的模型

可用工具：bash, read, write, edit, list, glob, grep, webfetch, task, todowrite

示例：

交互式创建

opencode agent create
指定参数创建

opencode agent create --description "代码审查 Agent" --mode subagent --tools "read,glob,grep"
使用特定模型

opencode agent create -m anthropic/claude-sonnet-4-20250514 --description "测试生成 Agent"

MCP 服务器管理

`opencode mcp`

管理 MCP（Model Context Protocol）服务器。

opencode mcp

#### 子命令

##### mcp add

添加 MCP 服务器（交互式）。

opencode mcp add

##### mcp list（别名：ls）

列出 MCP 服务器及其状态。

opencode mcp list

##### mcp auth [name]

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

opencode mcp auth [name]

##### mcp logout [name]

移除 MCP 服务器的 OAuth 凭证。

opencode mcp logout [name]

##### mcp debug

调试 MCP 服务器的 OAuth 连接。

opencode mcp debug

ACP 服务器

`opencode acp`

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

opencode acp

选项	说明	默认值
`--cwd`	工作目录	当前目录

其他选项同网络选项。

示例：

启动 ACP 服务器

opencode acp
指定工作目录

opencode acp --cwd /path/to/project --port 4096

插件管理

`opencode plugin` （别名：`plug`）

安装插件并更新配置。

opencode plugin

参数：

参数	说明
`module`	npm 模块名

选项	说明
`-g, --global`	安装到全局配置
`-f, --force`	替换已有的插件版本

示例：

安装插件

opencode plugin @opencode/plugin-example
全局安装

opencode plugin @opencode/plugin-example -g
强制替换

opencode plugin @opencode/plugin-example -f

GitHub 集成

`opencode github`

管理 GitHub Agent。

opencode github

#### 子命令

##### github install

安装 GitHub Agent。

opencode github install

##### github run

运行 GitHub Agent。

opencode github run

选项	说明
`--event`	模拟的 GitHub 事件
`--token`	GitHub Personal Access Token

示例：

安装 GitHub Agent

opencode github install
运行指定事件

opencode github run --event "issue_comment.created"
使用指定 Token

opencode github run --token githubpatxxxxx

`opencode pr`

拉取并检出 GitHub PR 分支，然后启动 OpenCode。

opencode pr

参数：

参数	说明
`number`	PR 编号

示例：

检出 PR #42 并启动

opencode pr 42

调试工具

`opencode debug`

提供多种调试和排错工具。

opencode debug

#### 子命令

##### debug config

显示已解析的配置。

opencode debug config

##### debug paths

显示全局路径（数据、配置、缓存、状态目录）。

opencode debug paths

##### debug skill

列出所有可用技能（Skills）。

opencode debug skill

##### debug scrap

列出所有已知项目。

opencode debug scrap

##### debug agent

显示指定 Agent 的配置详情。

opencode debug agent

##### debug wait

无限等待（用于调试场景）。

opencode debug wait

#### debug lsp — LSP 调试

opencode debug lsp

子命令	说明
`diagnostics`	获取文件诊断信息
`symbols`	搜索工作区符号
`document-symbols`	获取文档中的符号

示例：

opencode debug lsp diagnostics src/index.ts
opencode debug lsp symbols "MyComponent"
opencode debug lsp document-symbols file:///path/to/file.ts

#### debug rg — ripgrep 调试

opencode debug rg

子命令	说明
`tree`	使用 ripgrep 显示文件树
`files`	使用 ripgrep 列出文件
`search`	使用 ripgrep 搜索文件内容

示例：

opencode debug rg tree
opencode debug rg files
opencode debug rg search "TODO"

#### debug file — 文件系统调试

opencode debug file

子命令	说明
`read`	以 JSON 格式读取文件内容
`status`	显示文件状态信息
`list`	列出目录中的文件
`search`	按查询搜索文件
`tree [dir]`	显示目录树

示例：

opencode debug file read src/main.ts
opencode debug file status
opencode debug file list .
opencode debug file search "config"
opencode debug file tree src/

#### debug snapshot — 快照调试

opencode debug snapshot

子命令	说明
`track`	跟踪当前快照状态
`patch`	显示指定快照哈希的补丁
`diff`	显示指定快照哈希的差异

示例：

opencode debug snapshot track
opencode debug snapshot diff abc123
opencode debug snapshot patch abc123

数据库工具

`opencode db`

数据库操作工具（底层使用 SQLite）。

opencode db [query]

#### 子命令

##### 默认（交互模式或执行查询）

不传参数进入 SQLite 交互 shell，传入 SQL 则直接执行。

交互模式

opencode db
执行查询

opencode db "SELECT * FROM sessions LIMIT 10"

选项	说明
`--format`	tsv>	输出格式，默认 `tsv`

##### db path

打印数据库文件路径。

opencode db path

##### db migrate

将 JSON 数据迁移到 SQLite（与现有数据合并）。

opencode db migrate

Shell 补全

`opencode completion`

生成 Shell 自动补全脚本。

opencode completion

安装方式：

Bash

opencode completion >> ~/.bashrc
source ~/.bashrc
Zsh

opencode completion >> ~/.zshrc
source ~/.zshrc
macOS (Zsh) — 也可写入 zprofile

opencode completion >> ~/.zprofile
source ~/.zprofile
Fish

opencode completion >> ~/.config/fish/completions/opencode.fish

系统维护

`opencode upgrade [target]`

升级 OpenCode 到最新版本或指定版本。

opencode upgrade [target]

参数	说明
`target`	目标版本，如 `1.3.15` 或 `v1.3.15`（可选）

选项	说明
`-m, --method`	安装方式：`curl` / `npm` / `pnpm` / `bun` / `brew` / `choco` / `scoop`

示例：

升级到最新版

opencode upgrade
升级到指定版本

opencode upgrade v1.3.14
指定安装方式

opencode upgrade -m brew

`opencode uninstall`

卸载 OpenCode 并移除相关文件。

opencode uninstall

选项	说明
`-c, --keep-config`	保留配置文件
`-d, --keep-data`	保留会话数据和快照
`--dry-run`	预览将被删除的文件，不实际删除
`-f, --force`	跳过确认提示

示例：

预览将被删除的内容

opencode uninstall --dry-run
卸载但保留配置和数据

opencode uninstall --keep-config --keep-data
强制卸载不确认

opencode uninstall -f

文件路径说明

通过 opencode debug paths 可以查看所有路径：

路径类型	默认路径	说明
`home`	`~`	用户主目录
`data`	`~/.local/share/opencode`	数据目录（会话、快照等）
`bin`	`~/.cache/opencode/bin`	二进制缓存
`log`	`~/.local/share/opencode/log`	日志目录
`cache`	`~/.cache/opencode`	缓存目录
`config`	`~/.config/opencode`	配置文件目录
`state`	`~/.local/state/opencode`	状态文件目录

配置文件

OpenCode 的配置文件位于 ~/.config/opencode/ 目录下。可以使用 opencode debug config 命令查看完整的已解析配置。

常用配置方式：

1. 全局配置：~/.config/opencode/config.json 或 ~/.config/opencode/config.toml

2. 项目配置：项目根目录下的 .opencode 目录

3. 环境变量：如 OPENCODESERVERPASSWORD 等

本手册基于 OpenCode v1.3.15 生成，命令和选项可能随版本更新而变化。使用 opencode --help 查看最新信息。

OpenCode CLI 参考手册

概述

快速开始

在当前目录启动 TUI 交互界面

在指定项目目录启动

直接运行一条命令（非交互模式）

继续上一次的会话

查看版本

全局选项

网络选项（serve/web/attach 等共享）

核心命令

opencode（启动 TUI）

使用特定模型启动

继续上次会话

Fork 上次会话继续

在指定目录启动

opencode run [message..]

简单执行

附加文件

JSON 输出（适合管道处理）

使用特定模型和推理强度

附加文件并设置标题

附加到远程服务器执行

opencode serve

启动服务，监听 8080 端口

允许局域网访问

启用 mDNS 发现

opencode web

启动 Web 界面

局域网访问 Web 界面

opencode attach

连接本地服务器

带密码连接远程服务器

会话管理

opencode session

列出最近 10 个会话

JSON 格式输出

opencode export [sessionID]

opencode import

opencode stats

最近 7 天统计

按项目过滤

显示模型统计

只显示前 5 个工具

模型与提供商

opencode models [provider]

列出所有模型

列出 anthropic 的模型

详细模式

刷新缓存

opencode providers（别名：auth）

交互式登录

直接登录指定提供商

指定登录方式

Agent 管理

opencode agent

交互式创建

指定参数创建

使用特定模型

MCP 服务器管理

opencode mcp

ACP 服务器

opencode acp

启动 ACP 服务器

指定工作目录

插件管理

opencode plugin （别名：plug）

安装插件

全局安装

强制替换

GitHub 集成

opencode github

安装 GitHub Agent

运行指定事件

使用指定 Token

opencode pr

检出 PR #42 并启动

调试工具

opencode debug

数据库工具

`opencode`（启动 TUI）

`opencode run [message..]`

`opencode serve`

`opencode web`

`opencode attach`

`opencode session`

`opencode export [sessionID]`

`opencode import`

`opencode stats`

`opencode models [provider]`

`opencode providers`（别名：`auth`）

`opencode agent`

`opencode mcp`

`opencode acp`

`opencode plugin` （别名：`plug`）

`opencode github`

`opencode pr`

`opencode debug`

`opencode db`

`opencode completion`

`opencode upgrade [target]`

`opencode uninstall`