opencode

OpenCode CLI 和 Web 服务指南

当用户询问如何将 opencode 用作工具时，加载此技能 — 包括 CLI 命令、非交互模式、Web 服务、会话、模型或任何 opencode <command> 用法。

安装

curl -fsSL https://opencode.ai/install | bash
# Or: npm install -g opencode-ai
# Or: brew install anomalyco/tap/opencode

全局选项

所有命令都支持：--help、--version、--print-logs、--log-level <DEBUG|INFO|WARN|ERROR>、--pure（禁用插件）

TUI/服务模式的全局标志：-m <provider/model>、-c / --continue（恢复上一个会话）、-s <id> / --session（恢复指定会话）、--fork（恢复时复制会话）、--agent <name>、--prompt <text>

非交互模式：opencode run

运行 opencode 而不启动 TUI。适用于脚本、CI/CD 和自动化。

# Basic usage
opencode run "Explain async/await in TypeScript"

# With specific model
opencode run -m anthropic/claude-sonnet-4-20250514 "Refactor this function"

# Attach files to the prompt
opencode run -f src/index.ts "Explain this file"

# Continue last session
opencode run -c "Now add error handling"

# Fork a session (creates copy)
opencode run -c --fork "Try a different approach"

# Output raw JSON events (for piping/processing)
opencode run --format json "List all TODO comments"

# Share the session after completion
opencode run --share "Generate a README"

run 标志

标志	说明
-m, --model <provider/model>	要使用的模型
--agent <name>	要使用的 Agent
-c, --continue	继续上一个会话
-s, --session <id>	恢复指定会话
--fork	继续前分叉会话
--share	完成后分享会话
--format <default|json>	输出格式（默认：格式化）
-f, --file <path>	将文件附加到消息（可重复使用）
--title <text>	会话标题
--attach <url>	连接到正在运行的服务（例如，http://localhost:4096）
-p, --password <pw>	基本身份验证密码（环境变量：OPENCODE_SERVER_PASSWORD）
-u, --username <user>	基本身份验证用户名（默认：opencode）
--dir <path>	工作目录
--port <num>	本地服务端口（省略时随机分配）
--variant <level>	模型推理力度（例如，high、max、minimal）
--thinking	显示思考块
-i, --interactive	以直接交互式分屏页脚模式运行
--dangerously-skip-permissions	自动批准未被拒绝的权限
--command <cmd>	运行斜杠命令，而不是发送消息

将 run 连接到服务

连接到正在运行的服务，以避免 MCP 冷启动：

# Terminal 1: start server
opencode serve

# Terminal 2: run commands against it
opencode run --attach http://localhost:4096 "Fix the lint errors"

无头服务：opencode serve

启动不带 TUI 的无头服务。其他客户端（run --attach、web、attach）可连接到该服务。

# Start with defaults (random port, localhost)
opencode serve

# Specify port
opencode serve --port 4096

# Expose on all interfaces
opencode serve --hostname 0.0.0.0 --port 4096

# Enable mDNS discovery
opencode serve --mdns --port 4096

# Allow CORS for specific origins
opencode serve --cors http://localhost:5173 --port 4096

serve 标志

标志	默认值	说明
--port <num>	0（随机）	监听端口
--hostname <addr>	127.0.0.1	绑定地址
--mdns	false	启用 mDNS 服务发现
--mdns-domain <name>	opencode.local	自定义 mDNS 域名
--cors <origin>	[]	其他 CORS 域（可重复使用）

服务 REST API

服务会在绑定地址上开放 REST API。主要端点：

• GET /app — 应用详情
• POST /app/init — 初始化应用
• GET /config/providers — 列出已配置的提供方
• GET /mode — 可用模式
• GET /session — 列出会话
• POST /session/init — 初始化会话
• POST /session/summarize — 总结会话
• POST /session/abort — 中止正在运行的会话
• DELETE /session/delete — 删除会话
• GET /file/read?path=<path> — 读取文件内容
• GET /file/status — 已修改文件的状态
• GET /find/file — 搜索文件
• GET /find/symbol — 搜索符号
• GET /find — 搜索文本

身份验证：使用 -u / -p 标志，或 OPENCODE_SERVER_USERNAME / OPENCODE_SERVER_PASSWORD 环境变量。

Web 界面：opencode web

启动服务并在浏览器中打开 Web UI。标志与 serve 相同。

opencode web
opencode web --port 4096 --hostname 0.0.0.0
opencode web --cors http://localhost:5173

你可以将 TUI 连接到同一个 Web 服务：

# Terminal 1
opencode web --port 4096

# Terminal 2
opencode attach http://localhost:4096

连接到服务：opencode attach

将 TUI 连接到正在运行的 serve 或 web 实例。

opencode attach http://localhost:4096

# With session resume
opencode attach http://localhost:4096 -c

