跳到主要内容

WSL + OpenCode 环境说明书

1. 基础系统​

  • OS: Windows 10 Pro
  • WSL: WSL2
  • Linux 发行版: Ubuntu 22.04 LTS
  • 用户: ollama

2. WSL 安装与进入​

安装 Ubuntu​

wsl --install -d Ubuntu-22.04

下载大小约 500-700MB，安装后占用约 1.2-1.6GB

进入 WSL​

wsl -d Ubuntu-22.04 -u ollama

查看已安装发行版​

wsl -l -v

3. Node / 包管理​

  • Node.js: v20.x（Linux 原生安装）
  • Corepack: 已启用
  • pnpm: Corepack 管理（pnpm@latest）
  • PNPM_HOME: ~/.local/share/pnpm
  • PATH 已包含 PNPM_HOME

Node 安装命令​

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

pnpm 启用​

sudo corepack enable
sudo corepack prepare pnpm@latest --activate
pnpm setup
source ~/.bashrc

4. OpenCode 安装​

推荐方式（官方二进制）​

curl -fsSL https://opencode.ai/install | bash
source ~/.bashrc

验证​

source ~/.bashrc
which opencode   # 应为 ~/.opencode/bin/opencode 或 /usr/local/bin/opencode
opencode --version
实际安装位置

使用官方安装脚本安装时，opencode 默认安装在 ~/.opencode/bin/opencode，且已自动添加到 ~/.bashrc 的 PATH 中。

5. OpenCode Server​

  • 文档: windows-wsl
  • 启动命令: opencode serve --port 4096 --hostname 0.0.0.0
注意

参数必须分开传递：--port 和 --hostname 是独立的参数，不能合并。

  • 用途: 提供 Desktop / Web Client 远程接入
  • 访问地址: http://0.0.0.0:4096（在同一网络中可从其他设备访问）

5.1 oh-my-opencode 安装配置​

安装 oh-my-opencode​

# 全局安装（需要 root）
sudo npm install -g oh-my-opencode

配置复制（如已有配置）​

从 Windows 复制配置到 WSL：

# 复制 opencode 配置
cp /mnt/c/Users/YOUR_WINDOWS_USERNAME/.config/opencode/opencode.json ~/.config/opencode/
cp /mnt/c/Users/YOUR_WINDOWS_USERNAME/.config/opencode/oh-my-opencode.json ~/.config/opencode/

# 复制插件（如有）
cp -r /mnt/c/Users/YOUR_WINDOWS_USERNAME/.config/opencode/plugins ~/.config/opencode/

# 设置权限
chown -R ollama:ollama ~/.config/opencode
注意事项
  • Windows 配置文件中的绝对路径（如 E:\project\）需要手动改为 WSL 路径（如 /mnt/e/project/）
  • MCP 配置中的 Windows 批处理文件路径需要改为 WSL 的 shell 脚本路径

6. OpenCode 使用模式对比​

模式上下文管理Token消耗适合场景
Desktop会话历史累积较高决策/澄清需求
Desktop + WSL工程驱动中等重度改动/调试
CLI独立调用最低批量/原子patch
TUI可视化CLI低高频执行

工作流建议​

  • Desktop: 用于"想清楚要改什么"
  • CLI/TUI: 用于"把代码改对"
  • 每次调用只干一件事，用 Snapshot 替代历史

7. Token 优化策略​

核心原则​

  1. 减少上下文：用 Task Snapshot 替代历史
  2. 减少回合：子代理一次性调用
  3. 结构化输出：禁止解释，只给 diff

低 Token Prompt 模板​

Task Snapshot:
- Project: Spring Boot 2.7
- Goal: [明确目标]
- Constraints: [约束条件]

Output:
- Only unified diff
- No explanation

8. Python 环境​

sudo apt install -y python3 python3-pip python3-venv
pip3 install --user virtualenv ipython black isort pylint mypy
# 使用 tee 添加环境变量（无需进入编辑器）
echo 'export PATH="$HOME/.local/bin:$PATH"' | tee -a ~/.bashrc
source ~/.bashrc

9. Java 环境​

sudo apt install -y openjdk-17-jdk maven
  • JAVA_HOME: 已配置
  • 用途: OpenCode 代码理解与执行

10. 辅助工具​

sudo apt install -y git build-essential tree ripgrep fd-find curl wget unzip

11. tmux 终端复用​

安装​

sudo apt install -y tmux

常用命令​

# 创建新会话
tmux new -s dev

# 列出会话
tmux ls

# 附加到会话
tmux attach -t dev

# 分离会话（在 tmux 内）
Ctrl+b d

# 关闭窗口（在 tmux 内）
Ctrl+d

# 杀死会话
tmux kill-session -t dev

窗口操作（在 tmux 内）​

快捷键功能
Ctrl+b c新建窗口
Ctrl+b n下一个窗口
Ctrl+b p上一个窗口
Ctrl+b %垂直分屏
Ctrl+b "水平分屏
Ctrl+b 方向键切换面板

设置容器滚动​

写入 tmux 配置文件：

# 方法一：直接追加配置
echo 'set -g mouse on' >> ~/.tmux.conf
echo 'bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "clip.exe"' >> ~/.tmux.conf

# 方法二：使用 tee（需要 root 权限）
sudo tee -a ~/.tmux.conf << 'EOF'
set -g mouse on
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "clip.exe"
EOF

配合 OpenCode 使用​

# 方法一：在 tmux 中启动 server（推荐）
tmux new -s opencode -d 'opencode serve --port 4096 --hostname 0.0.0.0'

# 查看 server 状态
tmux capture-pane -t opencode -p

# 附加查看
tmux attach -t opencode

# 分离会话
Ctrl+b d