Logo
热心市民王先生

实施指南

技术研究 OpenCode 实施指南

OpenCode Server 的配置、部署与使用指南

基础配置

本地开发场景

# 启动本地 Server
opencode serve

# 自定义端口
opencode serve --port 8080

# 查看健康状态
curl http://localhost:4096/global/health
# 响应: {"healthy":true,"version":"x.x.x"}

远程访问配置

# 绑定所有网络接口（允许远程访问）
opencode serve --hostname 0.0.0.0 --port 4096

# 配置 CORS（允许特定源访问）
opencode serve --cors http://localhost:5173 --cors https://app.example.com

认证配置

# 设置密码保护
OPENCODE_SERVER_PASSWORD=your-secure-password opencode serve

# 自定义用户名
OPENCODE_SERVER_USERNAME=admin OPENCODE_SERVER_PASSWORD=secret opencode serve

# 客户端访问（带认证）
curl -u opencode:your-secure-password http://localhost:4096/session

典型使用场景

场景一：远程开发

需求：代码在远程服务器，开发者从本地机器访问。

配置步骤：

# 步骤 1: 在远程服务器启动 Server
ssh user@remote-server
cd /path/to/project
opencode serve --hostname 0.0.0.0 --port 4096

# 步骤 2: 本地 TUI 连接
opencode attach http://remote-server:4096

# 或者通过本地 Web 界面访问
# 浏览器打开: http://remote-server:4096

注意事项：

  • 确保防火墙开放对应端口
  • 生产环境务必设置密码认证
  • 考虑使用 VPN 或 SSH 隧道增强安全性

场景二：企业共享服务

需求：团队共享一个 OpenCode 实例，统一管理 API Key。

架构示意：

                    ┌─────────────────┐
                    │  企业内部网络    │
                    │                 │
┌──────────┐        │  ┌───────────┐  │
│ 开发者 A  │◄──────┼──┤           │  │
└──────────┘        │  │           │  │
                    │  │  OpenCode │  │
┌──────────┐        │  │  Server   │  │
│ 开发者 B  │◄──────┼──┤           │  │
└──────────┘        │  │           │  │
                    │  └─────┬─────┘  │
┌──────────┐        │        │        │
│ 开发者 C  │◄──────┼────────┘        │
└──────────┘        │                 │
                    └─────────────────┘

配置步骤：

# 服务器配置
export OPENCODE_SERVER_PASSWORD=shared-team-password
export OPENCODE_SERVER_USERNAME=team

opencode serve --hostname 0.0.0.0 --port 4096 \
  --cors https://internal-app.company.com

# 团队成员连接
opencode attach http://opencode.internal:4096

场景三：自动化脚本

需求：通过脚本批量执行代码审查或文档生成。

示例脚本：

#!/bin/bash
# auto-review.sh - 自动代码审查脚本

SERVER_URL="http://localhost:4096"

# 创建会话
SESSION=$(curl -s -X POST "$SERVER_URL/session" \
  -H "Content-Type: application/json" \
  -d '{"title": "Auto Code Review"}')
SESSION_ID=$(echo $SESSION | jq -r '.id')

# 发送审查请求
curl -X POST "$SERVER_URL/session/$SESSION_ID/message" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [{
      "type": "text",
      "text": "审查当前目录的代码，指出潜在的 bug 和改进建议"
    }]
  }'

# 等待响应完成（轮询状态）
while true; do
  STATUS=$(curl -s "$SERVER_URL/session/$SESSION_ID" | jq -r '.status')
  if [ "$STATUS" != "running" ]; then
    break
  fi
  sleep 2
done

# 获取消息内容
curl -s "$SERVER_URL/session/$SESSION_ID/message" | jq '.[-1].parts[].text'

场景四：IDE 集成

需求：在 IDE 中使用 OpenCode，无需切换到终端。

Zed 编辑器配置：

// ~/.config/zed/settings.json
{
  "agent_servers": {
    "OpenCode": {
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

VSCode 扩展：OpenCode 提供官方 IDE 插件，通过 Server API 实现深度集成。

最佳实践

安全建议

场景建议
本地开发默认配置即可（仅监听 localhost）
局域网访问设置强密码，限制 CORS
公网访问强烈建议使用反向代理 + HTTPS + 认证
企业部署配合 VPN/内网隔离，统一管理凭证

性能优化

# 复用 Server，避免 MCP 冷启动
# 1. 保持 Server 长期运行
opencode serve --port 4096

# 2. 后续命令附加到已有 Server
opencode run --attach http://localhost:4096 "任务描述"

# 而非每次重新启动
opencode run "任务描述"  # 每次都需要初始化 MCP

日志与监控

# 启用详细日志
opencode serve --log-level DEBUG

# 监控健康状态
watch -n 5 'curl -s http://localhost:4096/global/health'

# 查看活跃会话
curl -s http://localhost:4096/session | jq '.[] | {id, title, status}'

参考资料