OpenAI Codex Tools and Permissions Configuration

What You'll Learn

Master OpenAI Codex's permission system to control which tools OpenAI Codex can use and how they can be used, ensuring both productivity and security.

Prerequisites

• OpenAI Codex CLI installed
• Understanding of file paths and patterns
• Basic knowledge of JSON configuration

Steps

Step 1: Understand Configuration Hierarchy

OpenAI Codex checks permissions in this order (later overrides earlier):

1. Enterprise policies: /etc/codex-code/policies.json (Linux) or /Library/Application Support/OpenAI CodexCode/policies.json (macOS)
2. User settings: ~/.codex/settings.json
3. Project shared settings: .codex/settings.json
4. Project local settings: .codex/settings.local.json

Step 2: Create Basic Permission Configuration

Create .codex/settings.json in your project:

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(npm run:*)",
      "TodoRead",
      "TodoWrite"
    ]
  }
}

Step 3: Configure File-Specific Permissions

Use gitignore-style patterns to control file access:

{
  "permissions": {
    "allow": [
      "Read(src/**)",           // Read any file in src directory
      "Write(*.md)",            // Write only markdown files
      "Edit(src/**/*.js)",      // Edit only JS files in src
      "Read(~/.zshrc)",         // Read specific home file
      "Write(//tmp/**)"         // Write to absolute path
    ],
    "deny": [
      "Read(node_modules/**)",  // Deny reading node_modules
      "Write(package.json)"     // Prevent package.json changes
    ]
  }
}

Step 4: Configure Command Permissions

Control which shell commands OpenAI Codex can execute:

{
  "permissions": {
    "allow": [
      "Bash(npm run test)",      // Exact command match
      "Bash(npm run:*)",         // Prefix match with :*
      "Bash(git:*)",            // All git commands
      "Bash(ls:*)",             // All ls variations
      "Bash(echo:*)"            // All echo commands
    ],
    "deny": [
      "Bash(rm:*)",             // Prevent rm commands
      "Bash(sudo:*)",           // Prevent sudo usage
      "Bash(curl:*)"            // Prevent curl commands
    ]
  }
}

Step 5: Configure Advanced Tool Permissions

Set permissions for specialized tools:

{
  "permissions": {
    "allow": [
      "WebFetch",                           // Unrestricted web fetch
      "WebFetch(domain:docs.anthropic.com)", // Domain-restricted
      "WebSearch",                          // Web search capability
      "Task",                               // Allow sub-agents
      "Agent",                              // Allow search agents
      "NotebookRead",                       // Read Jupyter notebooks
      "NotebookEdit"                        // Edit Jupyter notebooks
    ]
  }
}

Example Usage

Development Environment Configuration

{
  "permissions": {
    "allow": [
      "Read",
      "Write(src/**)",
      "Edit(src/**)",
      "Bash(npm:*)",
      "Bash(yarn:*)",
      "Bash(pnpm:*)",
      "Bash(git:*)",
      "WebFetch",
      "TodoRead",
      "TodoWrite"
    ],
    "deny": [
      "Write(*.env)",
      "Read(*.pem)",
      "Bash(rm -rf:*)"
    ]
  }
}

Restrictive Production Configuration

{
  "permissions": {
    "allow": [
      "Read(src/**)",
      "Read(docs/**)",
      "Bash(npm run build)",
      "Bash(npm run test)",
      "TodoRead"
    ],
    "deny": [
      "Write",
      "Edit",
      "Bash(git push:*)",
      "WebFetch",
      "Task"
    ]
  }
}

Core Tools Reference

| Tool | Purpose | Permission Format | |------|---------|-------------------| | Bash | Execute shell commands | Bash(command) or Bash(prefix:*) | | Read | Read files | Read(pattern) or Read for all | | Write | Create/overwrite files | Write(pattern) or Write for all | | Edit | Modify existing files | Edit(pattern) or Edit for all | | MultiEdit | Batch file edits | MultiEdit | | Glob | Search for files | Glob | | Grep | Search file contents | Grep | | LS | List directories | LS | | WebFetch | Fetch web content | WebFetch or WebFetch(domain:example.com) | | WebSearch | Search the web | WebSearch | | TodoRead | View todo list | TodoRead | | TodoWrite | Manage todo list | TodoWrite | | Task | Launch sub-agents | Task |

Tips & Variations

Check Current Permissions

In an active OpenAI Codex session:

/allowed-tools

Headless Mode (Use with Caution)

Skip all permission checks:

codex --dangerously-skip-permissions

Warning: Not allowed when running as root user

Team Collaboration

• Commit .codex/settings.json to share team permissions
• Use .codex/settings.local.json for personal overrides
• Add settings.local.json to .gitignore

Pattern Matching Rules

• ** matches any number of directories
• * matches any file/folder name
• // prefix for absolute paths
• ~/ prefix for home directory paths

Troubleshooting

• Issue: Permission denied for a command Solution: Check exact command format and ensure it matches your allow rules

• Issue: Can't read/write certain files Solution: Verify file patterns match your intended paths

• Issue: Deny rules not working Solution: Deny rules take precedence - check for conflicting allow rules

• Issue: Settings not applying Solution: Check configuration hierarchy - local settings override global ones

Security Best Practices

1. Start Restrictive: Begin with minimal permissions and add as needed
2. Use Patterns: Leverage specific patterns rather than broad allows
3. Deny Dangerous Commands: Always deny commands like rm -rf, sudo, etc.
4. Protect Sensitive Files: Deny access to .env, private keys, credentials
5. Regular Audits: Review permissions periodically for your projects
6. Environment Separation: Use different permission sets for dev/staging/prod

Todo Management Best Practices

When allowing TodoRead/TodoWrite:

• OpenAI Codex will automatically track tasks and progress
• Todos are shared between main conversation and Task agents
• Mark todos complete immediately after finishing tasks
• Use detailed todo lists for complex multi-step projects

References

• Official OpenAI Codex Settings Documentation
• OpenAI Codex Security Guide
• OpenAI Codex CLI Reference