Codex 广域网远程共享指南：macOS 服务端 + Nginx + SSL（wss 方案）

本文提供通过 Nginx 做 TLS 终止代理，实现公网使用 wss:// 安全访问 Codex App Server 的方案。适合需要从外网（广域网）远程开发共享的场景。

注意：公网暴露服务请务必使用强 token 认证，并考虑防火墙、端口限制等安全措施。

一、服务端配置（macOS）

1. 安装并启动 Nginx

# 安装 Nginx
brew install nginx

# 启动 Nginx（开机自启动推荐）
brew services start nginx

Nginx 默认配置文件路径：/usr/local/etc/nginx/nginx.conf（或 /opt/homebrew/etc/nginx/nginx.conf，视 brew 安装路径而定）。

2. 配置 Codex App Server（仅监听本地）

# 生成 token（如果还没有）
mkdir -p ~/.codex
openssl rand -hex 32 > ~/.codex/ws-token.txt
chmod 600 ~/.codex/ws-token.txt

# 启动 app-server（只监听本地）
codex app-server \
  --listen ws://127.0.0.1:8899 \
  --ws-auth capability-token \
  --ws-token-file "$HOME/.codex/ws-token.txt"

建议使用 tmux 或 brew services 将其后台运行。

3. 配置 Nginx 反向代理（wss）

编辑 Nginx 配置（推荐新建站点配置文件）：

sudo mkdir -p /usr/local/etc/nginx/servers
# 编辑配置文件，例如：
sudo nano /usr/local/etc/nginx/servers/codex.conf

推荐配置内容（使用域名方式，更推荐）：

server {
    listen 443 ssl;
    server_name codex.yourdomain.com;     # ← 改成你的域名

    # SSL 证书配置（推荐使用 Let's Encrypt）
    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    # WebSocket 代理核心配置
    location / {
        proxy_pass http://127.0.0.1:8899;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
    }
}

如果暂时没有域名，想直接用 IP（不推荐长期使用）：

把 server_name 改成你的公网 IP，并相应调整证书。

4. 重载 Nginx 配置

nginx -t                     # 测试配置是否正确
brew services restart nginx  # 重启 Nginx

---

二、客户端配置

客户端无论在什么网络（公网或局域网），均使用 wss:// 连接。

1. macOS / Ubuntu / Linux 客户端

# 设置 token 对应的环境变量
export CODEX_REMOTE_TOKEN=$(cat ~/.codex/ws-token.txt) 

# 启动 Codex
codex --remote wss://codex.yourdomain.com \
      --remote-auth-token-env CODEX_REMOTE_TOKEN

2. Windows 客户端（PowerShell）

# 设置 token 对应的环境变量
$env:CODEX_REMOTE_TOKEN = (Get-Content -Raw "$env:USERPROFILE\.codex\ws-token.txt").Trim()

# 启动 Codex
codex --remote wss://codex.yourdomain.com --remote-auth-token-env CODEX_REMOTE_TOKEN

---

推荐优化与注意事项

• 证书推荐：使用 Certbot + Let’s Encrypt 免费获取正规证书，比自签名证书更友好。

• 域名解析：将域名 A 记录指向你的公网 IP。

• 防火墙：在路由器或云服务器上放行 443 端口（HTTPS）。

• 安全性：定期更换 ws-token.txt，避免长期使用弱 token。

• 调试命令（客户端遇到问题时使用）：

  RUST_LOG=debug CODEX_REMOTE_TOKEN=... codex --remote wss://...

• 常见问题：

  • 自签名证书可能导致客户端证书验证失败（需导入信任）。
  • WebSocket 升级失败通常是 Nginx 的 proxy_set_header Upgrade 和 Connection 配置错误。