OpusClaw 使用文档

主题

Codex 相关问题 ​

高效使用 Codex 的几条经验 ​

核心建议 ​

  1. 任务划分 — 不要提交过笼统的需求,要拆分成模块化组件
  2. 掌控意识 — 拆分前先评估颗粒度,预估模型会改哪些文件
  3. 避免压缩 — 大约 60% 上下文就能解决多数任务,频繁压缩说明前期任务拆得不够细

Windows 下让 Codex 更顺手 ​

推荐 MCP 工具 ​

  • Serena — 编码代理工具包(语义检索 + 项目记忆)
  • Desktop-Commander — 文件操作

Serena 安装 ​

bash
pip install uv
git clone https://github.com/oraios/serena.git
cd serena
uv run serena start-mcp-server --context codex --transport streamable-http --port 9121

Desktop-Commander 安装 ​

bash
npx @wonderwhy-er/desktop-commander@latest setup

若报错,下载 rg.exe 放入 %userprofile%\.cargo\bin\。

config.toml(Windows) ​

编辑 %userprofile%\.codex\config.toml:

toml
model_provider = "opusclaw"
model = "gpt-5-codex"
model_reasoning_effort = "high"
network_access = "enabled"
disable_response_storage = true
windows_wsl_setup_acknowledged = true
model_verbosity = "high"

[model_providers.opusclaw]
name = "opusclaw"
base_url = "https://api.opusclaw.me/v1"
wire_api = "responses"
requires_openai_auth = true

[mcp_servers.desktop-commander]
type = "stdio"
command = "cmd"
args = ["/c", "npx", "-y", "@wonderwhy-er/desktop-commander@latest", "--no-onboarding"]

[mcp_servers.desktop-commander.env]
SystemRoot = 'C:\Windows'

[mcp_servers.Serena]
type = "http"
url = "http://127.0.0.1:9121/mcp"

AGENTS.md 全局工作指南示例 ​

放在 %userprofile%\.codex\AGENTS.md:

markdown
# Codex 全局工作指南

## 回答风格
- 必须中文
- 总结 / Plan / Task / 长内容用表格

## 工具使用
1. 文件与代码检索:用 serena mcp
2. 文件操作:
   - 优先用 apply_patch
   - apply_patch 出错才用 desktop-commander
   - 禁止用 cmd / powershell / python 操作文件

Codex 常用命令 ​

命令说明
/model选当前模型
/approvals设置审批规则
/review审查工作区变更
/resume选历史会话继续
/new新对话
/init在当前目录生成 AGENTS.md 模板
/compact总结对话以释放上下文
/undo撤销上一步
/diff当前 git diff(含未跟踪)
/mention把文件 / 目录加入上下文
/status会话配置 + token 使用
/mcp列出可用 MCP 工具
/exit退出

Windows 下乱码问题 ​

  1. Win+R 输入 intl.cpl
  2. "管理" → "更改系统区域设置"
  3. 勾选"使用 Unicode UTF-8"选项,确定,重启

VSCode Codex 插件设置最新模型 ​

  1. Win+R 输入 %userprofile%\.vscode\extensions
  2. 找 openai.chatgpt 开头的目录(取最新版本号)
  3. 进入 webview\assets
  4. 替换插件内置 js(让插件认识更新的模型 ID)
  5. 重启 VSCode

全局提示词配置 ​

通过 ~/.codex/AGENTS.md 配置(参考上文)。

开启内置网络搜索 ​

config.toml 加:

toml
[features]
web_search_request = true

容器 / 沙盒中网络问题 ​

把 MTU 改成 1500(Clash 客户端可改),通常能解决。

Connection failed 排查 ​

报错示例:Connection failed: error sending request for url (https://api.opusclaw.me/v1/responses)

  1. 检查本机网络,确保能访问 https://api.opusclaw.me
  2. 关闭代理工具(或确认代理不拦截 OpusClaw 域名)
  3. 终端用 codex 测试一次
  4. 仍未解决 → 联系客服

401 Unauthorized ​

报错:exceeded retry limit, last status: 401 Unauthorized

Windows 检查环境变量 ​

cmd
cmd /c "echo ================= OPENAI ENV CHECK ================= & ^
if defined OPENAI_API_KEY (echo OPENAI_API_KEY  = OK) else (echo OPENAI_API_KEY  = MISSING) & ^
if defined OPENAI_BASE_URL (echo OPENAI_BASE_URL = OK) else (echo OPENAI_BASE_URL = MISSING) & ^
echo ========================================================="

如果显示 OK 说明系统层有冲突环境变量,清掉:

cmd
cmd /c "setx OPENAI_API_KEY \"\" & setx OPENAI_BASE_URL \"\""

macOS 检查 ​

bash
echo "================= OPENAI ENV CHECK ================="
[ -z "$OPENAI_API_KEY" ] && echo "OPENAI_API_KEY  = MISSING" || echo "OPENAI_API_KEY  = OK"
[ -z "$OPENAI_BASE_URL" ] && echo "OPENAI_BASE_URL = MISSING" || echo "OPENAI_BASE_URL = OK"
echo "========================================================"

非 MISSING 时清掉:

bash
unset OPENAI_API_KEY OPENAI_BASE_URL

还要检查 ​

  • ~/.codex/auth.json 中 API Key 是否正确
  • ~/.codex/config.toml 的 base_url 是否为 https://api.opusclaw.me/v1

403 Forbidden ​

报错示例:unexpected status 403 Forbidden: {"error":{"message":"Usage not included in your plan"...}}

通常是上游通道限速 / 切换通道短暂失败:

  1. Ctrl+C 中断本次请求(VSCode 点停止)
  2. 重新发起对话
  3. 连续 3 次仍失败 → 联系客服

OpusClaw

© 2026 OpusClaw Team