FAQ

Installation and authentication

Empty model list during /login

If you see "No models available for the selected platform" error when running the /login (or /setup) command, it may be due to:

• Invalid or expired API key: Check if your API key is correct and still valid.
• Network connection issues: Confirm you can access the API service addresses (such as api.pythinker.com or api.pythinker-ai.cn).

Invalid API key

Possible reasons for an invalid API key:

• Key input error: Check for extra spaces or missing characters.
• Key expired or revoked: Confirm the key status in the platform console.
• Environment variable override: Check if PYTHINKER_API_KEY or OPENAI_API_KEY environment variables are overriding the key in the config file. You can run echo $PYTHINKER_API_KEY to check.

Membership expired or quota exhausted

If you're using the Pythinker platform, you can check your current quota and membership status with the /usage command. If the quota is exhausted or membership expired, you need to renew or upgrade at Pythinker.

Interaction issues

cd command doesn't work in shell mode

Executing the cd command in shell mode won't change Pythinker Code's working directory. This is because each shell command executes in an independent subprocess, and directory changes only take effect within that process.

If you need to change working directory:

• Exit and restart: Run the pythinker command again in the target directory.
• Use --work-dir flag: Specify working directory at startup, like pythinker --work-dir /path/to/project.
• Use absolute paths in commands: Execute commands with absolute paths directly, like ls /path/to/dir.

Image paste fails

When using Ctrl-V to paste an image, if you see "Current model does not support image input", it means the current model doesn't support image input.

Solutions:

• Switch to an image-capable model: Use a model that supports the image_in capability.
• Check clipboard content: Make sure the clipboard contains actual image data, not just a file path to an image.

Working directory deleted or removed

If the working directory becomes inaccessible during a session (external drive unplugged, directory deleted, or filesystem unmounted), Pythinker Code detects the situation and displays a crash report containing the session ID and work directory path, then exits cleanly. You can recover the session with pythinker -r <session-id> from the correct directory.

ACP issues

IDE cannot connect to Pythinker Code

If your IDE (like Zed or JetBrains IDEs) cannot connect to Pythinker Code, check the following:

• Confirm Pythinker Code is installed: Run pythinker --version to confirm successful installation.
• Check configuration path: Ensure the Pythinker Code path in IDE configuration is correct. You can typically use pythinker acp as the command.
• Check uv path: If installed via uv, ensure ~/.local/bin is in PATH. You can use an absolute path like /Users/yourname/.local/bin/pythinker acp.
• Check logs: Examine error messages in ~/.pythinker/logs/pythinker.log.

MCP issues

MCP server startup fails

After adding an MCP server, if tools aren't loaded or there are errors, it may be due to:

• Command doesn't exist: For stdio type servers, ensure the command (like npx) is in PATH. You can configure with an absolute path.
• Configuration format error: Check if ~/.pythinker/mcp.json is valid JSON. Run pythinker mcp list to view current configuration.

Debugging steps:

# View configured servers
pythinker mcp list

# Test if server is working
pythinker mcp test <server-name>

OAuth authorization fails

For MCP servers that require OAuth authorization (like Linear), if authorization fails:

• Check network connection: Ensure you can access the authorization server.
• Re-authorize: Run pythinker mcp auth <server-name> to authorize again.
• Reset authorization: If authorization info is corrupted, run pythinker mcp reset-auth <server-name> to clear it and retry.

Header format error

When adding HTTP type MCP servers, header format should be KEY: VALUE (with a space after the colon). For example:

# Correct
pythinker mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: your-key"

# Wrong (missing space or using equals sign)
pythinker mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY=your-key"

Print/Wire mode issues

Invalid JSONL input format

When using --input-format stream-json, input must be valid JSONL (one JSON object per line). Common issues:

• JSON format error: Ensure each line is a complete JSON object without syntax errors.
• Encoding issues: Ensure input uses UTF-8 encoding.
• Line ending issues: Windows users should check if line endings are \n rather than \r\n.

Correct input format example:

{"role": "user", "content": "Hello"}

No output in print mode

If there's no output in --print mode, it may be:

• No input provided: You need to provide input via --prompt (or --command) or stdin. For example: pythinker --print --prompt "Hello".
• Output is buffered: Try using --output-format stream-json for streaming output.
• Configuration incomplete: Ensure API key and model are configured via /login.

Updates and upgrades

macOS slow first run

macOS's Gatekeeper security mechanism checks new programs on first run, causing slow startup. Solutions:

• Wait for check to complete: Be patient on first run; subsequent launches will return to normal.
• Add to Developer Tools: Add your terminal application in "System Settings → Privacy & Security → Developer Tools".

How to upgrade Pythinker Code

Run the built-in updater from any install method:

pythinker update

Inside the interactive shell, use /update. Pythinker checks the matching channel for your install (native installer, Homebrew, or PyPI) before offering the update.

Update notice on startup

Startup is non-blocking. When a newer installable version is detected by the background check, Pythinker Code shows a short update notice in the shell; run /update when you are ready.

How to disable update reminders

If you don't want Pythinker Code to check for updates or show startup update notices, set the environment variable:

export PYTHINKER_CLI_NO_AUTO_UPDATE=1

This disables background update checks and startup update notices. You can add this line to your shell configuration file (like ~/.zshrc or ~/.bashrc).