11 KiB
Advanced Configuration Examples
⚠️ CRITICAL: Always Use codex exec
ALL commands in this document use codex exec - this is mandatory in Claude Code.
❌ NEVER: codex -m ... or codex --flag ... (will fail with "stdout is not a terminal")
✅ ALWAYS: codex exec -m ... or codex exec --flag ... (correct non-interactive mode)
Claude Code's bash environment is non-terminal. Plain codex commands will NOT work.
Custom Model Selection
Example 1: Force GPT-5 for Code Task
User Request: "Use GPT-5.1 (not Codex) to review this code for architecture issues"
Skill Executes:
codex exec -m gpt-5.1 -s read-only \
-c model_reasoning_effort=high \
"Review this code for architecture issues"
Why: Even though it's code-related, user wants architectural review (high-reasoning) rather than code editing.
Example 2: Explicit GPT-5-Codex for Implementation
User Request: "Use GPT-5.1-Codex to implement the authentication module"
Skill Executes:
codex exec -m gpt-5.1-codex -s workspace-write \
-c model_reasoning_effort=high \
"Implement the authentication module"
Why: Implementation requires file writing and code generation (gpt-5.1-codex specialty).
Workspace Write Permission
Example 3: Allow File Modifications
User Request: "Have Codex refactor this codebase (allow file writing)"
Skill Executes:
codex exec -m gpt-5.1-codex -s workspace-write \
-c model_reasoning_effort=high \
"Refactor this codebase for better maintainability"
Permission: workspace-write allows Codex to modify files directly.
⚠️ Warning: Only use workspace-write when you trust the operation and want file modifications.
Example 4: Read-Only Code Review
User Request: "Review this code for security vulnerabilities (read-only)"
Skill Executes:
codex exec -m gpt-5.1 -s read-only \
-c model_reasoning_effort=high \
"Review this code for security vulnerabilities"
Permission: read-only prevents file modifications - safer for review tasks.
Web Search Integration
Example 5: Research Latest Patterns
User Request: "Research latest Python async patterns and implement them (enable web search)"
Skill Executes:
codex exec -m gpt-5.1-codex -s workspace-write \
-c model_reasoning_effort=high \
--search \
"Research latest Python async patterns and implement them"
Feature: --search flag enables web search for up-to-date information.
Example 6: Security Best Practices Research
User Request: "Use web search to find latest JWT security best practices, then review this auth code"
Skill Executes:
codex exec -m gpt-5.1 -s read-only \
-c model_reasoning_effort=high \
--search \
"Find latest JWT security best practices and review this auth code"
Reasoning Effort Control
Example 7: Maximum Reasoning for Complex Algorithm
User Request: "Design an optimal algorithm for distributed consensus (maximum reasoning)"
Skill Executes:
codex exec -m gpt-5.1 -s read-only \
-c model_reasoning_effort=high \
"Design an optimal algorithm for distributed consensus"
Default: Already uses high reasoning effort.
Example 8: Quick Code Review (Lower Reasoning)
User Request: "Quick syntax check on this code (low reasoning)"
Skill Executes:
codex exec -m gpt-5.1 -s read-only \
-c model_reasoning_effort=low \
"Quick syntax check on this code"
Use Case: Fast turnaround for simple tasks.
Verbosity Control
Example 9: Detailed Explanation
User Request: "Explain this algorithm in detail (high verbosity)"
Skill Executes:
codex exec -m gpt-5.1 -s read-only \
-c model_reasoning_effort=high \
-c model_verbosity=high \
"Explain this algorithm in detail"
Output: Comprehensive, detailed explanation.
Example 10: Concise Summary
User Request: "Briefly review this code (low verbosity)"
Skill Executes:
codex exec -m gpt-5.1 -s read-only \
-c model_reasoning_effort=high \
-c model_verbosity=low \
"Review this code"
Output: Concise, focused feedback.
Working Directory Control
Example 11: Specific Project Directory
User Request: "Work in the backend directory and review the API code"
Skill Executes:
codex exec -m gpt-5.1 -s read-only \
-c model_reasoning_effort=high \
-C ./backend \
"Review the API code"
Feature: -C flag sets working directory for Codex.
Approval Policy
Example 12: Request Approval for Shell Commands
User Request: "Implement the build script (ask before running commands)"
Skill Executes:
codex exec -m gpt-5.1-codex -s workspace-write \
-c model_reasoning_effort=high \
-a on-request \
"Implement the build script"
Safety: -a on-request requires approval before executing shell commands.
Combined Advanced Configuration
Example 13: Full-Featured Request
User Request: "Use web search to find latest security practices, review my auth module in detail with high reasoning, allow file fixes if needed (ask for approval)"
Skill Executes:
codex exec -m gpt-5.1-codex -s workspace-write \
-c model_reasoning_effort=high \
-c model_verbosity=high \
-a on-request \
--search \
"Find latest security practices, review my auth module in detail, and fix issues"
Features:
- Web search enabled (
--search) - High reasoning (
model_reasoning_effort=high) - Detailed output (
model_verbosity=high) - File writing allowed (
workspace-write) - Requires approval for commands (
-a on-request)
Decision Tree: When to Use GPT-5.1 vs GPT-5.1-Codex
Use GPT-5.1 For:
┌─────────────────────────────────────┐
│ Architecture & Design │
│ - System architecture │
│ - API design │
│ - Data structure design │
│ - Algorithm analysis │
├─────────────────────────────────────┤
│ Analysis & Review │
│ - Code reviews │
│ - Security audits │
│ - Performance analysis │
│ - Quality assessment │
├─────────────────────────────────────┤
│ Explanation & Learning │
│ - Concept explanations │
│ - Documentation review │
│ - Trade-off analysis │
│ - Best practices guidance │
└─────────────────────────────────────┘
Use GPT-5.1-Codex For:
┌─────────────────────────────────────┐
│ Code Editing │
│ - Modify existing files │
│ - Implement features │
│ - Refactoring │
│ - Bug fixes │
├─────────────────────────────────────┤
│ Code Generation │
│ - Write new code │
│ - Generate boilerplate │
│ - Create test files │
│ - Scaffold projects │
├─────────────────────────────────────┤
│ File Operations │
│ - Multi-file changes │
│ - Batch updates │
│ - Migration scripts │
│ - Build configurations │
└─────────────────────────────────────┘
Sandbox Mode Decision Matrix
| Task | Recommended Sandbox | Rationale |
|---|---|---|
| Code review | read-only |
No modifications needed |
| Architecture design | read-only |
Planning phase only |
| Security audit | read-only |
Analysis without changes |
| Implement feature | workspace-write |
Requires file modifications |
| Refactor code | workspace-write |
Must edit existing files |
| Generate new files | workspace-write |
Creates new files |
| Bug fix | workspace-write |
Edits source files |
Configuration Profiles
Create a Config Profile
You can create reusable configuration profiles in ~/.codex/config.toml:
[profiles.review]
model = "gpt-5.1"
sandbox = "read-only"
model_reasoning_effort = "high"
model_verbosity = "medium"
[profiles.implement]
model = "gpt-5.1-codex"
sandbox = "workspace-write"
model_reasoning_effort = "high"
approval_policy = "on-request"
Use Profile in Skill
User Request: "Use the review profile to analyze this code"
Skill Executes:
codex -p review "Analyze this code"
Result: Uses all settings from [profiles.review].
Best Practices
1. Match Model to Task Type
- Thinking/Design → GPT-5.1
- Doing/Coding → GPT-5.1-Codex
2. Use Safe Defaults, Override Intentionally
- Default to
read-onlyunless file writing is explicitly needed - Default to
highreasoning for complex tasks - Reduce reasoning effort only for simple, quick tasks
3. Combine Web Search with High Reasoning
For best results researching current practices:
codex exec -m gpt-5.1--search \
-c model_reasoning_effort=high \
"Research latest distributed systems patterns"
4. Request Approval for Risky Operations
Use -a on-request when:
- Working with production code
- Running shell commands
- Making broad changes
Common Patterns
Pattern 1: Research → Design → Implement
Phase 1 - Research (GPT-5.1 + web search):
codex exec -m gpt-5.1--search \
-c model_reasoning_effort=high \
"Research latest authentication patterns"
Phase 2 - Design (GPT-5.1 + high reasoning):
codex exec resume --last
# "Design the authentication system based on research"
Phase 3 - Implement (GPT-5.1-Codex + workspace-write):
codex exec -m gpt-5.1-codex -s workspace-write \
-c model_reasoning_effort=high \
"Implement the authentication system we designed"
Pattern 2: Review → Fix → Verify
Review (GPT-5.1 + read-only):
codex exec -m gpt-5.1 -s read-only \
"Review this code for security issues"
Fix (GPT-5.1-Codex + workspace-write):
codex exec resume --last
# "Fix the security issues identified"
Verify (GPT-5.1 + read-only):
codex exec resume --last
# "Verify the fixes are correct"
Next Steps
- Basic usage: See basic-usage.md
- Session continuation: See session-continuation.md
- Full documentation: See ../SKILL.md
- CLI reference: See ../resources/codex-help.md
- Config reference: See ../resources/codex-config.md