# With specific session
opencode attach http://localhost:4096 -s <session-id>

# With auth
opencode attach http://localhost:4096 -u opencode -p secretpassword

标志	说明
--dir <path>	工作目录
-c, --continue	继续上一个会话
-s, --session <id>	恢复指定会话
--fork	恢复时分叉会话
-p, --password <pw>	身份验证密码
-u, --username <user>	身份验证用户名

ACP 服务：opencode acp

启动 Agent Client Protocol 服务（标志与 serve 相同，另加 --cwd）。

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

会话管理

# List sessions
opencode session list
opencode session list -n 10 --format json

# Delete a session
opencode session delete <session-id>

# Export session as JSON
opencode export <session-id>
opencode export <session-id> --sanitize  # redact sensitive data

# Import session from file or share URL
opencode import session.json
opencode import https://opencode.ai/share/abc123

模型与提供商

# List all available models
opencode models

# Filter by provider
opencode models anthropic

# Verbose (includes cost info)
opencode models --verbose

# Refresh model cache
opencode models --refresh

# Manage providers
opencode providers list
opencode providers login
opencode providers logout

PR 工作流：opencode pr

获取 GitHub PR 分支、检出并打开 opencode：

opencode pr 42

GitHub Agent

opencode github install        # Install GitHub agent
opencode github run            # Run the agent
opencode github run --event '{"type":"issues","action":"opened",...}'
opencode github run --token github_pat_...

MCP 服务

opencode mcp add               # Add an MCP server
opencode mcp list              # List servers and status
opencode mcp auth [name]       # Authenticate OAuth MCP server
opencode mcp logout [name]     # Remove OAuth credentials
opencode mcp debug <name>      # Debug OAuth connection

Agent 管理

# List agents
opencode agent list

# Create agent
opencode agent create --description "Review code" --mode subagent --tools "read,grep,glob"

# Create with model
opencode agent create -m anthropic/claude-sonnet-4-20250514 --mode primary

# Create at specific path
opencode agent create --path .opencode/agents/reviewer.md

create 标志	描述
--path <dir>	输出目录
--description <text>	Agent 的功能
--mode <all|primary|subagent>	Agent 模式
--tools <list>	以逗号分隔的权限：bash,read,edit,glob,grep,webfetch,task,todowrite,websearch,lsp,skill
-m <model>	采用 provider/model 格式的模型

统计与调试

# Token usage and costs
opencode stats
opencode stats --days 7 --models --project myproject
opencode stats --tools 10

# Debug tools
opencode debug config           # Show resolved config
opencode debug paths            # Global paths (data, config, cache, state)
opencode debug info             # Debug information
opencode debug skill            # List available skills
opencode debug agent <name>     # Show agent config details
opencode debug startup          # Startup timing
opencode debug lsp              # LSP debugging
opencode debug rg               # Ripgrep debugging
opencode debug file             # File system debugging
opencode debug scrap            # List all known projects
opencode debug snapshot         # Snapshot debugging

数据库工具

opencode db                     # Interactive SQLite shell
opencode db "SELECT * FROM session LIMIT 5"  # Run query
opencode db path                # Print database path
opencode db migrate             # Migrate JSON data to SQLite
opencode db --format json "SELECT count(*) FROM message"

插件与扩展

# Install plugin
opencode plugin <npm-module>
opencode plugin <npm-module> --global
opencode plugin <npm-module> --force  # Replace existing version

升级与卸载

# Upgrade
opencode upgrade
opencode upgrade 0.1.48
opencode upgrade --method curl

# Uninstall
opencode uninstall --dry-run       # Preview what gets removed
opencode uninstall -c -d -f        # Remove but keep config and data

Shell 补全

opencode completion  # Generate completion script (bash/zsh/fish)

配置

配置文件

• 项目：.opencode/opencode.json
• 全局：~/.config/opencode/config.json

服务端配置（opencode.json）

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

环境变量

变量	描述
OPENCODE_AUTO_SHARE	自动分享会话
OPENCODE_CONFIG	自定义配置路径
OPENCODE_DISABLE_CLAUDE_CODE	禁用 Claude Code 兼容性
OPENCODE_SERVER_PASSWORD	默认身份验证密码
OPENCODE_SERVER_USERNAME	默认身份验证用户名

TUI 快速参考

以交互方式使用 opencode 时（默认，不带子命令）：

按键/命令	操作
Tab	切换构建/规划模式
Ctrl+X	快捷键引导键
/help	显示帮助
/init	创建 AGENTS.md
/connect	配置 AI 提供商
/new	新建会话
/sessions	列出会话
/models	切换模型
/undo / /redo	基于 Git 的撤销/重做
/share / /unshare	分享/取消分享会话
/compact	压缩上下文
/details	显示详情
/thinking	切换思考
/export	导出会话
@file	模糊文件引用
!command	执行 Shell 命令